BizKitHub
DocsAPI ReferenceVoucher/bff/voucher/analyze
getVoucherAdmin BFF

/bff/voucher/analyze

Returns a lightweight snapshot of a voucher: whether it exists in the organisation and, if it does, its computed status (active / inactive / expired / not-yet-valid / limit-reached). Unlike /full-detail, this endpoint does NOT throw when the voucher is missing. BIZKIT-19: when redeemContext is supplied, the response additionally carries the engine rejection reason this voucher would hit for that context.

VouchergetBffVoucherAnalyze

Parameters

3 query

Query parameters

· 3
codestringRequired

Voucher code to analyze.

ExampleSUMMER2024
redeemContextstringOptional

Optional redemption context. "order" = voucher is being added to a reservation/order; "voucher_page" = voucher is being redeemed on the dedicated voucher-redeem page. When present, the response includes rejectionReason/rejectionMessage reflecting what the order engine would answer today.

Exampleorder
contactIdstringOptional

Optional numeric contact id. Required to resolve "single-use per customer" rejection ahead of time. When omitted the final check still runs during order creation.

Example12345

Response schema

1 status code documented

200SuccessVoucher analysis result.
object | object

Voucher analysis result.

One of 2:
Variant 1

Voucher not found.

exists"false"Required

Voucher with this code does not exist.

rejectionReason"code_not_found"Required

Always "code_not_found" for the exists=false branch.

rejectionMessagestringRequired

Human-readable reason, pre-formatted for the frontend.

Variant 2

Voucher exists — snapshot with computed status.

exists"true"Required
codestringRequired

Voucher code (canonical, uppercase).

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

Discount type.

valuestringRequired

Discount value.

activebooleanRequired

Database active flag (does NOT consider expiration/limit).

effectivelyActivebooleanRequired

True if voucher is currently usable (active + within validity + below limit).

isValidbooleanRequired

Alias of effectivelyActive — convenient flag for UI consumers.

status"active" | "inactive" | "expired" | "not-yet-valid" | "limit-reached"Required

Computed status enum.

usedCountnumberRequired

Number of times voucher has been used.

usageLimitnumber | nullRequired

Maximum number of uses, or null if unlimited.

One of 2:
Variant 1
number
Variant 2
null
remainingUsagenumber | nullRequired

Remaining uses, or null if unlimited.

One of 2:
Variant 1
number
Variant 2
null
validFromDate | string | string | number | nullRequired

Validity start date.

One of 2:
Variant 1
Date | string | string | number
One of 4:
Variant 1
Date
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
Variant 2
null
validToDate | string | string | number | nullRequired

Validity end date.

One of 2:
Variant 1
Date | string | string | number
One of 4:
Variant 1
Date
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
Variant 2
null
daysUntilExpirationnumber | nullRequired

Days remaining until expiration, or null if no expiration or already expired.

One of 2:
Variant 1
number
Variant 2
null
lastUsedDateDate | string | string | number | nullRequired

Last usage date.

One of 2:
Variant 1
Date | string | string | number
One of 4:
Variant 1
Date
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
Variant 2
null
notestringRequired

Internal note (full content).

isOrderSingletonbooleanRequired

If true, voucher cannot be combined with other vouchers inside a single order.

singleUsePerCustomerbooleanRequired

If true, every customer may redeem this voucher on at most one order.

redeemableAtOrderbooleanRequired

If true, voucher may be redeemed on the reservation / order form.

redeemableAtVoucherPagebooleanRequired

If true, voucher may be redeemed on the dedicated "redeem voucher" page (typically used for free-credit vouchers).

rejectionReason"code_not_found" | "inactive" | "not_yet_valid" | "expired" | "usage_limit_reached" | "already_used_by_customer" | "wrong_redemption_context" | nullRequired

Rejection reason the order engine would answer for this voucher in the supplied redeemContext. Null when the voucher would be accepted or when redeemContext was not supplied.

One of 8:
Variant 1
"code_not_found"
Variant 2
"inactive"
Variant 3
"not_yet_valid"
Variant 4
"expired"
Variant 5
"usage_limit_reached"
Variant 6
"already_used_by_customer"
Variant 7
"wrong_redemption_context"
Variant 8
null
rejectionMessagestring | nullRequired

Human-readable rejection message. Null when accepted or no context passed.

One of 2:
Variant 1
string
Variant 2
null
acceptedForContext"order" | "voucher_page" | nullRequired

When the engine accepted the voucher this echoes the requested redeemContext; otherwise null.

One of 3:
Variant 1
"order"
Variant 2
"voucher_page"
Variant 3
null

Response example

application/json
{
  "exists": false,
  "rejectionReason": "code_not_found",
  "rejectionMessage": "example_rejectionMessage"
}

Request example

GET /bff/voucher/analyze

get
curl -X GET "https://api.bizkithub.com/bff/voucher/analyze?code=SUMMER2024&redeemContext=order&contactId=12345" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key