ChargebeeAPI
Using AI coding agents like Claude Code or Cursor? Try the official Chargebee Agent Skills to speed up your development.Try now

Charge Future Renewals

Idempotency Supported
Try in API Explorer

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.

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/subscriptions/{subscription-id}/charge_future_renewals

Input Parameters

terms_to_charge
optional, integer, default=1, min=1

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
invoice_immediately
optional, boolean

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
schedule_type
optional, enumerated string

The type of advance invoice or advance invoicing schedule.

Default value

  • immediate
Possible Enum Values
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]
fixed_interval_schedule
Parameters for fixed_interval_schedule
pass parameters as fixed_interval_schedule[<param name>]
specific_dates_schedule[0..n]
Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]

Returns

subscriptionSubscription object
Resource object representing subscription
customerCustomer object
Resource object representing customer
cardCard object
Resource object representing card
invoiceInvoice object
Resource object representing invoice
advance_invoice_schedulesoptional
Resource object representing advance_invoice_schedule