> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# How Do I Track Orders and Earn Points with Gameball POS (v4)?

> Submit in-store orders to Gameball so customers earn loyalty points

Tracking orders is the core of your POS integration. Each time a customer completes a purchase, you submit the order to Gameball, which awards points based on your configured earning rules and triggers any relevant campaigns or tier progression. Without this call, no points are earned.

This page documents the `/integrations/orders` endpoint, which every other earning and redemption flow builds on.

## Submit an Order

After payment is confirmed, send the order to Gameball:

```bash cURL theme={null}
curl -X POST 'https://api.gameball.co/api/v4.0/integrations/orders' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'SecretKey: YOUR_SECRET_KEY' \
  -d '{
    "customerId": "12345",
    "orderId": "ORD000123",
    "orderDate": "2025-10-19T12:10:00Z",
    "totalPaid": 100.00,
    "totalPrice": 100.00,
    "totalDiscount": 0,
    "totalTax": 2.00,
    "totalShipping": 0
  }'
```

```json Success theme={null}
{
  "orderId": "ORD000123",
  "customerId": "12345",
  "pointsEarned": 10,
  "rewardedPoints": 10,
  "status": "completed"
}
```

> [!NOTE]
>
> This is the **basic earn flow** with no redemption. To let customers spend points on this order, see [Redeem Points at Checkout](https://docs.gameball.co/installation-guides/v4/pos/integrate-redemption.md), which adds a hold step before this same call.

## Request Fields

**customerId** `string` *required*

Unique identifier for the customer. See [Choosing Your Customer ID](https://docs.gameball.co/installation-guides/v4/pos/getting-started.md#choosing-your-customer-id).

**orderId** `string` *required*

A unique transaction ID from your POS. Must be unique per store environment, duplicates are rejected.

**orderDate** `string` *required*

The time the order occurred, in ISO 8601 format.

**totalPaid** `number` *required*

Amount paid by the customer after discounts and redemptions.

**totalPrice** `number` *required*

Full value of the order before any discounts.

**totalTax** `number`

Tax portion of the order. Include if it affects point calculation.

**totalShipping** `number`

Shipping portion of the order, if applicable.

## Response Fields

**rewardedPoints** `number`

Points awarded for this order. Display this to the customer to show what they earned.

**pointsEarned** `number`

Points earned based on the transaction value and your earning rules.

**status** `string`

Order processing status, for example `completed`.

> [!NOTE]
>
> **Behind the scenes**, Gameball evaluates your earning rules against the transaction value, issues points accordingly, logs the order in the customer's purchase history, and may trigger campaign or tier logic based on cumulative spend.

> [!NOTE]
>
> **Automatic customer creation**: If the `customerId` doesn't exist yet, Gameball creates the profile automatically when you track the order, no separate create call required.

## Tips & Gotchas

* Submit final prices with tax and shipping if they affect point logic.
* Use ISO 8601 timestamps for `orderDate`.
* Never reuse an `orderId`, duplicates are rejected.
* Track the order after payment is confirmed but before closing the POS session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.