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

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.For more information, head to the Channel Merging Guide.

This API calculates the expected cashback points but does not perform any actual reward or action for the customer.

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.

lineItems object

productId string Optional Unique identifier for the product or service being purchased.

quantity float Optional Number of units purchased for this product or service.

price float Optional 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.

sku string Optional Stock Keeping Unit (SKU) for the product.

tags array Optional Tags associated with the product for categorization or promotional purposes.

category array Optional Product category, such as fashion or electronics. It can include one or multiple categories. Example: ["natural", "cosmetics"]

weight float Optional Weight of the product.

vendor string Optional Vendor or manufacturer of the product.

collection array Optional Collection ID(s) to which the product belongs. It can include one or multiple collections. Example: ["14313", "4343"]

title string Optional Product title or name.

taxes float Optional 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.

discount float Optional 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.

extra object Optional 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.

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.

merchant object

uniqueId string Optional Unique identifier for the merchant.

name string Optional Name of the merchant.

branch.uniqueId string Optional Unique identifier for the branch where the order took place.

branch.name string Optional Name of the branch where the order 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.

lineItems object

campaignId number The unique identifier for the active transactional campaign that affects the cashback reward for purchasing this line item. If no campaign is applicable, this field will be null.

campaignName string The name of the active transactional campaign that affects the cashback reward for purchasing this line item. If no campaign is applicable, this field will be null.

Example: If a store is running a "Double Points Weekend" campaign, the campaignName could be "Double Points Weekend."

campaignEndDate string The end date of the active campaign affecting the line item.This is the date when the campaign will no longer influence points or rewards.

campaignImpactWalletFactor number The multiplier applied by the campaign to the base points calculation. This factor adjusts the final points earned for the line item based on the campaign's impact. Present only if a campaign is applicable.

Example: If the campaign offers 3x points, the campaignImpactWalletFactor would be 3, multiplying the regular points earned by three.

campaignImpactPoints number The total number of points given for this line item due to the campaign's impact. This value reflects the additional points earned from the campaign.

Example: If the base points for an item are 100 and the campaign offers 5x points, the campaignImpactPoints would be 400 (totaling 500 points with the base points included).

productId string Unique identifier for the product.

quantity number The quantity of the product purchased.

totalDecimalPoints number The total decimal points earned for this line item,including any campaign impact.

totalPoints number The total points earned for this line item, including any campaign impact.

Example: If the base points for a product are 50 and a campaign adds 150 points, the totalPoints would be 200.

totalScore number The total score earned for this line item.This value is separate from point and is based on your cashback rewards configuration.

rewardWalletFactor number The multiplier applied to the product price to calculate the base points earned for this line item. This factor represents how many points are earned per unit of currency spent on the product.

Example: If the store rewards 10 points for every $1 spent, the rewardWalletFactor would be 10.

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.

Transaction object

transactionDate datetime The date and time when the transaction occurred.

gameballTransactionId number Unique identifier for the transaction in the Gameball system.

transactionType string Type of transaction. Possible values include:

AchievementReward: Captured when a customer reaches a VIP tier, participates in a reward campaign, or makes a referral.
PaymentReward: Recorded for rewarding a customer with points for every placed order.
Refund: Captured when points redeemed from a refunded order are returned to the customer.
Redemption: Recorded whenever a customer redeems their points for rewards.
Expiry: Captured when a customer's points expire, indicating a reduction in their total points.
Cancel: Recorded when a customer cancels an order, leading to the deduction of rewarded points.
Migration: Captured during updates or migrations of customer data via a CSV file, reflecting added or deducted points.
ManualAccumulation: Recorded for points that are manually added to a customer's balance.
DiscountCode: Captured when a customer creates a coupon code.
ManualDeduction: Recorded for points manually removed from a customer's balance.
ManualReward: Similar to AchievementReward, but specifically for manually awarding achievements to a customer.

amount number The monetary value involved in the transaction.

transactionId string A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball.

equivalentPoints number The points equivalent to the monetary value of the 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
}

PreviousOrder Tracking NextPayment

Last updated 22 days ago