Gift Voucher Redemption

Working with custom domains

In the following article, links will be referenced as originating from system.spektrix.com. If you have implemented a custom domain for your Integration, please replace system.spektrix.com with your chosen subdomain.

Gift Voucher Redemption lets a customer redeem a gift voucher code directly through API v3, converting its value into account credit immediately. This means you can offer a fully branded, custom experience for redeeming vouchers, without needing to redirect customers to embedded iframe solutions.

Monetary vouchers credit their full amount to the customer's account balance immediately; membership vouchers credit the membership's gift value and return the associated membership ID (see Membership voucher below). Available in API v3, web mode and system owner mode — the basket must have an associated customerId (supplied automatically via customer authentication in web mode, or provided directly in system owner mode), and a voucher can be redeemed at any point once a customer is associated with the basket, not just at checkout.

Redeeming a voucher

Web / Public mode

POST

https://system.spektrix.com/{clientname}/api/v3/customer/redeem-gift-voucher

System Owner mode

POST

https://system.spektrix.com/{clientname}/api/v3/customers/{id}/redeem-gift-voucher

Request body

{
  "voucherCode": "A-BCDE-FGHI"
}

Field	Type	Required	Description
voucherCode	string	Yes	The gift voucher code to redeem

Success responses

Monetary voucher

Response (HTTP 200)

{
  "voucherCode": "A-BCDE-FGHI",
  "voucherAmount": 50.00,
  "creditBalance": 150.00,
  "membership": null
}

Field	Type	Description
voucherCode	string	The redeemed voucher code
voucherAmount	decimal	The amount redeemed
creditBalance	decimal	The customer's updated credit balance
membership	object or null	null for monetary vouchers

Membership voucher

Response (HTTP 200)

{
  "voucherCode": "M-STUV-WXYZ",
  "voucherAmount": 100.00,
  "creditBalance": 100.00,
  "membership": {
    "id": "1204AHLTTVQCPBTQQBMJLLSCGGSBNVBRR"
  }
}

Field	Type	Description
voucherCode	string	The redeemed voucher code
voucherAmount	decimal	The membership gift value redeemed
creditBalance	decimal	The customer's updated credit balance
membership	object	Membership details object
membership.id	string	The membership identifier

The response only tells you which membership the voucher relates to — it does not tell you whether the customer already holds it or whether it's currently for sale. You're responsible for checking this yourself:

• Check whether the customer already holds the membership using GET /customer (web mode) or GET /customers/{id} (system owner mode) with $expand=subscriptions — see Expanding Memberships
• Check whether the membership is currently available for sale using GET /memberships

You can then decide whether to add the membership to the customer's basket or show an appropriate message.

Error responses

All error responses use HTTP 4xx status codes and include an error code and a developer-friendly message.

HTTP Status	Scenario	Message
400	Code is invalid or blank	"The voucher code format is invalid."
400	Voucher expiry date has passed	"This voucher has expired."
400	Voucher has already been redeemed	"This voucher has already been redeemed."
400	Code does not exist in the system	"We couldn't find a voucher with that code."
401	Customer has not authenticated (web mode)