BizKitHub Developer Documentation

Parameters

6 query

Query parameters

· 6

pagestringOptional

Page number (1-based) for pagination.

Example1

limitstringOptional

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

Example50

filterFulltextQuerystringOptional

Full-text search across voucher code and internal note.

ExampleSUMMER

typestringOptional

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

Examplepercentage

statusstringOptional

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

Exampleactive

segmentstringOptional

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

Exampleexpiring-soon

Response schema

1 status code documented

200SuccessPaginated list of vouchers with metadata.

itemsobject[]Required

Array of voucher items matching the query criteria.

Each array item:

Single voucher item in the list.

idstringRequired

Voucher code (unique identifier within organisation).

type"fixed" | "percentage" | "free-credit" | "free-product"Required

Discount type. "fixed" = fixed amount discount, "percentage" = percentage discount, "free-credit" = adds credit to customer account, "free-product" = adds free product to order.

valuestringRequired

Discount value (amount for fixed, percentage for percentage type).

usageLimitnumberOptional

Maximum number of times voucher can be used. Null if unlimited.

usedCountnumberRequired

Number of times voucher has been used.

usedOrderCountnumberRequired

Number of orders that have used this voucher.

activebooleanRequired

Whether voucher is currently active (computed from all conditions).

isOrderSingletonbooleanRequired

If true, voucher can only be applied once per order.

notestringRequired

Internal note (truncated to 100 characters in list view).

lastUsedDateDate | string | string | numberOptional

Date when voucher was last used.

One of 4:

Variant 1

Date

Date when voucher was last used.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

validFromDate | string | string | numberOptional

Start date of validity period.

One of 4:

Variant 1

Date

Start date of validity period.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

validToDate | string | string | numberOptional

End date of validity period.

One of 4:

Variant 1

Date

End date of validity period.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

insertedDateDate | string | string | numberRequired

Date when voucher was created.

One of 4:

Variant 1

Date

Date when voucher was created.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

updatedDateDate | string | string | numberRequired

Date when voucher was last modified.

One of 4:

Variant 1

Date

Date when voucher was last modified.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

costnumber | nullRequired

Money the voucher cost when issued (organisation default currency). null = unknown (1:1 fallback), 0 = explicitly gifted.

One of 2:

Variant 1

number

Variant 2

null

revenuestringRequired

Sum of shop__order.price for orders that used this voucher and reached paid status. Stringified to preserve decimal precision.

uniqueCustomersnumberRequired

Distinct customers that have redeemed this voucher.

burnRate7dnumberRequired

Number of redemptions in the last 7 days.

burnRate30dnumberRequired

Number of redemptions in the last 30 days.

sourceOrderIdnumber | nullRequired

Order that generated this voucher (product-voucher template fulfilment). Null for manually created vouchers.

One of 2:

Variant 1

number

Variant 2

null

sourceOrderNumberstring | nullRequired

Source order number, mirroring sourceOrderId.

One of 2:

Variant 1

string

Variant 2

null

sourceOrderHashstring | nullRequired

Source order hash (used as the admin order detail route segment).

One of 2:

Variant 1

string

Variant 2

null

itemCountnumberRequired

Total number of vouchers matching the query (before pagination).

Response example

application/json

{
  "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
}

/bff/voucher/list

Parameters

Query parameters

Response schema

Response example

Request example

Need an API key?