Get Gift Card By ID

Retrieve a gift card by its internal identifier.

Endpoint

GET /v1/giftCards/{giftCardId}

Headers

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

Path Parameters

Parameter	Type	Description	Required
giftCardId	String (UUID)	The card's internal ID	✅ Yes

Example Request

curl --location 'https://stage-platform-exlr8-incentives.exlr8now.com/v1/giftCards/9b2c4d6e-8f0a-4b1c-9d3e-5f7a1b2c3d4e' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Client-Secret: YOUR_CLIENT_SECRET'

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...",
    "cardNumberHash": "9c8d7e...",
    "pinHash": "1a2b3c...",
    "status": "ACTIVE",
    "currency": "INR",
    "initialBalance": 500,
    "remainingBalance": 350,
    "issuedAt": "2026-08-25T11:30:00Z",
    "expiresAt": "2027-08-25T11:30:00Z",
    "version": 3,
    "createdAt": "2026-08-25T11:30:00Z",
    "updatedAt": "2026-08-25T11:42:07Z"
  }
}

Response Fields

Field	Type	Description
giftCardId	String	Internal identifier
programId	String	The campaign this card belongs to
giftCardTemplateId	String	The template it was issued from
status	String	ACTIVE, INACTIVE, EXPIRED or FROZEN
currency	String	Inherited from the campaign
initialBalance	Number	Face value at issuance
remainingBalance	Number	What is left to spend
expiresAt	String	RFC 3339, UTC
version	Number	Optimistic-concurrency counter, incremented on each balance change
updatedAt	String	Last modification
codeHash	String	SHA-256 of the digital code
cardNumberHash	String	SHA-256 of the card number, when one was issued
pinHash	String	SHA-256 of the PIN, when one was issued

The plaintext code, card number and PIN are not returned — only their hashes, which are of no use for redemption. The one time the plaintext exists in a response is issuance.

:::note Choosing between this and inquiry Use this endpoint when you already hold the giftCardId — reconciliation, support tooling, order lookups. Use Gift Card Inquiry at checkout, when all you have is the code the customer presented. Inquiry also returns the template's redemption rules, which this endpoint does not. :::

Error Responses

Error code	HTTP	Cause
BAD_REQUEST	400	giftCardId is not a valid UUID
RECORD_NOT_FOUND	404	No such card within your merchant

A card belonging to another merchant returns 404, identically to one that does not exist.

Related Endpoints

• Gift Card Inquiry — look up by customer code instead
• List Gift Cards
• List Transactions — this card's ledger history