List Gift Cards

List the gift cards issued under your merchant, newest first, with cursor pagination.

Endpoint

GET /v1/giftCards

Headers

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

Query Parameters

Parameter	Type	Description	Required
templateId	String (UUID)	Return only cards issued from this template	❌ No
limit	Integer	Items per page. Default 15, maximum 100, -1 for unlimited	❌ No
nextCursor	String	Cursor from the previous page's pagination object	❌ No

Example Request

curl --location 'https://stage-platform-exlr8-incentives.exlr8now.com/v1/giftCards?limit=50' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Client-Secret: YOUR_CLIENT_SECRET'

Filter by template

curl --location 'https://stage-platform-exlr8-incentives.exlr8now.com/v1/giftCards?templateId=d4c3b2a1-6f5e-4d3c-8b2a-1f0e9d8c7b6a&limit=50' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Client-Secret: YOUR_CLIENT_SECRET'

Use this to reconcile a single campaign's cards rather than paging the whole merchant.

Response

Successful Response — 200 OK

{
  "success": true,
  "data": [
    {
      "giftCardId": "9b2c4d6e-8f0a-4b1c-9d3e-5f7a1b2c3d4e",
      "merchantId": "b1946ac9-2c3d-4e5f-8a7b-6c5d4e3f2a1b",
      "programId": "8f14e45f-ceea-467a-9d7f-1b2c3d4e5f60",
      "giftCardTemplateId": "d4c3b2a1-6f5e-4d3c-8b2a-1f0e9d8c7b6a",
      "codeHash": "3f2a1b...",
      "status": "ACTIVE",
      "currency": "INR",
      "initialBalance": 500,
      "remainingBalance": 350,
      "issuedAt": "2026-08-25T11:30:00Z",
      "expiresAt": "2027-08-25T11:30:00Z",
      "version": 3
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6IjliMmM0ZDZlIn0",
    "hasMore": true
  }
}

Each element carries the same fields as Get Gift Card By ID.

Pagination Fields

Field	Type	Description
nextCursor	String	Opaque cursor for the next page
hasMore	Boolean	Whether further pages exist

Paging through results

Pass nextCursor back until hasMore is false.

async function listAllGiftCards() {
  const cards = [];
  let cursor = null;

  do {
    const url = new URL(`${baseUrl}/v1/giftCards`);
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("nextCursor", cursor);

    const res = await fetch(url, {
      headers: {
        "X-Client-Id": clientId,
        "X-Client-Secret": clientSecret,
      },
    });

    const body = await res.json();
    cards.push(...body.data);
    cursor = body.pagination.hasMore ? body.pagination.nextCursor : null;
  } while (cursor);

  return cards;
}

Treat the cursor as opaque — do not parse it or construct one yourself.

:::note Scope is implicit Results are already filtered to your merchant. There is no merchant parameter, and no way to widen the scope. :::

:::caution Not a real-time feed This is a snapshot for reconciliation, not a change stream. Cards issued while you are paging may not appear consistently. For an authoritative view of one card, fetch it directly. :::

Error Responses

Error code	HTTP	Cause
BAD_REQUEST	400	limit is not an integer, or the cursor is malformed

Related Endpoints

• Get Gift Card By ID
• List Transactions — the ledger view
• Issue Gift Card