API Reference Overview

Every endpoint reachable with API client credentials. Configuration endpoints — programs, templates, users — are administrator-only and are not listed here; see Authentication for the full boundary.

Base URLs

The Incentives service is deployed separately from the Delivery Partner API, on its own hosts.

Environment	Base URL
UAT (Testing)	https://stage-platform-exlr8-incentives.exlr8now.com
Production	https://prod-platform-exlr8-incentives.exlr8now.com

Examples throughout these pages use the UAT host. Switch to the production host only once your integration is verified.

Endpoints

No.	API Name	Method	Endpoint
1	Issue Gift Card	POST	/v1/giftCards
2	Gift Card Inquiry	POST	/v1/giftCards/inquiry
3	Get Gift Card By ID	GET	/v1/giftCards/{giftCardId}
4	List Gift Cards	GET	/v1/giftCards
5	Create Transaction	POST	/v1/giftCards/transactions
6	Get Transaction By ID	GET	/v1/giftCards/transactions/{transactionId}
7	List Transactions	GET	/v1/giftCards/transactions
8	Issue Coupon	POST	/v1/coupons
9	Validate Coupon	POST	/v1/coupons/validate
10	Redeem Coupon	POST	/v1/coupons/redeem
11	Get Coupon By ID	GET	/v1/coupons/{couponId}
12	List Coupons	GET	/v1/coupons

Authentication

All requests require both credential headers:

X-Client-Id: YOUR_CLIENT_ID
X-Client-Secret: YOUR_CLIENT_SECRET
Content-Type: application/json

Common response patterns

Success

{
  "success": true,
  "data": { }
}

Paginated

{
  "success": true,
  "data": [],
  "pagination": {
    "nextCursor": "eyJpZCI6IjliMmM0ZDZlIn0",
    "hasMore": true
  }
}

Query parameters on every list endpoint:

Parameter	Type	Description
limit	Integer	Default 15, maximum 100, -1 for unlimited
nextCursor	String	Opaque cursor from the previous page

Error

{
  "success": false,
  "errCode": "GC_EXPIRED",
  "message": "Gift card has expired"
}

Branch on errCode. See Error Codes.

Status codes

Code	Meaning
200 OK	Read, validation, or coupon redemption succeeded
201 Created	An instrument or transaction was created
400 Bad Request	Malformed body, failed validation, or an unknown field
401 Unauthorized	Missing or invalid credentials
403 Forbidden	Authenticated, but not permitted for this role
404 Not Found	No such resource within your merchant
409 Conflict	Write contention (VERSION_MISMATCH), or a rare idempotency race — both retryable
422 Unprocessable Entity	A business rule rejected the request
500 Internal Server Error	Platform fault — safe to retry with the same idempotency key

Note the asymmetry on the two redemption paths: a gift card transaction returns 201 Created because it creates a ledger entry, while a coupon redemption returns 200 OK.

Conventions

• Money is a JSON number, rounded to two decimal places.
• Timestamps are RFC 3339 in UTC (2026-08-25T11:42:07Z).
• IDs are UUID v4.
• Currency comes from the campaign; you never send it.
• Unknown fields are rejected with 400 BAD_REQUEST.
• Merchant scope is implicit — never send a merchant ID.