Introducing the Chargebee CLI
chargebee docs

How do I calculate the next billing amount using Chargebee API?

Problem statement

This article explains how to calculate the next billing amount for an existing subscription using the Chargebee API.

Solution

Use the Subscription renewal estimate API to get an estimate of the amount that will be charged on the subscription's next billing date.

The API response includes:

  • estimate.subscription_estimate: Subscription details, such as status and next billing date.
  • estimate.invoice_estimate: Invoice details for the next billing date.

Steps to calculate the next billing amount

  1. Ensure that you have your Chargebee site subdomain and API key.

  2. Use the following API endpoint:

    curl https://test-site.chargebee.com/api/v2/subscriptions/__subscription_id__/renewal_estimate 
    \ -u test_api_key:

  3. To customize the estimate, pass optional query parameters:

    • include_delayed_charges
    • use_existing_balances
    • ignore_scheduled_cancellation
    • ignore_scheduled_changes
    • exclude_tax_type

    Example:

    curl "https://test-site.chargebee.com/api/v2/subscriptions/__subscription_id__/renewal_estimate?include_delayed_charges=true&use_existing_balances=false&ignore_scheduled_changes=false&exclude_tax_type=none" 
    \ -u test_api_key:

  4. Review the following fields in the response:

    • estimate.invoice_estimate.total
    • estimate.invoice_estimate.amount_due
    • estimate.invoice_estimate.sub_total
    • estimate.invoice_estimate.line_items
    • estimate.subscription_estimate.next_billing_at

Additional information

  • This API is not supported for canceled subscriptions.
  • For non-renewing subscriptions, only delayed charges are included in the invoice estimate.
  • If an advance invoice already exists for the subscription, this API does not generate a renewal invoice estimate.
  • If consolidated invoicing is enabled, use the Upcoming Invoices estimate API for the customer to get the actual invoice estimate.