> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brand-wallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List coupons

> Return the coupons belonging to a BrandWallet customer, optionally filtered to a single wallet card.

```http theme={null}
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](/api/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](/api/find-customer) (`cards[].id`). Filters coupons to those defined on that card; an unknown card returns `_card_not_found` (400). |

### Example

```bash theme={null}
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.

```json theme={null}
[
  {
    "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](/api/redeem-coupon), or as `reward` on [transactions](/api/process-transaction). |
| `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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.