POST /subscriptions/{subscription-id}/charge_future_renewals

Creates a single advance invoice or an advance invoicing schedule for a subscription.

Use this operation to bill future renewals in advance, enabling customers to prepay for upcoming billing cycles.

Prerequisites & Constraints

The Advance Invoicing feature must be enabled on the site.
The subscription status must be active.
The subscription must not be scheduled for cancellation or pause within the terms being invoiced.
The subscription must have at least one item price belonging to a non-metered item.
The Multi-Frequency Billing feature must be disabled for the site.
The subscription must not be a gift subscription. You can check this by listing all gifts setting the filter parameter gift_receiver[customer_id][is] to the customer_id of the subscription and checking if one of the returned objects has gift_receiver.subscription_id matching the id of the subscription.
For subscriptions with ramps, the following constraints apply:
- The subscription must not have more than 12 scheduled ramps in the invoicing period specified by this API.
- For the invoicing period specified by this API, the subscription must not have any ramps scheduled for the middle of the subscription term.
The subscription must not be in its final contract term. i.e. the subscription must not have contract_term.action_at_term_end set to cancel.
The subscription must not have addons in trial.

Impacts

Subscription

The subscription next_billing_at is updated to reflect the end of the last term being invoiced. If all remaining billing cycles are invoiced, next_billing_at is set to null.
The subscription's remaining_billing_cycles is reduced by the number of terms charged.

Invoice

When schedule_type is immediate and invoice_immediately = true:
- a single advance invoice is created covering the specified number of future billing cycles.
- the invoice includes line items for all non-metered items, applicable coupons, taxes, and credits.
- any changes scheduled in the current term or at the end of the current term for the subscription are automatically taken into account while generating the advance invoice.
- if auto_collection is on for the subscription, the payment for the invoice is collected immediately using the payment source associated with the subscription.

Unbilled Charges

When schedule_type is immediate and invoice_immediately is false: The charges are added to unbilled_charges for the subscription and invoiced on the next renewal.

Advance Invoice Schedule

When schedule_type is specific_dates or fixed_intervals:
- an advance invoice schedule is created. The schedule defines when advance invoices will be generated in the future.
- any changes scheduled for the subscription are automatically taken into account while generating the advance invoice.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`subscription-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`fixed_interval_schedule`	Object	No	Parameters for fixed_interval_schedule. Required if `schedule_type` is `fixed_intervals`. Constraint There must be exactly one element in the `fixed_interval_schedule` array.
`fixed_interval_schedule.end_date`	Integer	No	The date when the advance invoicing schedule ends. Advance invoices are not generated beyond this date. Constraints `fixed_interval_schedule[end_schedule_on]` must be set to `specific_date`. Must be a future date. Must be at least 1 day before the start of the last billing cycle of the subscription. Must be within 5 years from the current date.
`fixed_interval_schedule.days_before_renewal`	Integer	No	The number of days before each interval that advance invoices are generated. Constraints For weekly billing periods: Must be less than or equal to `5` days. For monthly billing periods: Must be less than or equal to `25` days for 1-month periods. For yearly billing periods: Must be less than or equal to `363` days. For daily billing periods: `days_before_renewal` should not be provided.
`fixed_interval_schedule.number_of_occurrences`	Integer	No	The number of advance invoices to generate. Required if `fixed_interval_schedule[end_schedule_on]` is set to `after_number_of_intervals`. Impact 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.
`fixed_interval_schedule.end_schedule_on`	String	No	Specifies when the advance invoicing schedule ends. * after_number_of_intervals - Advance invoices are generated a specified number of times. Constraint You must provide `fixed_interval_schedule[number_of_occurrences]`. * subscription_end - Advance invoices are generated for as long as the subscription is active. * specific_date - The advance invoicing schedule ends on a specific date. Constraint You must provide `fixed_interval_schedule[end_date]`. Valid values: `"after_number_of_intervals"` `"subscription_end"` `"specific_date"`
`invoice_immediately`	Boolean	No	Whether the charge should be invoiced immediately or added to `unbilled_charges`. Prerequisite If `invoice_immediately` is `true` and `auto_collection` is `on` for the subscription, there must be a valid and active online `payment_source` associated with the subscription or the customer. Constraints The `schedule_type` must be `immediate`. Default value `true`
`specific_dates_schedule`	Object	No	Parameters for specific_dates_schedule. Required if `schedule_type` is `specific_dates`. Constraints The total number of schedules on the subscription (existing and new ones scheduled through this API) must not exceed 5.
`specific_dates_schedule.terms_to_charge[]`	Array	No	The number of billing cycles to charge for on the specified date. Constraints The `schedule_type` must be `specific_dates`. Must be greater than 0. Must not exceed the maximum terms allowed for advance invoicing (configured in site settings). The total number of billing cycles across all schedules must not exceed the `remaining_billing_cycles` of the subscription. Default value `1`
`specific_dates_schedule.date[]`	Array	No	The date on which the advance invoice should be generated. This is the scheduled date for generating the invoice for the specified number of billing cycles. Constraints The `schedule_type` must be `specific_dates`. Must be before the start of the billing period(s) that will be invoiced. Must be a future date within 5 years from the current date.
`schedule_type`	String	No	The type of advance invoice or advance invoicing schedule. Default value `immediate` * immediate - Bill immediately for the number of billing cycles specified by `terms_to_charge`. Prerequisite There must not be an existing advance invoice or an advance invoice schedule for the subscription. * specific_dates - Invoice on specific dates. Prerequisite There should not be an existing advance invoice schedule of `schedule_type` = `fixed_intervals` for the subscription. The total number of advance invoice schedules (existing and new ones scheduled through this API) of `schedule_type` = `specific_dates` must not exceed 5. Constraints When this option is selected, you must provide `specific_dates_schedule[date]`. * fixed_intervals - Invoice at fixed intervals of time. Prerequisite There should not be any existing advance invoice schedule for the subscription. Constraints When this option is selected, you must provide the following parameters: `terms_to_charge` `fixed_interval_schedule[days_before_renewal]` `fixed_interval_schedule[end_schedule_on]` Valid values: `"fixed_intervals"` `"immediate"` `"specific_dates"`
`terms_to_charge`	Integer	No	The number of billing cycles to charge, depending on the `schedule_type`: For `schedule_type = immediate`: The number of future billing cycles to be invoiced in advance. The invoicing is done for the `remaining_billing_cycles` of the subscription if that is less than `terms_to_charge`. For `schedule_type = fixed_intervals`: The number of future billing cycles in one interval. 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. Constraints Must be greater than 0. Must not exceed the maximum terms allowed for advance invoicing (configured in site settings). The value must not exceed the `remaining_billing_cycles` of the subscription. Default value `1` Default value: 1

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.