> ## 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.

# Redeem a coupon

> Mark a BrandWallet coupon as redeemed and return the updated coupon.

```http theme={null}
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](/api/authentication).

Payload schema:

```json theme={null}
{
  "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](/api/list-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

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

```json theme={null}
{
  "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](/api/process-transaction).


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