Commerce
Promotions
Discount codes, automatic promotions, and campaigns.
A promotion discounts a cart. Buyers apply it with a code, or it applies itself when is_automatic is true. Discounts show on the cart as adjustments on lines and shipping methods.
How a promotion is defined
| Part | Meaning |
|---|---|
type | standard, or buyget for "buy X, get Y" offers. |
status | draft, active, or inactive. Only active promotions apply. |
code | What buyers type. Automatic promotions have a code too. |
limit | Optional total number of uses. |
rules | Conditions on the cart, such as customer group, region, country, sales channel, or currency. |
application_method | What is discounted and by how much. See below. |
Application method
| Field | Values |
|---|---|
type | fixed (an amount, needs currency_code) or percentage |
target_type | items, shipping_methods, or order |
allocation | each: the value applies to each matching item. across: the value is split across matching items. once: applied once, up to max_quantity items. |
target_rules | For items: product, category, collection, type, or tag. For shipping_methods: the shipping option type only. |
buy_rules | For buyget: what must be in the cart, with buy_rules_min_quantity and apply_to_quantity. |
B2B use
Target a company with a customer.groups.id rule on the company's customer group. Prefer price lists for standing contract prices, and promotions for time-limited offers.
Campaigns
A campaign groups promotions with a shared start date, end date, and optional budget. Budget types are spend (total discount amount) and usage (number of uses), plus per-attribute variants such as per customer. A promotion stops applying once its campaign ends or its budget runs out.
In the storefront
curl -X POST http://localhost:9000/store/carts/cart_.../promotions \
-H "x-publishable-api-key: pk_..." \
-H "Content-Type: application/json" \
-d '{ "promo_codes": ["SPRING10"] }'- Add and remove codes on a cart.
- An unknown code fails with
400. A known code whose rules don't match adds no discount, so read the cart's adjustments to see what applied. - Automatic promotions are re-evaluated on every cart change. Nothing to call.
- Uses and campaign budgets are counted when the cart is completed, not when a code is applied.