Get Coupon By ID

Retrieve a coupon by its internal identifier.

Endpoint

GET /v1/coupons/{couponId}

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
couponId	String (UUID)	The coupon's internal ID	✅ Yes

Example Request

curl --location 'https://stage-platform-exlr8-incentives.exlr8now.com/v1/coupons/7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Client-Secret: YOUR_CLIENT_SECRET'

Response

Successful Response — 200 OK

{
  "success": true,
  "data": {
    "couponId": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
    "merchantId": "b1946ac9-2c3d-4e5f-8a7b-6c5d4e3f2a1b",
    "programId": "3c6e0b8a-9c15-4f2b-8d1e-7a5b9c0d2e4f",
    "couponTemplateId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
    "codeHash": "8d7e6f...",
    "status": "ACTIVE",
    "redemptionCount": 0,
    "usageLimitTotal": 1,
    "expiresAt": "2026-11-23T11:30:00Z",
    "version": 1,
    "createdAt": "2026-08-25T11:30:00Z",
    "updatedAt": "2026-08-25T11:30:00Z"
  }
}

Response Fields

Field	Type	Description
couponId	String	Internal identifier
programId	String	The campaign this coupon belongs to
couponTemplateId	String	The template it was issued from
codeHash	String	SHA-256 of the coupon code
status	String	ACTIVE, USED, EXPIRED or VOIDED
redemptionCount	Number	How many times it has been redeemed
usageLimitTotal	Number	Redemption cap. 0 means unlimited
expiresAt	String	RFC 3339, UTC
version	Number	Optimistic-concurrency counter
createdAt	String	When the coupon was issued
updatedAt	String	Last modification

The plaintext code is not returned — only its hash. The one time the plaintext exists in a response is issuance.

:::note There is no lookup by code Unlike gift cards, which have an inquiry endpoint, coupons have no read-by-code operation. To check a customer's code, use Validate Coupon — it resolves the code, reports whether redemption would succeed, and consumes nothing. :::

Error Responses

Error code	HTTP	Cause
BAD_REQUEST	400	couponId is not a valid UUID
INSTRUMENT_NOT_FOUND	404	No such coupon within your merchant

A coupon belonging to another merchant returns 404 INSTRUMENT_NOT_FOUND, identically to one that does not exist. Note this differs from the gift card endpoints, which return RECORD_NOT_FOUND.

Related Endpoints

• Validate Coupon — the code-based equivalent
• List Coupons
• Redeem Coupon