Orders

Calculate Order Cashback

Changed on

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.

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

post/api/v4.0/integrations/orders/cashback

Request

  • Base URL: https://api.gameball.co
  • URL: https://api.gameball.co/api/v4.0/integrations/orders/cashback
  • Auth: API key in header apikey

Request body

customerIdstring

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.

emailstring

Customer's email address. Note: This is required if your account uses email-based channel merging.

mobilestring

Customer's mobile number. Note: This is required if your account uses mobile-based channel merging.

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

totalPricenumber

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.

totalDiscountnumber required

Total discount applied to the order. Must be positive.

totalShippingnumber required

Total shipping cost for the order.

Example request

{
  "customerId": "cust_12345abc",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "totalPaid": 350,
  "totalPrice": 350,
  "lineItems": [
    {
      "productId": "875511",
      "quantity": 1,
      "price": 150,
      "sku": "sku123",
      "collection": [
        "123"
      ]
    }
  ],
  "merchant": {
    "uniqueId": "MERCH001",
    "name": "TechGadgetStore",
    "branch": {
      "uniqueId": "BRANCH001",
      "name": "Downtown Branch"
    }
  }
}

Response

Cashback calculated successfully

totalPointsnumber

Total points expected to be earned from the entire order.

totalScorenumber

Total score expected to be earned from the entire order.

Example response

{
  "totalPoints": 19000,
  "lineItems": [
    {
      "productId": "875511",
      "quantity": 1,
      "totalDecimalPoints": 15000,
      "totalPoints": 15000,
      "rewardWalletFactor": 20,
      "campaignId": 2149,
      "campaignName": "5x Points Campaign",
      "campaignEndDate": "2024-11-01T08:39:00",
      "campaignImpactWalletFactor": 5,
      "campaignImpactPoints": 12000
    }
  ]
}

Changes

  • 5a5238b642e9Revision changes
    • breaking

      the request property became required

    • breaking

      the request property became required

    • breaking

      the // response's property format changed from no format to date-time for status

    • warning

      the request property's min was set to 0.00

    • info

      api operation id calculateOrderCashback was added

    • info

      api tag Orders added

  • 95e7f65e5afdRevision changes
    • info

      endpoint added