Skip to main content

​
Apply Promos Automatically

Gameball’s Automatic Promo API lets you apply valid, active promotions directly to a customer’s order, without requiring them to enter a promo code.
This helps you deliver a seamless checkout experience, where promotions are evaluated, matched, and applied automatically based on the order’s details and customer profile.

​
Why This Matters

Manual coupon entry can interrupt the checkout experience and lead to missed redemptions.
With automatic promos, Gameball determines which active offers apply to the order — such as spend thresholds, collection-based rules, or loyalty tier discounts — and applies them instantly. This ensures:
  • 💡 Frictionless checkout: Customers see eligible discounts automatically.
  • 🎯 Personalized offers: Gameball evaluates each customer’s eligibility in real time.
  • 🔁 Consistent rule enforcement: Prevents stacking or invalid promo combinations.
  • 📊 Accurate tracking: Discounts and rewards are logged and attributed properly in analytics.

​
When to Use It

You should call this API when:
ScenarioDescription
🛒 Checkout PageYou want Gameball to automatically apply all valid promotions based on cart contents.
🏪 POS CheckoutIn-store checkout flow where customers don’t manually enter promo codes.
💳 Payments or Fintech Use CasesYou want Gameball to automatically apply discounts or cashback promos to bill payments or wallet top-ups.

​
How It Works

When you call the Automatic Coupons API, you send the order payload (like you would in the Calculate Cashback API). Gameball then:
  1. Evaluates the order against all active promotions configured in your workspace.
  2. Filters the ones that match the criteria (e.g., collections, minimum spend, customer tier).
  3. Returns the best applicable promotions, including discount details, type, and value.

​
Example Request

{
  "customerId": "CUST_987",
  "orderId": "ORDER_2025_001",
  "totalPaid": 200,
  "totalPrice": 200,
  "totalShipping": 10,
  "totalTax": 5,
  "lineItems": [
    {
      "productId": "TSHIRT_001",
      "price": 50,
      "quantity": 2,
      "collection": ["Apparel"]
    },
    {
      "productId": "BAG_002",
      "price": 100,
      "quantity": 1,
      "collection": ["Accessories"]
    }
  ],
    "merchant": {
    "uniqueId": "<string>",
    "name": "<string>",
    "branch": {
      "uniqueId": "<string>",
      "name": "<string>"
    }
  },
  "channel": "web"
}

​
Example Response

{
  "isApplied": true,
  "couponName": "SPRINGSALE20",
  "discountAmount": 50,
  "discountType": "free_shipping",
  "discountedItems": [
    {
      "productId": "TSHIRT_001",
      "quantity": 2,
      "discount": 20,
      "price": 50
    },
    {
      "productId": "BAG_002",
      "quantity": 1,
      "discount": 30,
      "price": 100
    }
  ]
}

​
Understanding the Response

FieldDescription
isAppliedIndicates whether a promotion was successfully applied.
couponNameThe name of the automatically applied promotion.
discountAmountTotal discount applied to the order.
discountTypeType of discount — can apply to product price, shipping, or total.
discountedItemsArray listing affected products, their quantities, discount values, and original prices.

​
Example Scenarios

​
🛍️ 1. E-commerce Auto Promo at Checkout

Scenario: Sarah adds $200 worth of items to her cart. Gameball detects that she qualifies for the “SPRINGSALE20” promotion, which offers free shipping and $50 total savings.
Implementation: When Sarah proceeds to checkout, your system calls the Automatic Promos API before payment.
Result: 
{
  "isApplied": true,
  "couponName": "SPRINGSALE20",
  "discountAmount": 50,
  "discountType": "free_shipping",
  "discountedItems": [
    {
      "productId": "TSHIRT_001",
      "quantity": 2,
      "discount": 20,
      "price": 50
    },
    {
      "productId": "BAG_002",
      "quantity": 1,
      "discount": 30,
      "price": 100
    }
  ]
}
The discount is applied automatically, and the final checkout total is adjusted accordingly.

​
💳 2. Fintech Wallet Top-Up Discount

Scenario: Omar tops up his digital wallet with $100. A promo rule grants 5% cashback on top-ups over $50. Implementation: Before confirming payment, call the Automatic Coupons API with the transaction details. Response: 
{
  "isApplied": true,
  "couponName": "TOPUP5",
  "discountAmount": 5,
  "discountType": "percentage_discount",
  "discountedItems": []
}
Gameball applies the 5% discount automatically; no promo code required.

​
What Gameball Does Behind the Scenes

1

Checks all active promotions in your workspace.

2

Evaluates eligibility based on order details and customer profile.

3

Applies all matching promotions automatically.

4

Returns final discount details and affected items.

​
Implementation Tips

​
Error Handling

If isApplied is false, it means:
You should proceed with the normal checkout flow without applying discounts.

​
What’s Next

After applying promotions automatically:

​
Key Takeaways

Automatic Coupons API

Trigger automatic promo evaluation during checkout

Validate Coupon API

Confirm eligibility before applying auto promos

Burn Promo Tutorial

Finalize promotions after successful payment

Display Promotions Tutorial

Show customers which promos applied automatically