Estimates

'Estimates', as the name implies, can be used to find out the estimate for performing an operation as against performing the operation itself. Say, if you want to create a new subscription or update an existing one, you can deduce the details such as the amount the customer needs to be charged for this operation, the state the subscription would be in, etc. using the estimate API.

Note:These APIs when invoked don't perform actual operations. They just generate an estimate.

Sample estimate [ JSON ]

Generates an estimate for the 'create subscription' operation. This is similar to the Create Subscription API but no subscription will be created, only an estimate for this operation is created.

In the response,

• estimate.subscription_estimate has the subscription details like the status of the subscription (in_trial, active, etc.), next billing date, and so on.
• estimate.invoice_estimate has details of the invoice that will be generated immediately. This will not be present if no immediate invoice is generated for this operation.
• estimate.next_invoice_estimate has details of the invoice that will be generated on the next billing date of this subscription. This will be present only if no immediate invoice is generated during this operation and this subscription has next billing.
  

  If the subscription is created in trial/future states, estimate.invoice_estimate will not be present as no immediate invoice would be generated. However, estimate.next_invoice_estimate will be returned which is a preview of the invoice that would be generated at a later date when the subscription becomes 'active'.

• estimate.unbilled_charge_estimates has details of the unbilled charges. This is returned only if invoice_immediately is set as true. But this is not applicable for the ‘Subscription renewal estimate’ operation.

Note: If you have configured EU VAT or Customized taxes, you need to specify the applicable parameters for calculating taxes - billing_address[], shipping_address[], customer[vat_number], customer[taxability] etc. Otherwise tax calculation will be ignored.

Related Tutorial

• Check out this tutorial for when and how to use create subscription estimate API

curl  https://{site}.chargebee.com/api/v2/estimates/create_subscription \
     -u {site_api_key}: \
     -d subscription[plan_id]="basic" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

curl  https://{site}.chargebee.com/api/v2/estimates/create_subscription \
     -u {site_api_key}: \
     -d subscription[plan_id]="basic" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

Sample Response [ JSON ]

URL Format POST

curl  https://{site}.chargebee.com/api/v2/customers/4gkYnd21ouvW/create_subscription_estimate \
     -G  \
     -u {site_api_key}: \
     --data-urlencode subscription[plan_id]="basic"

curl  https://{site}.chargebee.com/api/v2/customers/4gkYnd21ouvW/create_subscription_estimate \
     -G  \
     -u {site_api_key}: \
     --data-urlencode subscription[plan_id]="basic"

Sample Response [ JSON ]

URL Format GET

Generates an estimate for the 'update subscription' operation. The input will be similar to the Update Subscription API but subscription will not be updated, only an estimate will be created.

In the response,

• estimate.subscription_estimate has the subscription details like the status of the subscription (in_trial, active, etc.), next billing date, and so on.
• estimate.invoice_estimate has details of the invoice that will be generated immediately. This will not be present if no immediate invoice is generated for this operation. This will happen when
  • end_of_term parameter is true
  • prorate parameter is false
  • No recurring items (plan and addons) are changed . E.g. only a coupon is applied or billing_cycles is updated.
  • For certain types of changes - like plan/addon quantity downgrades - only Credit Notes will be created and no invoice gets generated.
• estimate.next_invoice_estimate has details of the invoice that will be generated during the next billing date of this subscription. This will be present only if no immediate invoice is generated during this operation (scenarios mentioned above) and this subscription has next billing.
  

  The generated invoice_estimate/next_invoice_estimate will include all the balances - Promotional Credits, Refundable Credits, and Excess Payments - if any. If you don’t want these balances to be included you can specify 'false' for the parameter use_existing_balances.

• estimate.credit_note_estimates[] has details of the credit-notes that will get generated during this operation. This list will be empty if no credit-note gets generated during this operation.
• estimate.unbilled_charge_estimates has details of the unbilled charges. This is returned only if invoice_immediately is set as true. But this is not applicable for the ‘Subscription renewal estimate’ operation.

Note: If you have configured EU VAT or Customized taxes, you need to specify the applicable parameters for calculating taxes - billing_address[], shipping_address[], customer[vat_number], customer[taxability] etc. Otherwise tax calculation will be ignored.

curl  https://{site}.chargebee.com/api/v2/estimates/update_subscription \
     -u {site_api_key}: \
     -d subscription[id]="5cDfREwp3I5lJ" \
     -d subscription[plan_id]="basic" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

curl  https://{site}.chargebee.com/api/v2/estimates/update_subscription \
     -u {site_api_key}: \
     -d subscription[id]="5cDfREwp3I5lJ" \
     -d subscription[plan_id]="basic" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

Sample Response [ JSON ]

URL Format POST

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/recurring_subscription_estimate \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/recurring_subscription_estimate \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format GET

This returns an estimate of the amount that will be charged when the subscription is billed next. The estimate is calculated based on the current recurring items of the subscription - plan, addons, and coupons.

In the response,

• estimate.subscription_estimate has the current subscription details like its status, next billing date, and so on.
• estimate.invoice_estimate has details of the invoice that will be generated at the next billing date.

  The generated invoice estimate will include all the balances - Promotional Credits, Refundable Credits, and Excess Payments - if any. If you don’t want these balances to be included you can specify 'false' for the parameter use_existing_balances.

  To exclude the delayed charges from the invoice estimate, specify 'false' for the parameter include_delayed_charges.

Note:

• This API will not generate a renewal invoice if an advance invoice is already present for the subscription.
• For 'Non Renewing' subscriptions, only the delayed charges will be included in the invoice estimate.
• This API is not supported for 'Cancelled' subscriptions.

curl  https://{site}.chargebee.com/api/v2/subscriptions/5cDfREwp3I5lJ/renewal_estimate \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/subscriptions/5cDfREwp3I5lJ/renewal_estimate \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format GET