Gift Card Inquiry

Look up a gift card by the code a customer presents. Returns the balance, status and redemption rules — everything you need to decide what to charge before redeeming.

Endpoint

POST /v1/giftCards/inquiry

:::info Why POST The code is a secret. Sending it in a request body keeps it out of URLs, access logs, proxy logs and browser history. No endpoint in this API accepts a code as a path or query parameter. :::

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
code	String	The digital code the customer presented	✅ Yes

Example Request

curl --location 'https://stage-platform-exlr8-incentives.exlr8now.com/v1/giftCards/inquiry' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Client-Secret: YOUR_CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "GC-7F3A-9K2M-4XQ8"
  }'

Response

Successful Response — 200 OK

{
  "success": true,
  "data": {
    "giftCardId": "9b2c4d6e-8f0a-4b1c-9d3e-5f7a1b2c3d4e",
    "giftCardTemplateId": "d4c3b2a1-6f5e-4d3c-8b2a-1f0e9d8c7b6a",
    "status": "ACTIVE",
    "currency": "INR",
    "initialBalance": 500,
    "remainingBalance": 350,
    "issuedAt": "2026-08-25T11:30:00Z",
    "expiresAt": "2027-08-25T11:30:00Z",
    "expired": false,
    "minRedemptionAmount": 50,
    "allowPartialRedemption": true
  }
}

Response Fields

Field	Type	Description
giftCardId	String	Internal identifier — store it for refunds and voids
giftCardTemplateId	String	The template this card 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
issuedAt	String	RFC 3339, UTC
expiresAt	String	RFC 3339, UTC
expired	Boolean	Derived from expiresAt against the current time
minRedemptionAmount	Number	Floor on a single partial redemption
allowPartialRedemption	Boolean	Whether the card may be spent across several orders

No hashes and no secrets are returned — the response is safe to log, though the request body is not.

Deciding what to charge

The last two fields are the ones your checkout logic turns on.

allowPartialRedemption = true
  remainingBalance >= orderTotal  →  debit orderTotal (if >= minRedemptionAmount)
  remainingBalance <  orderTotal  →  debit remainingBalance, collect the rest by other means

allowPartialRedemption = false
  →  debit the full remainingBalance, or decline the card

Check expired and status before offering the card at all. A card that is expired or not ACTIVE will be refused at redemption, so catching it here gives the customer a clearer message.

:::caution Redemption rules can come back zeroed minRedemptionAmount and allowPartialRedemption are read from the card's template. If that template cannot be loaded, the inquiry still succeeds but returns both as zero values — 0 and false — rather than failing.

allowPartialRedemption: false is therefore ambiguous: it may mean the template genuinely forbids partial redemption, or that the template could not be read. Treat the conservative reading (debit the full balance) as correct in both cases, and alert if you see it on a template you know allows partials. :::

:::note Inquiry is a snapshot The balance can change between an inquiry and a redemption — another checkout may spend the card in between. Treat the inquiry as guidance for the customer, and let the redemption call be the authority. Redemption re-reads the balance from the primary database and will reject an over-debit regardless of what the inquiry said. :::

Error Responses

Error code	HTTP	Cause
BAD_REQUEST	400	Missing code, or an unknown field
GC_INVALID	422	No card matches this code within your merchant

{
  "success": false,
  "errCode": "GC_INVALID",
  "message": "Gift card is invalid: gift card not found"
}

GC_INVALID covers both a code that does not exist and a code belonging to another merchant — the platform does not distinguish the two.

Related Endpoints

• Create Transaction — redeem the card you just inspected
• Get Gift Card By ID — the same information by internal ID
• How Redemption Works