Skip to main content

Recurring interval

recurringInterval is the field on a plan that defines when a subscription renews and how often. A plan with recurringInterval is a subscription plan; a plan without it is a one-time plan.

Field overview​

recurringInterval: {
  unit: 'day',              // 'day' | 'week' | 'month' | 'year'
  length: 1,                // number of units between renewals
  limit: 1,                 // max number of invoices; omit or 0 = unlimited
  billingTiming: 'prepaid', // 'prepaid' | 'postpaid'
  periodAnchorInstruction: { // optional — see below
    method: 'day-of-month',
    day: 20
  }
}
FieldDescription
unitUnit of time between renewals: day, week, month, or year.
lengthHow many units between renewals. unit: 'month', length: 1 renews monthly; length: 3 renews every three months.
limitMaximum number of invoices the subscription will generate. Set to 1 for a single-renewal subscription; omit (or 0) for unlimited.
billingTimingprepaid charges at the start of each cycle (the default); postpaid charges at the end.
periodAnchorInstructionOptional. Pins the renewal day to a specific calendar day instead of using the activation date as the anchor. Omit for "renew on whatever day this subscription started."

Anchoring to a day of the month​

periodAnchorInstruction: {
  method: 'day-of-month',
  day: 1 // 1 to 31
}

The subscription renews on the specified day each month, regardless of when it was activated. day: 1 renews every subscription on this plan on the 1st of the month.

For behavior when the anchor day does not exist in a month (28th, 30th, 31st in February, 31st in 30-day months), see Billing cycles.

Anchoring to a day of the week​

periodAnchorInstruction: {
  method: 'day-of-week',
  day: 'Monday', // 'Sunday' | 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday'
  week: 'next'   // 'next' | 'first-in-month' | 'last-in-month'
}
week valueMeaning
nextThe next occurrence of the named day.
first-in-monthThe first occurrence of the named day in each month.
last-in-monthThe last occurrence of the named day in each month.

Billing timing​

prepaid is the default and the more common pattern: the customer is charged at the start of the cycle for the period that is about to start. postpaid charges at the end of the cycle for the period that has just finished — useful for usage-based pricing where the final amount is not known until the cycle closes.