Gifting APIDocumentation

Key concepts

Endpoint summary

Authentication

Every endpoint requires an API key, sent in the X-API-KEY request header. The key identifies your tenant — all catalogs, balances, orders, and transactions are scoped to it automatically.

X-API-KEY: your-api-key-here

A request with a missing or invalid key returns 401 Unauthorized.

Quick start

1. Find a brand. Fetch the catalog for the currency you want to spend in, then pick a brandId and one of its denominations.

curl -X GET "https://sandbox.api.cheers.gift/api/v2/catalog?currency=USD" \
  -H "X-API-KEY: your-api-key"

2. Create the order. Choose how you want it issued.

curl -X POST "https://sandbox.api.cheers.gift/api/v2/order" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "bmctMTpjYXQtMTIzNDU",
    "amount": 25.00,
    "idempotencyKey": "3f9a1c7e-1d2b-4f8a-9c31-0f4b2d6a77e1",
    "issuanceType": "OnDemand"
  }'

3. Deliver the gift. For OnDemand you get redeem.url — hand that to your customer. For JustInTime you get card with the card details themselves.

Conventions

Brand identifiers

In v2, brandId is an opaque string. Read it from the catalog and send it back unchanged when you create an order.

• Do store it and echo it back verbatim.
• Don't parse it, decode it, derive meaning from it, or construct one yourself.

Its internal format is not part of this contract and will change. Treat it the way you would treat a session token.

Issuance types

issuanceType decides when the gift card is issued.

OnDemand returns as soon as the order is paid for. It is the right choice when you are sending a link to a recipient and do not need the card yourself.

JustInTime waits for the card to be issued, which involves two asynchronous steps on our side. It usually completes within the request. When it does not, you get status: "Processing" and a retryAfter — the order is fine, it is simply not finished yet. See Handling Processing.

Handling Processing

JustInTime issuance waits on two asynchronous steps. Most orders finish inside the original request. When one does not, you get:

{
  "orderId": 987654,
  "status": "Processing",
  "retryAfter": "2026-08-12T09:15:05Z"
}

The order exists and is paid for. Wait until retryAfter, then re-POST the order — same body, same idempotencyKey:

curl -X POST "https://sandbox.api.cheers.gift/api/v2/order" \
  -H "X-API-KEY: your-api-key" -H "Content-Type: application/json" \
  -d '{ ...exactly the same body, including the same idempotencyKey... }'

This resumes the existing order — it never creates a second one — and waits for the card.

GET /api/v2/order/{orderId} is a read: it reports the current state and is safe to call as often as you like, but it does not itself advance a stalled order. Use it to check; use the re-POST to make progress.

Fees

amount is the gift card's value — what the recipient receives, and what you asked for. It is not necessarily what you are billed.

Some brands carry a processing fee, applied by the platform on top of the card value. A $50 card on a brand with a $4.90 fee draws $54.90 from your balance while amount still reads 50.00.

Idempotency

Create an order is the only endpoint that moves money, so it is guarded by an idempotency key that you generate and send in idempotencyKey.

• The key must be unique within your tenant — a UUID per order attempt works well.
• Store the key alongside your own order record before you call the API.
• If a call fails with a network error or timeout, retry with the same key.

Reusing a key with the same request body returns 200 OK — it replays the original order, or resumes it if it was left unfinished. Reusing a key with a different request body returns 409 Conflict.

So a retry after a timeout simply returns the order — you never need to reconcile a 409 to find out whether the first attempt succeeded.

{ "message": "Duplicate request detected. This idempotency key has already been used." }

Order status

Transaction status

orderStatus on List transactions — a separate vocabulary from Order status above, describing the payment transaction rather than issuance.

Card

Returned as card on a completed JustInTime order.

There is no Barcode redemption type. A card displayed as a barcode is a Code — the barcode is a way of presenting the value, not a separate way of redeeming it.

Card type

Error handling

The API uses standard HTTP status codes.

Error responses carry a JSON body with a human-readable message:

{ "message": "Amount 37 is not available for brand 'bmctMTpjYXQtMTIzNDU'. Valid denominations: 25, 50, 100." }

Log the message verbatim when reporting an issue to Jifiti support, along with the request timestamp (UTC) and, where relevant, the idempotencyKey or orderId.

Retry guidance

Need a sandbox key? Talk to our team.