Voucher Redemption

Once an order is fulfilled, the buyer holds one or more voucher codes they can redeem on the partner platform (e.g. an Amazon gift-card code, a Netflix PIN, a mobile top-up token).

Because orders can contain multiple products and multiple quantities, BD Voucher exposes codes at two levels:

Order level → one flat voucher_codes[] array containing every code across all items and quantities.
Item level → items[].voucher_codes[] grouped by variant.

Both lists match exactly what the customer received in their consolidated delivery email.

Get all codes for an order

The easiest way to retrieve every code from an order — whether the basket contained one product or many, and regardless of quantity — is to check the top-level voucher_codes array on the order response:

GET /api/v1/orders/:id
Authorization: Bearer $TOKEN

{
  "id": 42,
  "order_number": "20260427",
  "status": "SUCCEEDED",
  "dispatched_email": "customer@example.com",
  "email_sent_at": "2026-04-27T14:22:00.000Z",
  "voucher_codes": ["ABCD-1234-EFGH-5678", "WXYZ-9876-MNOP-5432"],
  "items": [
    {
      "variant_id": 22402,
      "quantity": 2,
      "fulfilled": true,
      "fulfilled_at": "2026-04-27T14:21:58.000Z",
      "voucher_codes": ["ABCD-1234-EFGH-5678", "WXYZ-9876-MNOP-5432"],
      "voucher": {
        "id": 101,
        "code": "ABCD-1234-EFGH-5678",
        "status": "sold",
        "serial_number": null,
        "expires_at": "2027-04-27T00:00:00.000Z"
      }
    }
  ]
}

Order-level voucher fields

Field	Type	Description
`voucher_codes`	`string[]`	Flat deduplicated list of every code across every item and every quantity unit — identical to the list the customer received by email.
`dispatched_email`	`string \| null`	The email address the consolidated voucher email was sent to. `null` until the email is successfully dispatched.
`email_sent_at`	`ISO 8601 \| null`	Timestamp of the last successful voucher-email dispatch. `null` until sent.

Item-level voucher fields

Field	Type	Description
`items[].voucher_codes`	`string[]`	Codes belonging to this specific item / variant. For a `quantity: 2` item, this holds both codes.
`items[].voucher.code`	`string`	Primary voucher code (the first code for multi-quantity items).
`items[].voucher.status`	`string`	Voucher status: `available`, `reserved`, `sold`, or `used`.
`items[].voucher.serial_number`	`string \| null`	Optional serial / activation number returned by the partner.
`items[].voucher.expires_at`	`ISO 8601 \| null`	Expiry date set by the partner, if provided.

List vouchers

Returns all vouchers linked to the authenticated user’s fulfilled orders, with optional filtering.

GET /api/v1/vouchers
Authorization: Bearer $TOKEN

Query parameters

Parameter	Type	Description
`page`	`integer`	Page number (1-based). Default: `1`.
`limit`	`integer`	Items per page. Default: `20`.
`search`	`string`	Full-text search across voucher code and product name.
`categoryId`	`integer`	Filter by product category ID.
`brandId`	`integer`	Filter by brand ID.
`partnerId`	`integer`	Filter by fulfillment partner ID.
`paymentChannelId`	`integer`	Filter by the payment channel used for the order.
`sort`	`string`	Sort order: `price_asc`, `price_desc`, or `newest` (default).

Example

GET /api/v1/vouchers?page=1&limit=10&sort=newest
Authorization: Bearer $TOKEN

Notes on multi-quantity orders

When a customer buys quantity: 3 of a single variant, three separate voucher rows are created — one per unit. They all appear in items[].voucher_codes[] and again in the top-level voucher_codes[] for easy access without traversing the items list.

The consolidated delivery email groups all codes together with product and variant labels so customers never lose track of which code belongs to which purchase.

Checkout flow — how to create an order and receive vouchers.
Orders — full order lifecycle and status semantics.
Admin fulfillment recovery — how operators manually deliver vouchers for stuck orders.