Issue Gift Card

Create a new gift card from a template. The platform generates the card's secrets and returns them once — this response is your only opportunity to capture them.

Endpoint

POST /v1/giftCards

Headers

Header	Type	Description	Required
X-Client-Id	String	Your client ID	✅ Yes
X-Client-Secret	String	Your client secret	✅ Yes
Content-Type	String	application/json	✅ Yes

Request Body

Field	Type	Description	Required
giftCardTemplateId	String (UUID)	The template to issue from	✅ Yes

That is the entire body. Denomination, currency, expiry and redemption rules are all fixed on the template — see Setup Flow.

Example Request

curl --location 'https://stage-platform-exlr8-incentives.exlr8now.com/v1/giftCards' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Client-Secret: YOUR_CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "giftCardTemplateId": "d4c3b2a1-6f5e-4d3c-8b2a-1f0e9d8c7b6a"
  }'

Response

Successful Response — 201 Created

{
  "success": true,
  "data": {
    "giftCardId": "9b2c4d6e-8f0a-4b1c-9d3e-5f7a1b2c3d4e",
    "digitalCode": "GC-7F3A-9K2M-4XQ8",
    "cardNumber": "6011457893214567",
    "pin": "4821"
  }
}

Response Fields

Field	Type	Description
giftCardId	String	Internal identifier. Store this — refunds and voids reference it
digitalCode	String	The code the customer presents to redeem
cardNumber	String	Luhn-valid card number, always issued
pin	String	PIN, always issued

:::caution Returned exactly once Only hashes of digitalCode, cardNumber and pin are stored. They cannot be retrieved again by any endpoint. Deliver them to the customer and persist whatever you need before you acknowledge this response. :::

Behaviour

The campaign must be active. Issuance is refused with PROGRAM_INACTIVE if the campaign behind the template is DRAFT, PAUSED, EXPIRED or ARCHIVED. A campaign also expires automatically once it passes its endAt, so a previously working integration can start failing without anyone changing anything — surface this error clearly rather than retrying.

Caps are enforced at issuance, atomically. The cap reservation and the card insert commit together, so counters never drift from the cards that exist. Two caps apply:

• The template's own count and value caps → TEMPLATE_LIMIT_EXCEEDED
• The campaign's value budget → CAMPAIGN_LIMIT_EXCEEDED

Note that a campaign's count cap governs how many templates may exist under it, not how many cards you issue. Only its value budget is consumed here, by the card's face value.

Velocity limits are enforced. If the campaign carries a rolling value limit (per day, month or year), issuance that would breach the window is rejected with CAMPAIGN_LIMIT_EXCEEDED — the same code as the lifetime budget. The two are not distinguishable from the code alone; read the message to tell them apart when diagnosing.

Neither cap is retryable — an administrator must raise the limit.

Expiry is set now. With FROM_ISSUANCE, the card's expiry is computed from this moment plus the template's validity period. With FIXED_DATE, every card shares one date regardless of when it was issued.

Issuance is not idempotent. Unlike redemption, this endpoint takes no idempotency key — two calls create two cards. If a call times out, look the card up with List Gift Cards before retrying, or accept that an unused card may be stranded.

Error Responses

Error code	HTTP	Cause
BAD_REQUEST	400	Missing or malformed giftCardTemplateId, or an unknown field
TEMPLATE_NOT_FOUND	404	No such template within your merchant
PROGRAM_NOT_FOUND	404	The template points at a campaign that no longer exists
PROGRAM_INACTIVE	422	The campaign is not ACTIVE
TEMPLATE_LIMIT_EXCEEDED	422	The template's count or value cap is reached
CAMPAIGN_LIMIT_EXCEEDED	422	The campaign's value budget or velocity window is exhausted
INTERNAL_SERVER_ERROR	500	Platform fault

{
  "success": false,
  "errCode": "PROGRAM_INACTIVE",
  "message": "Program is inactive: program is not ACTIVE"
}

Related Endpoints

• Gift Card Inquiry — look a card up by the code you just issued
• Create Transaction — redeem, refund or void
• List Gift Cards — reconcile what you have issued