Skip to main content

​
Burn API

After a promotion is validated and applied, its redemption flow isn’t complete until it’s burned.
This final step confirms that the promotion was successfully used, ensuring it cannot be reused and that your analytics, limits, and reward logic remain accurate. Burning a promotion finalizes its lifecycle inside Gameball’s Promo Engine by marking it as used, ensuring transparent tracking and reliable customer data.

​
Overview

In Gameball’s Promo Engine, the Burn API serves as the final confirmation step that marks a promotion as redeemed after a successful order or payment. You should call this API once the transaction is successfully completed, such as when: If the transaction fails, gets canceled, or times out, use the Release API instead to free the locked promotion.

​
Before You Burn: Validate First

Before any promotion can be finalized (burned), it must first be validated using the
Validate API. This validation step is essential because it:
1

Confirms eligibility

Ensures the promotion is active and applicable to the customer, transaction, and cart context.
2

Generates a lock reference

Returns a unique lockReference; this must be included in all burn or order redemption requests.
Always validate promotions just before checkout. Use the returned lockReference when:
  • Calling the Burn API after successful payment, or
  • Sending the Order API with couponsLockReference for automatic burning.
If you skip validation or use an expired lockReference the burn or redemption request will fail, and the promotion won’t apply.

​
When and Where to Use It

ChannelExample Use
🛍️ E-commerceFinalize a 10% off promotion after successful checkout.
🏪 POS (Retail)Confirm an in-store promotion once the sale is processed.
💳 Fintech / PaymentsApply and finalize promotional discounts on payments, bills, or services.

​
Use Case 1: Burn Promotion After Checkout

​
Scenario

After Sarah completes her order using the WEEKEND10 promotion, the payment gateway confirms success. Your backend must now finalize the promotion redemption to ensure it cannot be reused.

​
How to Implement

Once the payment is confirmed, call the Burn API with:
  • customerId: the customer’s unique identifier
  • code(s): the applied promotion code(s), this is shared as a path parameter
  • lockReference: the lock reference from the validation step

​
Example Request

{
  "customerId": "CUST_1123",
  "promotionCodes": ["WEEKEND10"],
  "couponsLockReference": "lock-47bc79a1-c4b3-4a77-8b61-f9a32f9ef98a"
}

​
Example Response

{
  "status": "success",
  "burnedPromotions": [
    {
      "code": "WEEKEND10",
      "burnedAt": "2025-03-10T15:20:00Z",
      "discountType": "percentage_discount",
      "discountValue": 10
    }
  ]
}

​
Use Case 2: Apply & Burn a Promotion via the Order API

​
Scenario

For a smoother checkout, you can finalize promotions automatically when creating an order. Prerequisite: the promotion must first be validated using the Validate Promotion API to obtain the couponsLockReference

​
Flow

1

Validate the promotion

Call the Validate API with the promotion code and customer data. The response includes a lockReference that temporarily locks this promotion for checkout.
2

Submit the order (auto-burn)

Send the Order API request, including the couponsLockReference. Once the order succeeds, Gameball automatically burns the promotion.
3

If payment fails or order is canceled

Use the Release API to unlock the promotion for reuse. Or wait until the configured lock duration expires.

​
Example Flow

​
Step 1: Validate the Promotion

// POST /integrations/coupons/{code}/validate
{
  "customerId": "CUST_4412"
}

​
Response:

{
  "status": "valid",
  "lockReference": "lock-47bc79a1-c4b3-4a77-8b61-f9a32f9ef98a"
}

​
Step 2: Create Order (Auto-Burn)

// POST /integrations/orders
{
  "customerId": "CUST_4412",
  "orderId": "ORD_9001",
  "totalPaid": 250.0,
  "orderDate": "2025-03-10T12:45:00Z",
  "redemption": {
    "couponsLockReference": "lock-47bc79a1-c4b3-4a77-8b61-f9a32f9ef98a"
  },
  "lineItems": [
    { "productId": "TSH001", "price": 125.0, "quantity": 2 }
  ]
}
When an order is successfully processed, the associated promotion is automatically burned; no manual Burn API call required.

​
Use Case 3: Payment-Based Promotion (Fintech or Subscriptions)

​
Scenario

A fintech app offers a SAR 25 promotion on wallet top-ups using the PAYBILL25 promotion code. After confirming the transaction, the app must burn the promotion to finalize it.

​
How to Implement

Once validation and payment success are confirmed, call the Burn API as follows: 
{
  "customerId": "USER_902",
  "lockReference": "lock-8c34d2a1-c8e0-4a9b-9317-2a9bfc1dc728"
}

​
Response:

{
  "success": true,
  "burnedAt": "2023-11-07T05:31:56Z"
}

​
Best Practice

Burn Coupon API

Final confirmation step for coupons and promos

Release Coupon API

Unlock promotions when checkout fails

Validate Coupon API

Validate and lock promos before burning them

Apply Automatic Promos

Learn how to auto-apply eligible promotions