Backdate subscriptions

You can backdate a subscription to bill customers for time that has already elapsed. This is often used when migrating to Stripe or for record keeping purposes. The backdate_start_date field specifies the subscription’s backdated start date. You also have the option to bill customers for this elapsed time and set the next billing date.

Backdating and charging users

Sometimes users can have access to your service before you create a subscription for them, and you want to charge them for that access.

This creates an invoice with a prorated amount for the time between the backdated start date and the current time. The prorated amount is calculated based on an imagined interval that starts on the backdated start date. For example, if the billing interval is monthly on the first of the month, and you set the backdate_start_date to 15 February (in a non-leap year), the proration calculation is based on a month running 15 February to 15 March. Because that imagined month is 28 days, the prorated amount for the 14 days of 15 February to 1 March is exactly half the amount of a normal monthly charge.

Similarly, if you set the backdate_start_date to 15 January, the proration calculation is based on an imagined month running 15 January to 15 February. Because that month is 31 days, the pro-rata amount for the 17 days of 15 January to 1 February is 17 divided by 31 (or 0.548) of a normal monthly charge.

Another way to think about the calculation is to look at the backdated start date as the original start date and the beginning of the first full billing period as an updated start date.

Backdating without charging users

You can also backdate a subscription without charging the customer for the backdated period, which you can use if you’re migrating to Stripe. To do so, pass proration_behavior: 'none' when you create the subscription. That sets the start_date to the same value as backdate_start_date, but it doesn’t charge the customer for backdated time.

Backdating and setting the billing cycle anchor

You can combine backdate_start_date with billing_cycle_anchor to backdate a subscription and set the billing cycle anchor to a date in the future. This creates a pro-rata item on the next invoice for the time between the backdated start date and the billing cycle anchor. You can use this if you’re migrating to Stripe and need to carry over the next billing date for your subscriptions while billing customers for elapsed time.

For example, say it’s 15 October and you’re migrating to Stripe. You have a subscription that started on 1 September, and the next billing date is 1 November. To migrate that subscription, create a new subscription and set backdate_start_date to 1 September and billing_cycle_anchor to 1 November.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d backdate_start_date=1575176400 \
  -d billing_cycle_anchor=1572580800 \
  -d "items[0][price]"=
{{PRICE_ID}}

This immediately issues an invoice for the pro-rata amount covering the time between 1 September and 1 November. It also sets the start_date of the subscription to 1 September. Stripe issues the next invoice on 1 November.

Backdating an update

To set the effective date of prorations when updating a subscription, use the proration_date parameter. Pass an integer Unix timestamp within the subscription’s items’ current period. If the subscription is backed by a subscription schedule, make sure that the timestamp is before the start date of the next phase of the subscription schedule.

You can set a proration_date earlier than the current period only during the first period of a backdated subscription. In this case, the proration_date can be on or after the subscription[start_date] (backdated start date). In all other cases, the proration_date can’t be before the current_period_start.