Overview
Create discount codes and choose who, what, and when they apply to.
Coupons apply an amount or percentage discount when a customer supplies a code. Choose which products qualify, how often the code can be used, and when it is valid. For discounts that apply without a code, use Promotions.
The response fields products and product_variants contain explicit product
and variant IDs that determine where the coupon applies.
Coupons and their linked products must belong to the selected store. Track batch requests in your integration and check what changed after a lost response before retrying; batch writes do not have a general idempotency guarantee. Each endpoint documents its discount units, limits, and date fields.
Subscription coupons
A coupon discounts one kind of purchase, set by applies_to. A one_time
coupon, the default, discounts one-time purchases. A subscriptions coupon
discounts the first subscription_payments payments of a subscription plan,
from 1 to 36, counting the signup payment as the first. A 20% coupon with
subscription_payments: 3 takes 20% off the signup and the next two renewals,
and the fourth payment bills the full plan price.
- A coupon only discounts order lines of its kind, and its
minimum_amountis measured on those lines. Theproductsandproduct_variantsyou add must be of its kind too, or the request returns422. - A subscription coupon can't take 100% off. Offer a free trial instead.
- Stripe and payment methods the store bills in house carry the discount. On Stripe, more than one discounted payment needs a monthly or yearly plan. PayPal and Razorpay sell the plan at its full price, and the order is created without the coupon.
- A subscription coupon doesn't apply to a plan that starts with a trial, or to a charge.
- Renewals keep the discount but not the coupon: a renewal order's
coupon_idis null, so the coupon'slimitcounts each subscription once.
Subscription discounts explains how renewals bill and what ends the discount early.