eXlr8 Incentives API Documentation
The eXlr8 Incentives platform is the system of record for gift cards and coupons. Merchants configure incentive programs and issue digital instruments at scale; their customers present those instruments at checkout, and this API validates and redeems them.
This documentation covers the API client integration — the server-to-server surface your backend calls with client credentials.
Two planes, two audiences
The platform separates configuring an incentive programme from operating it. They use different credentials and are documented differently.
| Configuration plane | Operations plane | |
|---|---|---|
| Who | Merchant administrator | Your backend (API client) |
| Where | eXlr8 merchant dashboard | Your own systems, server-to-server |
| Credential | Email + password (JWT) | X-Client-Id / X-Client-Secret |
| Does what | Creates campaigns, templates and users | Issues, validates and redeems instruments |
| Covered here | As background — see Setup Flow | In full — see API Reference |
An API client cannot create campaigns, create templates, or manage users. Those are administrator actions, done once, before any integration work begins. Your integration starts at the point where a campaign is live and a template exists.
What you can do with the API
- Issue a gift card or coupon from a template — the platform generates the code and returns it once
- Inquire into a gift card by the code a customer presents — balance, status, expiry, redemption rules
- Validate a coupon against an order without consuming it — a safe dry run
- Redeem — debit a gift card balance, or consume a coupon and receive the computed discount
- Refund, void and expire gift card value through the transaction ledger
- List and retrieve instruments and transactions for reconciliation
Instrument types
Gift cards carry stored value. A card is issued with a fixed denomination, and each redemption debits the remaining balance until it is exhausted. Every movement of money is recorded as a transaction.
Coupons carry an entitlement rather than value. The platform supports three behaviours, each with its own configuration and discount maths:
| Type | Behaviour |
|---|---|
SAVE_X | A flat or percentage amount off the order, with an optional cap and minimum order value |
BUY_X_GET_Y | Buy N of certain products, get M of certain products free |
FREE_SHIPPING | Waive shipping once the order meets a threshold |
Where to start
- Setup Flow — what the merchant administrator does first, and where your credentials come from
- Authentication — the two headers on every request
- Quick Start — issue and redeem an instrument end to end
- How Redemption Works — the concepts you need before writing money-moving code
- API Reference — every endpoint, in detail
:::caution Redemption moves money Redemption is a financial operation. Before you write it, read How Redemption Works — in particular the section on idempotency keys, which is what makes a retry safe. :::