List Transactions

List gift card transactions across your merchant, newest first, with cursor pagination. This is the reconciliation view of every value movement.

Endpoint

GET /v1/giftCards/transactions

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
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/transactions?limit=100' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Client-Secret: YOUR_CLIENT_SECRET'

Response

Successful Response — 200 OK

{
  "success": true,
  "data": [
    {
      "transactionId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "giftCardId": "9b2c4d6e-8f0a-4b1c-9d3e-5f7a1b2c3d4e",
      "type": "DEBIT",
      "amount": 150,
      "balanceBefore": 500,
      "balanceAfter": 350,
      "referenceId": "order-20260825-0042",
      "idempotencyKey": "order-20260825-0042-debit-01",
      "createdAt": "2026-08-25T11:42:07Z"
    },
    {
      "transactionId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "giftCardId": "9b2c4d6e-8f0a-4b1c-9d3e-5f7a1b2c3d4e",
      "type": "REFUND",
      "amount": 50,
      "balanceBefore": 350,
      "balanceAfter": 400,
      "referenceId": "order-20260825-0042",
      "idempotencyKey": "order-20260825-0042-refund-01",
      "createdAt": "2026-08-25T14:05:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6IjJiM2M0ZDVlIn0",
    "hasMore": true
  }
}

Each element carries the same fields as Get Transaction By ID.

Reconciliation

referenceId is the join key back to your own records. Set it to your order ID at redemption and this listing reconciles directly against your order book.

// Reconcile a day's redemptions against your orders
async function reconcile(orderIndex) {
  const unmatched = [];
  let cursor = null;

  do {
    const url = new URL(`${baseUrl}/v1/giftCards/transactions`);
    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();

    for (const txn of body.data) {
      if (!orderIndex.has(txn.referenceId)) {
        unmatched.push(txn);
      }
    }

    cursor = body.pagination.hasMore ? body.pagination.nextCursor : null;
  } while (cursor);

  return unmatched;
}

Both the debit and its refund carry the same referenceId — that is required by the refund rules, and it means a reference can map to several ledger entries. Sum by type when netting.

A transaction with no matching order usually means a redemption committed but your acknowledgement was lost — the value moved, and your side does not know it. These are the entries worth alerting on.

:::note Netting a card's position A card's balance is initialBalance minus debits plus refunds. You do not need to compute it: balanceAfter on the most recent transaction is authoritative, as is remainingBalance from Get Gift Card By ID. :::

Error Responses

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

Related Endpoints

• Get Transaction By ID
• Create Transaction
• Get Gift Card By ID