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:

Scenario	Description
🛒 Checkout Page	You want Gameball to automatically apply all valid promotions based on cart contents.
🏪 POS Checkout	In-store checkout flow where customers don’t manually enter promo codes.
💳 Payments or Fintech Use Cases	You 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:

Evaluates the order against all active promotions configured in your workspace.
Filters the ones that match the criteria (e.g., collections, minimum spend, customer tier).
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

Field	Description
`isApplied`	Indicates whether a promotion was successfully applied.
`couponName`	The name of the automatically applied promotion.
`discountAmount`	Total discount applied to the order.
`discountType`	Type of discount — can apply to product price, shipping, or total.
`discountedItems`	Array listing affected products, their quantities, discount values, and original prices.

Example Scenarios

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

Checks all active promotions in your workspace.

Evaluates eligibility based on order details and customer profile.

Applies all matching promotions automatically.

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

Getting Started

General

Experiences

More

Automatic Promos

Apply Promos Automatically

Why This Matters

When to Use It

How It Works

Example Request

Example Response

Understanding the Response

Example Scenarios

💳 2. Fintech Wallet Top-Up Discount

What Gameball Does Behind the Scenes

Implementation Tips

Error Handling

What’s Next

Key Takeaways

Automatic Coupons API

Validate Coupon API

Burn Promo Tutorial

Display Promotions Tutorial

​Apply Promos Automatically

​Why This Matters

​When to Use It

​How It Works

​Example Request

​Example Response

​Understanding the Response

​Example Scenarios

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

​💳 2. Fintech Wallet Top-Up Discount

​What Gameball Does Behind the Scenes

​Implementation Tips

​Error Handling

​What’s Next

​Key Takeaways

​Related Resources

Automatic Coupons API

Validate Coupon API

Burn Promo Tutorial

Display Promotions Tutorial

Apply Promos Automatically

Why This Matters

When to Use It

How It Works

Example Request

Example Response

Understanding the Response

Example Scenarios

🛍️ 1. E-commerce Auto Promo at Checkout

💳 2. Fintech Wallet Top-Up Discount

What Gameball Does Behind the Scenes

Implementation Tips

Error Handling

What’s Next

Key Takeaways

Related Resources