Add discounts

Learn how to apply discounts with coupons and promotion codes in your custom integration.

You can use discounts to reduce the amount charged to a customer. Coupons and promotion codes allow you to:

Apply a discount to an entire purchase subtotal
Apply a discount to 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

Create a coupon

Coupons specify a fixed value discount. You can create customer-facing promotion codes that map to a single underlying coupon. This means that the codes FALLPROMO and SPRINGPROMO can both point to one 25% off coupon. You can create coupons in the Dashboard or with the API:

Use a coupon

To create a session with an applied discount, pass the coupon ID in the coupon parameter of the discounts array. Checkout Sessions support up to one coupon or promotion code.

Configure a coupon

Coupons have the following parameters that you can use:

currency
percent_off or amount_off
max_redemptions
redeem_by: The latest date customers can apply the coupon
applies_to: Limits the products that the coupon applies to

Limit redemption usage

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.

Limit eligible products

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 only apply to the list of eligible products.

Delete a coupon

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

Create a promotion code

Promotion codes are customer-facing codes created on top of coupons. You can also specify additional restrictions that control when a customer can apply the promotion. You can share these codes with customers who can enter them during checkout to apply a discount.

To create a promotion code, specify an existing coupon and any restrictions (for example, limiting it to a specific customer). If you have a specific code to give to your customer (for example, 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 can’t reuse that code for a promotion code redeemable by any customer.
If you create a promotion code that is redeemable by any customer, you can’t 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:

Use a promotion code

On your server, enable customer-redeemable promotion codes using the allow_promotion_codes parameter in a Checkout Session.

On your client, use applyPromotionCode to apply a promotion code that your customer enters. Use removePromotionCode to remove all previously applied promotion codes.

index.html
<input type="text" id="promotion-code" />
<button id="apply-promotion-code">Apply</button>
<button id="remove-promotion-codes">Remove</button>
<div id="promotion-code-error"></div>

checkout.js
stripe.initCheckout({fetchClientSecret}).then((checkout) => {
  const input = document.getElementById('promotion-code');
  document.getElementById('apply-promotion-code').addEventListener('click', () => {
    checkout.applyPromotionCode(input.value).then((result) => {
      if (result.error) {
        // Display an error message
        document.getElementById('promotion-code-error').textContent = result.error.message;
      } else {
        // Clear the input if the promotion code was successfully applied
        input.value = '';
      }
    });
  });
  document.getElementById('remove-promotion-codes').addEventListener('click', () => {
    checkout.removePromotionCode();
  });
});

Configure a promotion code

For each promotion code, you can customize eligible customers, redemptions, and other limits.

Limit by customer

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

Limit by first-time order

You can also limit the promotion code to first-time customers with restrictions.first_time_transaction. If the customer isn’t defined, or if a defined customer has no prior payments or non-void invoices, it’s considered a first-time transaction.

Note

Sessions that don’t create Customers instead create Guest Customers in the Dashboard. Promotion codes limited to first-time customers are still accepted for these Sessions.

Set a minimum amount

With promotion codes, you can set a minimum transaction amount for eligible discount by configuring minimum_amount and minimum_amount_currency. 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 expiration date for the promotion code can’t be later than that of the coupon. If promotion_code[expires_at] isn’t 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 can set coupon[redeem_by] to one year from now, and set each promotion_code[expires_at] to one week after it’s created.

Limit redemptions

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

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 can 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. You can’t reactivate these promotion codes.

Delete promotions

You can delete promotions in the Dashboard or the API. Deleting a promotion prevents it from being applied to future transactions or customers.