Redeem a coupon - BrandWallet

POST $BASE_URL/v1/customers/:id/coupons/:couponId/redeem

Marks the given coupon as redeemed and returns the updated coupon. All body fields are optional and carry opaque ids (your external system identifiers), resolved to internal references on our side.

Auth: Authorization: Bearer <accessToken> — an organization-scoped token from Authentication.

Payload schema:

{
  "user": "usr-ext-1042",                                  // optional — cashier user opaque id
  "branch": "9bb88786-6df3-4d16-b4dd-e89b43e8b2b5",        // optional — branch opaque id
  "products": ["4221450", "4221453"]                       // optional — product opaque ids in the redemption
}

Path parameters

Parameter	Type	Description
`id`	string	Customer id.
`couponId`	string	Coupon instance id (from GET /v1/customers/:id/coupons).

Body

Field	Type	Description
`user`	string	Optional. Cashier user opaque id. When omitted, the authenticated API user is recorded as the redeeming user.
`branch`	string	Optional. Branch opaque id. When omitted, the authenticated user’s branch is used.
`products`	string[]	Optional. Product opaque ids included in the redemption.

Example

curl --request POST \
  --url "$BASE_URL/v1/customers/3d8ec956-de2a-4d43-9c1e-74475b153362/coupons/906550fd-dcf5-4aed-a80e-03e8939fc2b4/redeem" \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "9bb88786-6df3-4d16-b4dd-e89b43e8b2b5" }'

Response

Returns 200 with the updated coupon; status is now redeemed.

{
  "id": "906550fd-dcf5-4aed-a80e-03e8939fc2b4",
  "coupon": { "name": "Free Coffee Coupon" },
  "code": "500265",
  "issuedAt": "2026-04-21T12:19:19.037Z",
  "expiresAt": "2026-09-09T12:14:08.511Z",
  "redeemed": {
    "branch": "9bb88786-6df3-4d16-b4dd-e89b43e8b2b5",
    "user": "4eeb2186-7ca7-4a45-81e1-1616480975d6"
  },
  "redeemedAt": "2026-08-04T10:00:00.000Z",
  "status": "redeemed"
}

Notes:

Redeeming an already redeemed, expired, or disabled coupon returns _coupon_is_not_valid (400).
A coupon can also be redeemed as part of a basket by passing its id in reward on POST /v1/transactions/process.

Last modified on September 29, 2026