/bff/voucher/list

Returns a paginated list of vouchers for the authenticated organisation. Default order is status-aware: active vouchers expiring soon first, then active, then awaiting activation, limit-reached, expired, and finally manually deactivated. Within each group the rows are ordered by valid_to ascending and then last_used_date descending. Each voucher includes usage statistics, validity information, cost, revenue (sum of paid order totals where used), unique customer count, recent burn rate, and source-order linkage. Supports full-text search on code/note, type filter, computed-status filter, and orthogonal segment filter.

VouchergetBffVoucherList

Parameters

6 query

6 total

Query · 6

pagestring

Page number (1-based) for pagination.

limitstring

Maximum items per page (1–500, default 50).

filterFulltextQuerystring

Full-text search across voucher code and internal note.

typestring

Filter by voucher type: fixed, percentage, free-credit, or free-product.

statusstring

Filter by computed status. Allowed values: active, inactive, expired, not-yet-valid, limit-reached.

segmentstring

Behavioural segment, orthogonal to status (can be combined). Allowed values: expiring-soon (active and within 30 days of validTo), hot (used at least once in the last 7 days), gift-card (generated from a source order, i.e. product voucher template), never-used (created 30+ days ago, never redeemed), unlimited (no usage limit set).

Request

GET /bff/voucher/list

get

curl -X GET "https://api.bizkithub.com/bff/voucher/list?page=1&limit=50&filterFulltextQuery=SUMMER&type=percentage&status=active&segment=expiring-soon" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Paginated list of vouchers with metadata.

{
  "items": [
    {
      "id": "example_id",
      "value": "example_value",
      "usageLimit": 0,
      "usedCount": 0,
      "usedOrderCount": 0,
      "active": false,
      "isOrderSingleton": false,
      "note": "example_note",
      "revenue": "example_revenue",
      "uniqueCustomers": 0,
      "burnRate7d": 0,
      "burnRate30d": 0
    }
  ],
  "itemCount": 0
}

All response codes

1 status code documented

Need an API key?

All BizKitHub API endpoints require authentication via API key.

Get API Key