Order Rewards & History
Calculate reward points for orders and retrieve all associated transactions. These APIs provide cashback calculations and display reward, refund, and transaction details linked to specific orders.
Available APIs
POST - Calculate Order Cashback
https://api.gameball.co/api/v4/integrations/orders/cashback
This API calculates the cashback points to be rewarded for a specific order in Gameball, based on provided order details. It considers configured cashback rules and customer eligibility.
Security: Requires apiKey header
Request
Body
application/json
customerId string
Optional
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.
If provided, the cashback calculation will consider the customer's tier. Special tier-based configurations, such as enhanced point accrual rates, may affect the points calculation.
email string
Optional
Customer's email address.
Note: This is required if your account uses email-based channel merging.
mobile string
Optional
Customer's mobile number.
Note: This is required if your account uses mobile-based channel merging.
totalPaid float
Required
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. This is the value used to calculate any points or rewards earned from the order.
totalPrice float
Optional
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.
totalDiscount float
Required
Total discount applied to the order. Must be positive.
totalShipping float
Required
Total shipping cost for the order.
lineItems array
Optional
An array containing details about each product in the order. If not provided, the calculation will only consider the total order values.
merchant object
Optional
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.
Sample Request
{
"customerId": "cust_12345abc",
"totalPaid": 350,
"totalPrice": 350,
"totalDiscount": 0,
"totalShipping": 0,
"lineItems": [
{
"productId": "875511",
"price": 150,
"quantity": 1,
"collection": [
"123"
],
"taxes": 0,
"discount": 0
},
{
"price": 200,
"quantity": 1,
"productSku": "sku123",
"taxes": 0,
"discount": 0
}
],
"merchant": {
"uniqueId": "MERCH001",
"name": "TechGadgetStore",
"branch": {
"uniqueId": "BRANCH001",
"name": "Downtown Branch"
}
}
}
Response
application/json
totalPoints number
Total points expected to be earned from the entire order.
totalScore number
Total score expected to be earned from the entire order.
lineItems array
An array of individual line items and their cashback calculation details.
Sample Response
{
"totalPoints": 19000,
"totalScore": 0,
"lineItems": [
{
"productId": "875511",
"quantity": 1,
"totalDecimalPoints": 15000.0,
"totalPoints": 15000,
"totalScore": 0,
"rewardWalletFactor": 20.0,
"campaignId": 2149,
"campaignName": "5x Points Campaign",
"campaignEndDate": "2024-11-01T08:39:00",
"campaignImpactWalletFactor": 5.0,
"campaignImpactPoints": 12000.0
},
{
"productId": null,
"quantity": 1,
"totalDecimalPoints": 4000.0,
"totalPoints": 4000,
"totalScore": 0,
"rewardWalletFactor": 20.0,
"campaignId": null,
"campaignName": null,
"campaignEndDate": null,
"campaignImpactWalletFactor": 0.0,
"campaignImpactPoints": 0.0
}
]
}
Key Points:
The first product (
productId
:875511
) is part of a collection affected by an active "5x Points Campaign," which multiplies the points earned for this product by a factor of 5.The
rewardWalletFactor
for both products is 20, meaning the product price is multiplied by 20 to calculate the base points earned.The
campaignImpactPoints
for the first product reflect the additional points awarded due to the active campaign.
GET - Order Transactions
https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/transactions
This API retrieves the transactional details for a specified order in Gameball, identified by orderId
. It includes information on rewards, refunds, and equivalent points, giving a detailed view of the financial activities associated with the order.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
orderId string
Required
Unique identifier for the order, which is case-sensitive. It is used to reference and retrieve the order's transactions accurately.
Response
application/json
transactions array
List of transactions associated with the order.
Example: If a customer places an order and redeems points, the transactions
array will contain both the cashback reward transaction and the redemption transaction.
count number
Total number of transactions associated with the order.
Sample Response
{
"transactions": [
{
"transactionDate": "2024-10-16T08:13:29.29",
"gameballTransactionId": 11034754,
"transactionType": "PaymentReward",
"amount": 250.75,
"transactionId": "ORD12345",
"equivalentPoints": 192.0
}
],
"count": 1
}
Last updated