> ## 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.

# Track Orders & Earn Points

> 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:

<RequestExample>
  ```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
    }'
  ```
</RequestExample>

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

<Note>
  This is the **basic earn flow** with no redemption. To let customers spend points on this order, see [Redeem Points at Checkout](/installation-guides/v3/pos/integrate-redemption), which adds a hold step before this same call.
</Note>

## Request Fields

<ParamField body="customerId" type="string" required>
  Unique identifier for the customer. See [Choosing Your Customer ID](/installation-guides/v3/pos/getting-started#choosing-your-customer-id).
</ParamField>

<ParamField body="orderId" type="string" required>
  A unique transaction ID from your POS. Must be unique per store environment, duplicates are rejected.
</ParamField>

<ParamField body="orderDate" type="string" required>
  The time the order occurred, in ISO 8601 format.
</ParamField>

<ParamField body="totalPaid" type="number" required>
  Amount paid by the customer after discounts and redemptions.
</ParamField>

<ParamField body="totalPrice" type="number" required>
  Full value of the order before any discounts.
</ParamField>

<ParamField body="totalTax" type="number">
  Tax portion of the order. Include if it affects point calculation.
</ParamField>

<ParamField body="totalShipping" type="number">
  Shipping portion of the order, if applicable.
</ParamField>

## Response Fields

<ResponseField name="rewardedPoints" type="number">
  Points awarded for this order. Display this to the customer to show what they earned.
</ResponseField>

<ResponseField name="pointsEarned" type="number">
  Points earned based on the transaction value and your earning rules.
</ResponseField>

<ResponseField name="status" type="string">
  Order processing status, for example `completed`.
</ResponseField>

<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>

<Info>
  **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.
</Info>

## 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.