Add discounts for one-time payments

Reduce the amount charged to a customer by discounting their subtotal with coupons and promotion codes.

You can use discounts in Checkout to reduce the amount charged to a customer for one-time payments. Coupons and promotion codes allow for great flexibility in how you define and use them. They can:

Apply a discount to the entire subtotal or specific products
Reduce the total charged by a percentage or a flat amount
Create customer-facing promotion codes on top of coupons to share directly with customers

You can create customer-facing codes that map to a single underlying coupon. For example, promotion codes FALLPROMO and SPRINGPROMO could both point to a single 25% off coupon.

To use coupons for discounting subscriptions with Checkout and Billing, see how to apply discounts to subscriptions.

Checkout does not currently support discounting a purchase below the minimum charge amount for one-time payments.

Creating coupons

Coupons specify how much to discount. They have the following parameters that can be used for one-time payments:

id, a unique identifier for the coupon
currency
percent_off or amount_off
max_redemptions
redeem_by, the latest date at which this coupon can be applied
applies_to, limits the products that the coupon will apply to

The max_redemptions and redeem_by values apply to the coupon across every application. For example, you can restrict a coupon to the first 50 usages of it, or you can make a coupon expire by a certain date.

You can limit the products that are eligible for discounts using a coupon by adding the product IDs to the applies_to hash in the Coupon Object. Any promotion codes that map to this coupon are also restricted to this list of eligible products.

Coupons can be created in the Dashboard or with the API:

Terminal

curl https://api.stripe.com/v1/coupons \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "percent_off"=20 \
  -d "duration"="once"

If you want to create a session with an applied discount, pass the coupon ID in the coupon parameter of the discounts array. Checkout currently supports up to one coupon or promotion code.

Terminal

curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_types[]"=card \
  -d "line_items[][price]"="{{PRICE_ID}}" \
  -d "line_items[][quantity]"=1 \
  -d mode=payment \
  -d "discounts[][coupon]"="{{COUPON_ID}}" \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Creating promotion codes

Promotion codes are customer-shareable codes created on top of coupons. You may also specify additional restrictions that control when the promotion code can be applied. These codes may be shared with customers for them to input into Checkout to apply a discount.

To create a promotion code, specify an existing coupon and any restrictions (for example, limiting to a specific customer). If you have a specific code you’d like to give to your customer (e.g., FALL25OFF), set the code. If you leave this field blank, we’ll generate a random code for you.

The code is case-insensitive and unique across active promotion codes for any customer. For example:

You can create multiple customer-restricted promotion codes with the same code, but you cannot reuse that code for a promotion code redeemable by any customer.
If you create a promotion code that is redeemable by any customer, you cannot create another active promotion code with the same code.
You can create a promotion code with code: NEWUSER, inactivate it by passing active: false, and then create a new promotion code with code: NEWUSER.

Promotion codes can be created in the coupons section of the Dashboard or with the API:

Terminal

curl https://api.stripe.com/v1/promotion_codes \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "coupon"="{{COUPON_ID}}" \
  -d "code"="VIPCODE"

Enable user-redeemable promotion codes using the allow_promotion_codes parameter in a Checkout Session. This enables a field in Checkout to allow users to input promotion codes.

Terminal

curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_types[]"=card \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=usd \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d allow_promotion_codes=true \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Promotion code configurations

By configuring the promotion code object parameters, you can customize which customers are eligible, how many times a promotion can be redeemed, when a promotion code expires, or set a minimum amount the discount can be applied to.

Limit by customer

To limit a promotion to a particular customer, specify a customer when creating the promotion code. If no customer is specified, the code can be redeemed by any customer.

Limit by first time order

You can also limit the promotion code to first time customers with the first_time_transaction parameter of the restrictions attribute. If the customer is not defined or if a defined customer has no prior payments or non-void invoices, it is considered a first time transaction.

Set a minimum amount

With promotion codes, you can set a minimum transaction amount for eligible discount by configuring the minimum_amount and the minimum_amount_currency properties. Since promotion code restrictions are checked at redemption time, the minimum transaction amount only applies to the initial payment for a subscription.

Customize expirations

You can set an expiration date on the promotion code using expires_at. If the underlying coupon already has redeem_by set, then the promotion code’s expiration date cannot be later than the coupon’s. If promotion_code[expires_at] is not specified, the coupon’s redeem_by automatically populates expires_at.

For example, you might have plans to support a coupon for a year, but you only want it to be redeemable for one week after a customer receives it. You would set coupon[redeem_by] to one year from now, and set each promotion_code[expires_at] to one week after it is created.

Limit redemptions

You can limit the number of redemptions by using max_redemptions, which works similarly to coupons. If the underlying coupon already has max_redemptions set, then the promotion code’s max_redemptions cannot be greater than the coupon’s.

For example, you might want a Seasonal Sale coupon to be redeemable by the first 50 customers, but the winter promotion can only use 20 of those redemptions. In this scenario, you would set coupon[max_redemptions]: 50 and promotion_code[max_redemptions]: 20.

Inactive promotions

You can set whether a promotion code is currently redeemable by using the active parameter. However, if the underlying coupon for a promotion code becomes invalid, all of its promotion codes become permanently inactive. Similarly, if a promotion code reaches its max_redemptions or expires_at, it becomes permanently inactive. These promotion codes cannot be reactivated.

Deleting coupons

You can delete coupons via the Dashboard or the API. Deleting a coupon prevents it from being applied to future transactions or customers.