Discounts & vouchers · Nevios docs

Two related domains:

Discounts — Shopify-style codes, BOGO, bulk pricing, automatic promotions. Reduce order value at checkout.
Vouchers — gift cards / store credit. Carry a redeemable balance with partial redemption support.

Discount types

`type`	Description
`discount_code`	Customer enters a code (`SAVE10`)
`automatic_discount`	Applied without input when conditions match
`gift_card`	Discount issued from a voucher (special case)
`buy_x_get_y`	BOGO (`bogo_config` JSONB describes mechanics)
`bulk_pricing`	Tiered (`bulk_tiers` JSONB)
`shipping_discount`	Reduces shipping (free shipping thresholds)

Value modes

`value_mode`	Behavior
`percentage`	`value_amount` is basis points (1000 = 10.00%)
`fixed_amount`	`value_amount` cents in `currency`; min(amount, subtotal)
`set_price`	Set the order to a target price; discount = difference
`free`	100% off

Create a code

curl -X POST "$API/discounts.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{
    "type": "discount_code",
    "code": "SAVE10",
    "title": "10% off everything",
    "value_mode": "percentage",
    "value_amount": 1000,
    "applies_to": "order",
    "stackable": false,
    "minimum_order_subtotal_cents": 50000,
    "customer_eligibility": "all",
    "first_order_only": false,
    "usage_limit_total": 1000,
    "usage_limit_per_customer": 1,
    "starts_at": "2026-05-01T00:00:00Z",
    "ends_at": "2026-06-01T00:00:00Z",
    "status": "active"
  }'

stackable controls multi-discount behavior — non-stackable discounts replace whatever was applied. Customer eligibility supports all | tagged | segments | specific | first_order.

Apply at checkout

The storefront calls:

curl -X POST "$SF/checkouts/{token}/discount.json" \
  -H "X-Storefront-Key: $SK" -H "Content-Type: application/json" \
  -d '{"code":"SAVE10"}'

The checkout service validates: window dates, archived status, market scope, customer eligibility, per-customer usage limit, total usage limit. Applies the discount and recomputes totals (CZ VAT respected — tax computed on post-discount totals).

Remove with DELETE /checkouts/{token}/discount/{code}.json.

Vouchers (gift cards)

curl -X POST "$API/vouchers.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{
    "initial_balance_cents": 100000,
    "currency": "CZK",
    "recipient_email": "[email protected]",
    "expires_at": "2027-05-01T00:00:00Z"
  }'

Response includes the code (XXXX-XXXX-XXXX-XXXX, 16 chars, globally unique across tenants). The recipient enters the code at checkout (or in the dashboard) to redeem.

curl -X POST "$API/vouchers/redeem.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{"code":"WXYZ-...","amount_cents":30000,"order_id":308...}'

Partial redemption supported. Balance hits zero → status flips to depleted. Voucher lifecycle: active → depleted | expired | disabled | revoked.

Redemption ledger

Both discount_redemptions and voucher_redemptions are append-only audit logs. Use them for monthly accounting reports and per-customer usage caps. POST /vouchers/{id} (GET) returns the full payment_attempts array for support staff.

Endpoints

POST   /admin/2026-01/{handle}/discounts.json
GET    /admin/2026-01/{handle}/discounts.json
PUT    /admin/2026-01/{handle}/discounts/{id}.json
DELETE /admin/2026-01/{handle}/discounts/{id}.json   (archive)

POST   /admin/2026-01/{handle}/vouchers.json
GET    /admin/2026-01/{handle}/vouchers.json
GET    /admin/2026-01/{handle}/vouchers/{id}.json
POST   /admin/2026-01/{handle}/vouchers/redeem.json
DELETE /admin/2026-01/{handle}/vouchers/{id}.json   (disable)

Next: Shipping.