Private preview
Service period coupons Private preview
Discount a specific time window on a subscription regardless of billing cadence or invoice timing.
Private preview
Service period coupons are in private preview, and functionality might change during development. Use the registration form below to request access.
Service period coupons determine discount eligibility based on when you provide service, not when you create an invoice. Stripe discounts the portion of each subscription line item whose service dates overlap the discount’s service period schedule. Use a service period coupon when a promotion must apply to specific service dates instead of billing events.
Request access to service period coupons
Enter your email to request access.
Before you begin
Service period coupons have the following limitations:
- You can’t apply them to metered prices with max or last aggregation formulas.
- You can’t apply them to metered prices with tiers.
- You can’t add them to draft invoices.
- You can’t create them as script coupons.
- A service period coupon’s service cycle anchor doesn’t update if you later change the subscription’s service cycle anchor.
- They can create more invoice line items because Stripe doesn’t aggregate line items that represent separate service periods.
Choose a coupon type
Use a service period coupon when the discount must follow service dates instead of billing events.
| Goal | Classic coupon | Service period coupon |
|---|---|---|
| Discount a fixed service window across subscription cadences | Applies to the entire eligible line item created while the discount is active. A two month coupon can discount an entire annual line item. | Discounts only the portion of a line item whose service dates overlap the configured window. For example, a two month, 50% discount on a 240 USD annual subscription applies to 40 USD of service and discounts 20 USD. |
| Discount multiple service periods on one invoice | Applies one fixed amount to the eligible invoice. | Provides a separate amount-off allowance for each service period iteration. For example, three 30 USD monthly iterations apply up to 90 USD to one quarterly invoice. |
| Preserve an amount-off allowance during a plan change | Applies according to the billing events created by the plan change and doesn’t track a balance for a service period iteration. | Credit prorations restore previously consumed allowance, and eligible replacement charges can use the restored balance. For example, if a plan change credits 20 USD of previously discounted service, that 20 USD returns to the allowance for the same iteration. |
| Attach a discount now and start it in a future period | Doesn’t provide a coupon level start date setting. Your integration must wait to attach the coupon. | Set start_date=current_period_end to leave the current period undiscounted. For example, if you attach the coupon on January 15 and the current period ends February 1, the February 1 renewal is discounted. |
| End a discount at a subscription service cycle boundary | The coupon duration isn’t anchored to the subscription’s service cycle. | Use the subscription service cycle anchor to align iteration boundaries with the subscription. For example, a one month coupon that starts January 15 can have a shortened first iteration that ends at the February 1 renewal. |
| Apply a discount to the current service period | A discount-only update takes effect at a future billing event. | Adding an overlapping discount creates prorations. For example, after a service disruption, set proration_behavior=always_invoice to invoice the adjustment for the current service period immediately instead of waiting for the next renewal. |
Define the service period schedule
- Create a service period coupon by setting duration=service _ period .
- Use service _ period. interval and service _ period. interval _ count to define the length of each iteration.
- Use service _ period. iterations to define whether the iteration occurs a fixed number of times or continues indefinitely. Iterations are particularly significant for amount _ off coupons because each iteration provides a separate allowance. For percent _ off coupons, the percentage scales with the eligible service amount in each iteration. For example, the following coupon provides an allowance of up to 20 USD during each two month iteration. With three iterations, it lasts six months and provides up to 60 USD in total.
Command Line
cURL
Calculate the discount
Percent-off and amount-off service period coupons use the service period schedule specified in service_period, but calculate discounts differently.
Calculate a percent-off discount
A percent_off coupon applies its percentage to the portion of a line item whose service dates overlap the current iteration. For example, 50% off two months of a 240 USD annual subscription discounts 50% of the 40 USD attributable to those two months, resulting in a 20 USD discount.
Calculate an amount-off discount
An amount_off coupon provides a maximum allowance for each iteration. Stripe applies the allowance to eligible charges until it exhausts the allowance. Stripe doesn’t prorate the allowance according to the number of eligible service days. For example, if an iteration has a 200 USD allowance and the first eligible charge is 150 USD, Stripe discounts 150 USD. Other eligible charges, such as debit prorations, can use the remaining 50 USD during the same iteration. Eligible charges consume the allowance, and credit prorations restore it.
Apply a service period coupon
When you apply a service period coupon, Stripe creates a Discount with its own service period schedule. Configure discount settings to choose when the schedule starts and how its iterations align with the subscription’s service cycle.
Choose a start date
When you update a subscription to attach a coupon, use start_date to choose when the discount schedule begins. Suppose the current subscription item service period runs from January 1 through February 1, and you apply the coupon on January 15:
| Start date | Discount starts | Result |
|---|---|---|
current_period_start | January 1 | Sets the service period eligible for discounting to begin at the start of the current subscription item service period and creates prorations, but doesn’t discount service consumed before the update. |
now | January 15 | Applies the discount only to service provided on or after January 15 and creates prorations. |
current_period_end | February 1 | Leaves the current subscription item service period undiscounted. The renewal on February 1 is discounted. |
When an invoice line item spans the discount’s start date, Stripe creates prorations to apply the discount only to the overlapping service dates. Use proration_behavior to leave those adjustments pending or invoice them immediately. The following request starts the discount’s service period at the end of the current subscription item service period. Stripe creates the Discount immediately but doesn’t calculate a discount amount until the renewal on February 1.
Command Line
cURL
Align iterations to an anchor
The service period anchor controls where iteration boundaries fall. When you apply a coupon directly to a subscription, Stripe uses the subscription’s service cycle anchor by default. You can also provide a custom calendar anchor. Suppose a one month service period coupon starts on January 15, and the subscription renews on the first day of each month:
- Subscription service cycle anchor: The first iteration runs from January 15 through February 1. The anchor shortens the first iteration so that later iterations align with the subscription’s service cycle.
- Custom anchor on the fifteenth day of the month: The first iteration runs from January 15 through February 15, preserving an entire one month iteration from the discount’s start date. The following request starts the service period immediately and aligns its iteration boundaries with the subscription’s service cycle anchor.
Command Line
cURL