Setup Flow

Before your backend can issue or redeem anything, a merchant administrator configures the incentive programme in the eXlr8 dashboard. This page describes what they set up and why it matters to your integration — so you understand what the identifiers in your API calls refer to, and can tell an administrator exactly what you need.

None of this is done through the API you have access to. It is dashboard work, performed once, before integration begins.

The hierarchy

Everything hangs off a merchant. Each level constrains the one beneath it.

Merchant                         one merchant, one currency
  └── Program (campaign)         the budget and the lifecycle
        └── Template             the rules every instrument inherits
              └── Instrument     the gift card or coupon a customer holds
                    └── Transaction / Redemption

A program — also called a campaign — holds the budget and the status. A template holds the rules: denomination, expiry, discount behaviour. An instrument is a single issued gift card or coupon. Your API calls create instruments from a template, then move value on them.

The consequence worth remembering: you never send a denomination, an expiry date, or a discount rule. All of it is fixed on the template. Your issuance call names a template and nothing else.

What the administrator sets up

1. The campaign

The administrator creates a campaign and gives it a currency, a budget and an optional end date. Two properties of it reach into your integration:

• Instrument type — a campaign carries either gift cards or coupons, never both. A merchant running both will have at least two campaigns.
• End date — an hourly job moves campaigns past their end date to EXPIRED, and issuance stops at that moment.

2. Activation

A campaign is created as a draft and must be activated before it can issue anything. Its lifecycle:

DRAFT ──► ACTIVE ◄──► PAUSED
            │           │
            └─────┬─────┘
                  ▼
              EXPIRED ──► ARCHIVED

This gates your integration. Issuance requires the campaign to be ACTIVE. If an administrator pauses a campaign, or it passes its end date, your issuance calls start returning PROGRAM_INACTIVE (HTTP 422) — with no change on your side. Instrument up front and alert on it.

Redemption of instruments already issued is a separate matter; see How Redemption Works.

3. The template

The template is where every rule an instrument obeys is written down. It is created once and reused for every instrument you issue.

Gift card settings that shape your code

Setting	Why it matters to you
Face value	The single denomination of every card issued from this template
Partial redemption	When disabled, a redemption must spend the entire remaining balance in one go
Minimum redemption amount	The floor on a single partial redemption
Expiry rule	Either a validity period counted from issuance, or one fixed date shared by every card

You do not have to take these on trust — Gift Card Inquiry returns the partial-redemption flag, the minimum amount and the expiry for any card you look up. Read them there rather than hard-coding assumptions.

Coupon settings that shape your code

Setting	Why it matters to you
Coupon type	SAVE_X, BUY_X_GET_Y or FREE_SHIPPING — determines how the discount is computed
Type configuration	The percentages, thresholds and product lists behind that maths. See Redeem Coupon
Code type	UNIQUE issues a distinct code per customer; SHARED gives everyone one public promo code
Usage limit	How many times a coupon may be redeemed
Applicability	ALL, CATEGORIES or PRODUCTS

Two of these change how your integration behaves:

Code type decides what issuance means. A UNIQUE template produces a new code on every call — issue one per customer. A SHARED template is issued once and the returned code distributed however you like.

Applicability decides what you must send at redemption. When a coupon is scoped to categories or products, the discount is computed only over matching order lines, and an order with no matching line is rejected as CV_NOT_APPLICABLE. This is why redemption takes order line items rather than a total.

4. Your API client

Finally, the administrator provisions the identity your backend will use, as a user with the MERCHANT_API_CLIENT role.

That role is onboarded differently from every other. There is no temporary password, no OTP and no first sign-in — an API client never signs in at all. The platform generates a client secret at creation and emails the credentials to the address on the account:

X-Client-Id:     b7e2f1a0-4c3d-4e5f-9a8b-1c2d3e4f5a6b
X-Client-Secret: <64-character secret>

:::caution The secret is shown once Only a hash of the client secret is stored. It appears in that one email and can never be retrieved again — not by you, and not by the administrator who created it. Move it into your secret manager as soon as it arrives. :::

The client ID is stable and never changes. Only the secret rotates.

Rotating the secret

If the secret is lost or compromised, an administrator triggers a rotation from the dashboard. The new secret is emailed to the API client's own address, exactly as at provisioning — the administrator performing the rotation never sees it either.

The previous secret stops working immediately. There is no overlap window, so agree a rotation time when you can deploy the new value promptly. A sudden run of 401 API_KEY_INVALID on a previously working integration almost always means a rotation happened; check for a credentials email.

What you receive

At the end of setup you should have been given:

Item	Example	Used for
Client ID	b7e2f1a0-…	The X-Client-Id header
Client secret	<64 chars>	The X-Client-Secret header
Template ID(s)	d4c3b2a1-…	Issuing instruments
Base URL	See Authentication	Every request

You do not need a merchant ID or a campaign ID. Both are resolved from your credentials and the template.

:::tip Ask for one thing more Ask which campaign each template belongs to and when that campaign ends. It is the single most useful piece of context for diagnosing a PROGRAM_INACTIVE months later. :::

Next steps

• Authentication — how to present your credentials
• Quick Start — issue and redeem your first instrument
• How Redemption Works — before you write money-moving code