Przewodnik

Discounts and promotions

A discount is either a code the customer types (code set) or an automatic promotion (is_automatic: true) that applies whenever its conditions are met.

Types

`discount_type`	`value` meaning	Example
`percentage`	Percent off eligible items	`10` → 10% off
`fixed`	Amount off in minor units of the cart currency, spread across eligible items	`2000` → 20.00 off
`free_shipping`	Ignored; makes the chosen shipping rate free
`bundle`	Percent off when all `bundle_product_ids` are in the cart	`15` → 15% off the bundle items
`volume`	Ignored; uses `volume_tiers` `[{"min_qty": 3, "percent": 5}, {"min_qty": 10, "percent": 12}]`	Buy 10+ of eligible items, get 12% off

Conditions

Field	Meaning
`applies_to`	`all`, `products` (uses `product_ids`) or `collections` (uses `collection_ids`)
`min_subtotal`	Minimum cart subtotal in minor units
`min_quantity`	Minimum number of eligible items
`starts_at`, `ends_at`	Active time window
`usage_limit`	Total number of uses across all customers
`usage_per_customer`	Uses per customer email
`active`	Manual on/off switch
`combinable`	Whether this discount can be combined with other discounts

Combination rules

All matching automatic discounts and entered codes are evaluated. Every combinable discount applies; of the non-combinable ones only the single best one for the customer applies. Percentage discounts are capped at 100% and fixed discounts at the eligible subtotal, so a line never goes below zero.

Validating a code

json

POST /discounts/validate
{ "code": "SPRING10", "lines": [{ "variant_id": "…", "quantity": 2 }], "email": "buyer@example.com" }

Returns valid, a human-readable message when invalid (expired, usage limit reached, minimum not met, not applicable…), the applied discount, the resulting discount_total and free_shipping. To apply the code, save it on the cart with PATCH /carts/:token and discount_code.

Reporting

Uses, discount amount given and revenue per code are shown in Analytics, and in report.discounts of GET /analytics/summary.