> ## 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.
# Order Tracking
> Create orders in Gameball to award points for customer purchases.
Create orders in Gameball to award points for customer purchases. This API is used to track orders and reward customers for their completed purchases.
Security: Provide both `apikey` and `secretkey` headers.
**Automatic Customer Creation**: If the customer specified by `customerId` doesn't exist in Gameball, a new customer profile will be automatically created when using this API. You don't need to create the customer separately before tracking orders.
## OpenAPI
````yaml POST /api/v4.0/integrations/orders
openapi: 3.1.0
info:
title: Gameball API
description: >-
Gameball REST API v4.0 - Complete API reference for integrating loyalty,
gamification, and customer engagement features
version: 4.0.0
servers:
- url: https://api.gameball.co
security:
- bearerAuth: []
paths:
/api/v4.0/integrations/orders:
post:
tags:
- Orders
summary: Track Order
description: >-
The API call is used to track a new order and is specifically designed
for e-commerce solutions. It helps capture essential order details,
enabling better tracking of customer purchases and order management.
**Security:** Requires both `apikey` and `secretkey` headers.
**Channel Merging Available:** If your system uses different customer
IDs across multiple channels (e.g., online and offline), Gameball's
channel merging feature helps unify customer profiles. By including the
customer's mobile number or email (based on your merging configuration)
with each request, Gameball will combine activities into a single
profile.
operationId: trackOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerId
- orderId
- orderDate
- totalPaid
properties:
customerId:
type: string
description: >-
Unique identifier for the customer that you can reference
across the customer's whole lifetime. Could be a database
ID, random string, email or anything that uniquely
identifies the customer.
example: cust_123456789
email:
type: string
description: >-
Customer's email address. **Note:** This is required if your
account uses email-based channel merging.
example: john.doe@example.com
mobile:
type: string
description: >-
Customer's mobile number. **Note:** This is required if your
account uses mobile-based channel merging.
example: '+1234567890'
orderId:
type: string
description: >-
Unique identifier for the order on your system. This ID is
case-sensitive.
example: ORD12345
orderDate:
type: string
format: date-time
description: Timestamp of when the order was placed.
example: '2024-10-16T08:13:29.290Z'
totalPaid:
type: number
description: >-
The actual amount paid by the customer for the order,
accounting for any discounts or coupons applied. Unlike
`totalPrice`, which reflects the original cost of the order,
`totalPaid` represents the final amount the customer paid at
checkout after all adjustments. This value is used for
reward calculations in Gameball to determine the points or
benefits earned from the order. **Example:** A customer
purchases items worth $120, including taxes and shipping. If
a $20 coupon is applied, the `totalPaid` becomes $100,
reflecting the discounted amount the customer paid.
example: 250.75
totalPrice:
type: number
description: >-
The total cost of the order, including all item prices,
shipping, taxes, and tips. This value does not account for
any discounts or coupons applied and is not used for
calculations in Gameball; it is solely saved as historical
data linked to the order. Must be a positive value.
**Example:** A customer purchases items worth $120,
including taxes and shipping. Even if a $20 coupon is
applied, the totalPrice remains $120 as it represents the
original cost of the order before any discounts are applied.
example: 300
totalDiscount:
type: number
description: Total discount applied to the order.
example: 50
totalShipping:
type: number
description: Total shipping cost associated with the order.
example: 10
totalTax:
type: number
description: Total tax amount for the order.
example: 15
lineItems:
type: array
description: >-
An array containing details about each product in the order.
If not provided, the calculation will only consider the
total order values.
items:
type: object
properties:
productId:
type: string
description: >-
Unique identifier for the product or service being
purchased.
example: PROD98765
quantity:
type: number
description: Number of units purchased for this product or service.
example: 2
price:
type: number
description: >-
The original price of a single product before any tax
or discount is applied. This reflects the cost of one
unit of the item, not the total for multiple
quantities in an order. **Example:** If the original
price of a product is $50 and a customer buys two
units, the price for each item would still be recorded
as $50, regardless of quantity.
example: 100
sku:
type: string
description: Stock Keeping Unit (SKU) for the product.
example: SKU98765
tags:
type: array
items:
type: string
description: >-
Tags associated with the product for categorization or
promotional purposes.
example:
- electronics
- smartphone
category:
type: array
items:
type: string
description: >-
Product category, such as fashion or electronics. It
can include one or multiple categories.
example:
- mobile phones
weight:
type: number
description: Weight of the product.
example: 0.5
vendor:
type: string
description: Vendor or manufacturer of the product.
example: TechVendor
collection:
type: array
items:
type: string
description: >-
Collection ID(s) to which the product belongs. It can
include one or multiple collections.
example:
- latest gadgets
title:
type: string
description: Product title or name.
example: Smartphone XYZ
taxes:
type: number
description: >-
The total amount of taxes applied to the line item,
expressed in the shop's currency. This amount must be
positive and reflects the total taxes based on the
quantity of the item.
example: 7.5
discount:
type: number
description: >-
The total discount applied to this line item,
expressed as a positive value. This amount should
reflect the total discounts based on the quantity of
the item.
example: 25
extra:
type: object
additionalProperties: true
description: >-
Key-value pairs containing any extra information about
the product, such as size, color, or other custom
attributes. The values must be of type string or
number.
example:
subClass: SUBCLASS123
redemption:
type: object
description: >-
Redemption details for the order, including points held for
redemption.
properties:
pointsHoldReference:
type: string
description: >-
Reference from the Hold Points API for redeeming held
points. For more details on how hold references are
generated and utilized, refer to the Transactions
section.
example: HOLD123
couponsLockReference:
type: string
description: >-
The lock reference for the coupon is a unique identifier
used to 'lock' a coupon for a specific customer or
order. This prevents the coupon from being used by
others or on multiple transactions. For more details on
how to generate and use lock references, refer to the
Coupons section.
example: LOCK123
couponCodes:
type: array
items:
type: string
description: >-
A list of coupon codes that were applied to the order.
Each code in the array represents a different discount
or promotional coupon used during the checkout process.
Coupon codes must be locked before they can be used for
redemption.
example:
- DISCOUNT10
extra:
type: object
additionalProperties: true
description: >-
Key-value pairs containing any extra information about the
order. The values must be of type string or number.
**Example:** If your business offers gift options, you might
want to include a personalized gift message with the order.
Additionally, specific delivery instructions can be recorded
to ensure smooth delivery and provide a personalized
experience.
example:
paymentMethod: CREDIT CARD
merchant:
type: object
description: >-
This object contains details about the specific merchant
involved in the transaction, which is particularly important
for businesses managing multiple merchants or branches under
the same Gameball account. This object can provide
identifying information about both the main merchant and any
associated branch where the transaction took place.
properties:
uniqueId:
type: string
description: Unique identifier for the merchant.
example: MERCH001
name:
type: string
description: Name of the merchant.
example: TechGadgetStore
branch:
type: object
description: Branch information where the order took place.
properties:
uniqueId:
type: string
description: >-
Unique identifier for the branch where the order
took place.
example: BRANCH001
name:
type: string
description: Name of the branch where the order took place.
example: Downtown Branch
guest:
type: boolean
description: >-
Indicates whether the customer is a guest (not signed up).
Set this to `true` for guest users; otherwise, they are
treated as registered customers by default.
default: false
example: false
channel:
type: string
enum:
- mobile
- pos
- web
- callcenter
description: >-
The channel through which the order was placed helps track
the origin of the order, particularly useful for systems
that support multiple sales or communication channels. By
identifying the channel, you can gain valuable insights into
customer behavior, optimize channel-specific strategies, and
ensure efficient handling of orders across platforms.
**Possible values:** `mobile` - The order was placed through
your mobile application. `pos` - The order was placed in
person using a Point of Sale (POS) system, such as at a
physical store or outlet. `web` - The order was placed
through your website. `callcenter` - The order was placed
over the phone by contacting a customer service
representative or a call center.
example: pos
cartId:
type: string
description: Identifier for the shopping cart associated with the order.
example: CART98765
cashbackConfigurations:
type: object
description: >-
This object contains configurations related to the cashback
settings.
properties:
returnWindow:
type: integer
description: >-
The number of days the cashback will stay in a
**pending** state, typically aligning with the return
window in e-commerce to account for potential order
cancellations or refunds. The value should be between
**0 and 7,300 days (20 years)**.
minimum: 0
maximum: 7300
example: 7
responses:
'200':
description: Order tracked successfully
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
description: >-
Unique identifier for the customer that you can reference
across the customer's whole lifetime. Could be a database
ID, random string, email or anything that uniquely
identifies the customer.
example: cust_123456789
redeemedPoints:
type: number
description: >-
Points redeemed by the customer for this order, if
applicable. **Example:** If a customer has accumulated 500
points and decides to redeem 100 points for a discount on
their current order, the `redeemedPoints` value for that
transaction will be 100. This helps track how many points
were used in the transaction and what benefits were
applied to the order based on the customer's redeemed
points.
example: 1000
rewardedPoints:
type: number
description: >-
The total number of points rewarded to the customer for
making this order. These points are typically awarded
based on your configured cashback rewards. **Example:** If
the store rewards 10 points for every $1 spent, and a
customer places an order worth $50, the **rewardedPoints**
for this order would be 500 points.
example: 101
lineItems:
type: array
description: >-
Details about each product or service in the order,
including points rewarded.
items:
type: object
properties:
productId:
type: string
description: Unique identifier for the product or service.
example: PROD98765
quantity:
type: number
description: >-
Number of units purchased for this product or
service.
example: 2
decimalPoints:
type: number
description: Fractional points rewarded for this line item.
example: 91.25
points:
type: number
description: Any points rewarded for this line item.
example: 91
score:
type: number
description: Any score awarded for the line item, if applicable.
example: 0
security:
- apiKey: []
secretKey: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
secretKey:
type: apiKey
in: header
name: secretkey
````