Overview
Manage automatic, scheduled, multi-phase checkout discounts.
Promotions apply automatic checkout discounts without a coupon code. Each promotion has ordered phases; the first eligible phase controls the active discount. Priority determines evaluation across promotions, while stackability controls whether a coupon can also apply.
Replacing phases is a complete replacement. Preserve any phase that should remain and send decimal monetary or percentage values as documented strings, not JSON floats. The operation schemas are authoritative for phase conditions, discount units, schedules, and redemption caps.
One-time and subscription promotions
A promotion discounts one kind of purchase, set by applies_to. A one_time
promotion, the default, discounts one-time purchases and always covers the
whole store. A subscriptions promotion discounts the first
subscription_payments payments of a subscription plan, from 1 to 36, counting
the signup payment as the first. A subscription promotion can't take 100% off;
offer a free trial instead.
A subscription promotion covers every plan in the store until you narrow it.
Send store_wide: false with the products it should reach, and optionally
product_variants to limit those products to certain plans. A picked product
with none of its plans listed takes every plan of that product, including plans
added later. Send store_wide in any request that sends products or
product_variants.
Which promotion a cart takes
A cart takes at most one promotion: the running promotion with the lowest
priority among those that fit it.
- A cart of one-time products takes a
one_timepromotion. - A cart with a subscription plan takes a
subscriptionspromotion that reaches the plan, as long as the chosen payment method can carry the discount, or, before one is chosen, any payment method the plan offers. Stripe and payment methods the store bills in house can; on Stripe, more than one discounted payment needs a monthly or yearly plan. PayPal and Razorpay can't, so they sell the plan at its full price. - On your storefront, a cart that mixes a plan with one-time products takes
only a
one_timepromotion, which discounts the one-time lines. The API refuses such a cart; see Buying a plan. - A plan takes one discount. When a coupon reaches it, the coupon wins, even over a stackable promotion. A plan that starts with a trial, or that a fixed discount would make free, takes no subscription promotion.
A subscription's renewals keep the discount but don't count as redemptions, so
max_redemptions counts each subscription once, at signup.
Subscription discounts explains how renewals
bill and what ends the discount early.