Coupons & Deals
A catalogue of merchant offers that your users unlock by spending the coins or points they already earn in your app. You build the storefront; Cheggout supplies the inventory and delivers the coupon.
Available Headless API · TBD Hosted
The problem it solves
Loyalty programmes accumulate liabilities. Points sit unspent, which is bad for engagement and awkward on the balance sheet. A rewards store gives points somewhere to go — but sourcing merchant inventory, managing coupon pools and handling redemption is a business most publishers do not want to be in.
This module supplies the inventory and the fulfilment. You keep the wallet, the storefront and the customer relationship.
What you get
- A catalogue of offers with imagery, terms, pricing in coins and redemption instructions
- Live inventory so you never sell something that has run out
- Coupon delivery with an idempotent, reconcilable contract
- Per-user purchase limits enforced by the platform
- Free offers alongside paid ones —
amount: 0costs no coins
What stays yours
The coin economy is entirely yours. Cheggout has no wallet API, does not hold balances and does not know what a coin is worth. You burn coins; Cheggout delivers a coupon.
This is a deliberate boundary. It means you can price offers however you like, run promotions on your own terms, and change your points economics without a Cheggout release.
Architecture
The journey
The prescribed ordering
This ordering is not optional. Delivering a coupon before the burn is committed lets a user obtain inventory without paying. Leaving a burn without either a coupon or a refund takes the user's coins and gives nothing back.
Every failure path — and there are seven documented ones — must end in a retry with the same
extTransactionId, or a refund.
See Coupon delivery for the full error handling.
Identifiers
| Identifier | Owner | Purpose |
|---|---|---|
virtualId | You | The user. Pseudonymous, immutable, no personal data. |
extTransactionId | You | Unique per claim. Idempotency and reconciliation key. |
orderId | Cheggout | The delivery record — see the caveat below |
TBD The contract describes orderId as the authoritative delivery record, but its
presence in the delivery response is unconfirmed. Reconcile on your own extTransactionId,
which is reliably echoed back.
Caching
The catalogue is not user-specific, which makes it the easiest performance win in the whole platform.
Scheduled refresh ──► getCatalogue ──► your cache ──► your storefront
Before buy CTA ──► getCatalogueInventory (180s TTL) ──► enable or disable
Never call Cheggout on a page view. Only inventory needs to be fresh, and it tells you how long it stays valid. See Catalogue.
Integration complexity
| Aspect | Effort |
|---|---|
| Authentication | Low — an API key header, no signing |
| Catalogue and caching | Low |
| Coin burn and refund | Medium to high — this is where the care goes |
| Storefront | Yours to build |
| Reconciliation | Medium — worth doing properly from day one |
Roughly two weeks for the integration, plus your storefront. The burn-and-refund logic deserves more of that time than the API calls do.
Before you start
- API key and secret issued
- Egress IPs whitelisted
- Your coin wallet supports atomic burn and refund
- A delivery ledger keyed on
extTransactionId - A decision on how you map users to offer
tags
Endpoints
| Endpoint | Purpose |
|---|---|
getCatalogue | The offer catalogue — cacheable |
getCatalogueInventory | Live stock, 180s TTL |
fetchCouponCode | Deliver a coupon |
getUserCoupons | A user's coupons for an offer |
| Coupon status webhook | You host this |
Next
- Catalogue — loading, caching and targeting.
- Coupon delivery — the purchase flow.
- My Coupons — history and invalidation.