Discounts and vouchers

Discount codes and single-use vouchers.

The API distinguishes two mechanisms: discount codes (reusable, reduce the price) and vouchers (single-use, exchanged for a product).

Discount codes

A discount code reduces the order price by a percentage or a fixed amount.

Field	Description
scope	Scope: all, server, product
targets	Server/product IDs for a scope other than all
type	percentage or fixed
value	Discount value
expirationDate	Expiration date
maxUsage	Maximum number of uses
minOrderValue	Minimum order value
maxDiscountAmount	Upper limit on the discount amount

Validation before purchase

The customer can check a code publicly:

curl -X POST http://localhost:3000/api/v2/discounts/validate \
  -H "Content-Type: application/json" \
  -d '{ "code": "SUMMER10", "shopId": "<shopId>", "orderValue": 50 }'

The response contains valid, discountAmount, and finalPrice. The code is also applied when creating an order through the discountCode field.

A 100% discount that reduces the amount to zero bypasses the payment gateway and sends the order to plugin fulfillment. See Payments.

Vouchers

A voucher is a single-use code that the customer exchanges for a specific product — without payment.

Generation

A staff member with the vouchers:write permission creates a single voucher (POST /vouchers/{shopId}) or generates a batch (POST /vouchers/{shopId}/generate).

Redemption

curl -X POST http://localhost:3000/api/v2/vouchers/redeem \
  -H "Content-Type: application/json" \
  -H "cf-turnstile-response: <turnstile-token>" \
  -d '{ "code": "ABC123", "shopId": "<shopId>", "nickname": "Steve" }'

The Turnstile header is required in production. After redemption, an order is created for plugin fulfillment and the response contains a trimmed data shape plus a statusToken. The voucher becomes used. Expired vouchers are marked periodically.