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 GBP annual subscription applies to 40 GBP of service and discounts 20 GBP. |
| 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 GBP monthly iterations apply up to 90 GBP 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 GBP of previously discounted service, that 20 GBP 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 15 January and the current period ends 1 February, the 1 February 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 15 January can have a shortened first iteration that ends at the 1 February 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 GBP during each two-month iteration. With three iterations, it lasts six months and provides up to 60 GBP 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 GBP annual subscription discounts 50% of the 40 GBP attributable to those two months, resulting in a 20 GBP 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 GBP allowance and the first eligible charge is 150 GBP, Stripe discounts 150 GBP. Other eligible charges, such as debit prorations, can use the remaining 50 GBP 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 1 January to 1 February, and you apply the coupon on 15 January:
| Start date | Discount starts | Result |
|---|---|---|
current_period_start | 1 January | 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 | 15 January | Applies the discount only to service provided on or after 15 January and creates prorations. |
current_period_end | 1 February | Leaves the current subscription item service period undiscounted. The renewal on 1 February 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 1 February.
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 15 January, and the subscription renews on the first day of each month:
- Subscription service cycle anchor: The first iteration runs from 15 January to 1 February. 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 15 January to 15 February, 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