Skip to main content

​
Overview

When a coupon is validated and locked, it becomes temporarily unavailable for others (or the same user) to redeem.
If the order fails, payment doesn’t go through, or the customer abandons checkout, those locked coupons should be released to make them reusable. That’s where the Release Coupons API comes in; it reverts the coupon status from locked to available.

​
Why This Matters

Coupon locking ensures discounts are held during checkout to prevent misuse or concurrent redemptions.
However, if these coupons remain locked after failed transactions, they can become unavailable to customers who never actually used them. Releasing them promptly:

​
When to Use It

You should call the Release Coupons API when:
ScenarioDescription
💳 Payment FailsThe transaction fails before completing checkout.
❌ Order Is CanceledThe order was canceled manually or automatically.
⏱️ Checkout TimeoutThe session expired before confirmation.
🛒 Cart AbandonedThe customer left checkout after applying a coupon.
Or wait until the configured lock timeout passes; Gameball will automatically unlock it if your system doesn’t confirm redemption in time.

​
How to Implement

Once an order fails or is canceled, call the Release Coupons API using the same lockReference that was returned during the coupon validation (or lock) phase. 
https://api.gameball.co/api/v4.0/integrations/coupons/{lockReference}

​
Example Response:

{
  "status": "success",
  "releasedAt": "2025-02-20T13:20:00Z"
  "releasedCoupons": [
    {
      "code": "SUMMER20"
    }
  ]
}

​
What Gameball Does Behind the Scenes

1

Validates the lock reference

Ensures the lock reference matches a valid, previously locked coupon session.
2

Updates coupon status

Changes coupon state from locked → available.

​
Example Use Cases

​
🛍️ E-commerce Checkout Cancellation

Scenario: Sarah applied the coupon WINTER25 but canceled the order before confirming payment. Implementation: Your system should call the Release Coupons API immediately after order cancellation. 
https://api.gameball.co/api/v4.0/integrations/coupons/lock-21c39f02-f8a3-4a7b-910e-f4c29a05be93
Result: The coupon becomes available again for future use.

​
💳 Payment Gateway Failure

Scenario: John applied FREESHIP, but his payment failed due to an expired card. Implementation: After receiving the failure callback from your payment gateway, release the locked coupon. 
https://api.gameball.co/api/v4.0/integrations/coupons/lock-47b2f1d9-12d6-4b31-91cf-8f89b3da1c9e
Result: The coupon is reactivated, and John can retry the transaction.

​
🏪 POS Transaction Reversal

Scenario: A store cashier mistakenly voids a transaction where a coupon was applied. Implementation: Call the Release Coupons API to unlock the coupon for reuse. 
https://api.gameball.co/api/v4.0/integrations/coupons/lock-82b1aa5c-8a4e-4a31-91ef-99e6b1d6cc1a
Result: The coupon is freed for the same or another customer to use later.

​
Best Practices:

Always call the Release Coupons API immediately after payment failure or cancellation.
Avoid skipping release; otherwise, coupons may appear as unavailable until their lock expires.

​
Key Takeaways

Release Coupon API

Unlock coupons after failed or canceled orders

Burn Coupon API

Mark coupons as redeemed once payment succeeds

Validate Coupon API

Confirm eligibility and lock coupons before checkout

Coupon Entity Reference

Understand coupon fields, types, and lifecycle data