You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

The invoice for a subscription in Chargebee is generated at the time of subscription renewal. Invoices can also be generated in advance for an upcoming renewal or set of renewals. With Advance Invoicing Schedules, you can set up a plan for when such advance invoices are generated for the lifetime of the subscription. This helps you:

  • Set up a contract with your customers so that they can be notified of their payment schedules in advance.
  • Allow customers who make offline payments to be alerted about their upcoming dues well ahead of actual subscription renewals.
  • Prevent post-renewal unpaid usage of your services by customers.

Advance invoices can be scheduled in two ways:

Specific Dates Schedule

Advance invoices for a subscription can be scheduled to be generated on specific dates in the future. You must specify the number of billing cycles to be invoiced on each date. A maximum of 5 dates can be specified.

Fixed Interval Schedule

Advance invoices can be scheduled to be generated at fixed intervals of time, where each interval spans the same number of billing cycles of the subscription. The invoice for each interval is generated a specified number of days (days_before_interval) before the start of the interval. You can configure the schedule to end on a certain date or after a specified number of advance invoices have been generated.

The start date of the first interval depends on the number of days remaining from current time till the next renewal of the subscription. If this is more than days_before_interval, the interval begins at the next renewal. On the other hand, if the number of days remaining before the next renewal is less than days_before_interval, the first interval begins at the renewal following the next.

Sample advance invoice schedule [ JSON ]

{ "id": "__test__KyVkmQSCX2vRK2t", "object": "advance_invoice_schedule", "schedule_type": "specific_dates", "specific_dates_schedule": { "date": 1518339706, "object": "specific_dates_schedule", "terms_to_charge": 2 } }
id
string, max chars=40
System-generated and immutable unique Id for the advance_invoice_schedule.
schedule_type
optional, enumerated string
The type of advance invoice or advance invoicing schedule.
Possible values are
fixed_intervalsThe advance charges occur at fixed intervals of time.specific_datesThe advance charges occur on specific dates. For each date, a fixed number of billing cycles is charged for. There can be up to 5 dates configured.
fixed_interval_schedule
Show attributes[+]
optional, fixed_interval_schedule
When the schedule_type is fixed_intervals, this object gives further details of the schedule.
Fixed interval schedule attributes
end_schedule_on
optional, enumerated string
Specifies when the schedule should end.
Possible values are
after_number_of_intervalsAdvance invoices are generated a specified number of timesspecific_dateEnd the advance invoicing schedule on a specific date.subscription_endAdvance invoices are generated for as long as the subscription is active.
number_of_occurrences
optional, integer, min=1
The number of advance invoices to generate. The schedule is created such that the total number of billing cycles in the schedule does not exceed the remaining_billing_cycles of the subscription. This parameter is applicable only when fixed_interval_schedule[end_schedule_on] = after_number_of_intervals
days_before_renewal
optional, integer, min=1
The number of days before each interval that advance invoices are generated.
end_date
optional, timestamp(UTC) in seconds
The date when the schedule should end. Advance invoices are not generated beyond this date. It must be at least 1 day before the start of the last billing cycle of the subscription and also within 5 years from the current date. This parameter is only applicable when fixed_interval_schedule[end_schedule_on] = specific_date.
created_at
timestamp(UTC) in seconds
The date when this advance invoicing schedule was created.
terms_to_charge
optional, integer, min=1
The number of billing cycles in one interval.
specific_dates_schedule
Show attributes[+]
optional, specific_dates_schedule
The advance charges occur on specific dates. For each date, a fixed number of billing cycles is charged for. There can be up to 5 dates configured.
Specific dates schedule attributes
terms_to_charge
optional, integer
The number of billing cycles to charge for, on the date specified. Applicable only when schedule_type is specific_dates.
date
optional, timestamp(UTC) in seconds
The unique id of the member of the advance_invoice_schedule array which corresponds to the specific_dates_schedule that you intend to modify. Only applicable when schedule_type is specific_dates.
created_at
timestamp(UTC) in seconds
The date when this advance invoicing schedule was created.