Discounts, gift cards & store credit

Kustom has no discount UI. Every reduction is expressed in the order lines, which means a promotion is something your own system prices and Kustom renders — not a feature you switch on.

Coming soon: better support inside Kustom Checkout. Handling discounts, gift cards and store credit in the checkout itself is on the way. Until then, express every reduction as an order line, as shown below.

A discount on one line

A 20% reduction on a shirt at 25% VAT uses total_discount_amount on that line, with total_amount already reduced:

{
  "type": "physical",
  "name": "White t-shirt",
  "reference": "12-345-ABC",
  "quantity": 1,
  "unit_price": 30000,
  "tax_rate": 2500,
  "total_amount": 25000,
  "total_discount_amount": 5000,
  "total_tax_amount": 5000
}

An order-level discount

Its own line, with negative amounts and type: "discount". A fixed 10.00 off at 25% VAT:

{
  "type": "discount",
  "name": "10.00 discount",
  "reference": "12-345-ABC-discount",
  "quantity": 1,
  "unit_price": -1000,
  "tax_rate": 2500,
  "total_amount": -1000,
  "total_tax_amount": -200
}

Multi-buy offers

Three for the price of two, and so on, are the same shape as an order-level discount: work out the cash value of the offer, put it on a discount line as a negative total_amount and derive total_tax_amount from it with the formula in How VAT lands on a reduction.

Gift cards and store credit

These are not discounts, because no VAT is due when they are sold — only when they are spent. Redeem them as a negative line at 0% tax, typed gift_card:

{
  "type": "gift_card",
  "name": "Gift card",
  "reference": "voucher",
  "quantity": 1,
  "unit_price": -10000,
  "tax_rate": 0,
  "total_amount": -10000,
  "total_tax_amount": 0
}

Store credit issued for a return is handled the same way, typed store_credit. Loyalty points and bonus cheques are agreed case by case with Kustom, but a bonus cheque generally behaves as a voucher.

A voucher that covers the whole cart leaves a zero-amount order, which needs no configuration: Kustom shows no payment methods, leaves the purchase button active and the confirmation page reports a completed zero-amount order.

How VAT lands on a reduction

VAT is calculated on the discounted price. The tax on any line is:

total_amount - total_amount * 10000 / (10000 + tax_rate)

Whatever shape a reduction takes below, order_amount must still equal the sum of the line totals. That’s the invariant the whole order is checked against.

Related

• Order lines and tax — the order line in full
• Checkout options — the rest of the order’s configuration
• Checkout API reference — the authoritative schema for every field here