List coupons - BrandWallet

GET $BASE_URL/v1/customers/:id/coupons

Returns the coupons belonging to the given customer, as a JSON array. When card is provided, only the coupons defined on that card are returned; otherwise all of the customer’s coupons are returned.

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

Path parameters

Parameter	Type	Description
`id`	string	Customer id.

Query parameters

Parameter	Type	Description
`card`	string	Optional. A card id from GET /v1/customers/find (`cards[].id`). Filters coupons to those defined on that card; an unknown card returns `_card_not_found` (400).

Example

curl --request GET \
  --url "$BASE_URL/v1/customers/3d8ec956-de2a-4d43-9c1e-74475b153362/coupons?card=41dd8263-288e-4b55-bf2e-6a82995a0441" \
  --header 'Authorization: Bearer <accessToken>'

Response

Returns 200 with a JSON array; each element is one coupon instance.

[
  {
    "id": "906550fd-dcf5-4aed-a80e-03e8939fc2b4",
    "coupon": { "name": "10% Discount" },
    "code": "500265",
    "type": "discount",
    "discountAmount": 10,
    "isPercent": true,
    "maxDiscountAmount": 25,
    "issuedAt": "2026-04-21T12:19:19.037Z",
    "expiresAt": "2026-09-09T12:14:08.511Z",
    "status": "active"
  },
  {
    "id": "499e8e25-47e3-409c-90cd-97ee2bffe66e",
    "coupon": { "name": "Free Coffee Coupon" },
    "code": "431825",
    "type": "product",
    "discountAmount": 100,
    "isPercent": true,
    "products": {
      "quantity": 1,
      "productIds": ["4221450", "4221453", "4221456"]
    },
    "issuedAt": "2026-04-21T12:19:19.037Z",
    "status": "active"
  }
]

Field	Type	Description
`id`	string	Coupon instance id. Use it as `:couponId` on redeem, or as `reward` on transactions.
`coupon`	object	Coupon summary: `name`.
`code`	string	Coupon code, when one is assigned. Optional.
`type`	string	Coupon type, e.g. `discount` or `product`. Optional.
`discountAmount`	number	Discount value; a percentage when `isPercent` is true. `product` (free product) coupons come as `100` with `isPercent: true`. Optional.
`isPercent`	boolean	Whether `discountAmount` is a percentage. Optional.
`maxDiscountAmount`	number	Cap for percentage discounts. Optional.
`includesModifiers`	boolean	Whether product modifiers are included in the discount. Optional.
`products`	object	Which products the coupon applies to: `quantity` and `productIds` (your external product codes). Present on product-scoped coupons.
`issued` / `issuedAt`	object / string	Where (`branch`, `user`) and when (ISO 8601) the coupon was issued. Optional.
`redeemed` / `redeemedAt`	object / string	Where and when the coupon was redeemed. Present on redeemed coupons.
`expiresAt`	string	Expiry time (ISO 8601). Optional.
`status`	string	One of `active`, `redeemed`, `disabled`.

Notes:

Optional fields that have no value are omitted — you will not receive null.

Last modified on September 29, 2026