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.
• If you have configured Avalara, Chargebee will retrieve tax amount from Avalara to be displayed in the estimate invoice, this may increase your Avalara request count.

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 false. But this is not applicable for the ‘Subscription renewal estimate’ operation.

Tip
Set the customer[taxability] attribute as true and provide any other necessary parameters to compute taxes. Otherwise tax is exempted for the estimate.

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]="no_trial" \
     -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]="no_trial" \
     -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/customers/__test__KyVnHhSBWl2XD2aV/create_subscription_estimate \
     -G  \
     -u {site_api_key}:\

curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl2XD2aV/create_subscription_estimate \
     -G  \
     -u {site_api_key}:\

curl  https://{site}.chargebee.com/api/v2/estimates/update_subscription \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWl3M42aj" \
     -d subscription[plan_id]="plan1" \
     -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]="__test__KyVnHhSBWl3M42aj" \
     -d subscription[plan_id]="plan1" \
     -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/subscriptions/__test__KyVnHhSBWkzpS2Zo/renewal_estimate \
     -u {site_api_key}:

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

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkjcSAl6gBw1/advance_invoice_estimate \
     -u {site_api_key}:\
     -d invoice_immediately="false" \
     -d terms_to_charge=3

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkjcSAl6gBw1/advance_invoice_estimate \
     -u {site_api_key}:\
     -d invoice_immediately="false" \
     -d terms_to_charge=3

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnOuSHufvfo16/regenerate_invoice_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d invoice_immediately="true"

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnOuSHufvfo16/regenerate_invoice_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d invoice_immediately="true"

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnOuSHufpzqv/regenerate_invoice_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d invoice_immediately="false" \
     -d date_from=1518344700 \
     -d date_to=1519381500 \
     -d prorate="true"

{"estimate": {
    "created_at": 1517480722,
    "invoice_estimate": {
        "amount_due": 895,
        "amount_paid": 0,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnOuSHufvfo16",
        "date": 1517480722,
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVnOuSHufvfo16",
                "date_from": 1517480722,
                "date_to": 1519899922,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnOuSHufvn81H",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnOuSHufvfo16",
                "tax_amount": 0,
                "unit_amount": 895
            },
            {..}
        ],
        "object": "invoice_estimate",
        "price_type": "tax_exclusive",
        "recurring": true,
        "round_off_amount": 0,
        "sub_total": 895,
        "taxes": [],
        "total": 895
    },
    "object": "estimate",
    "subscription_estimate": {
        "currency_code": "USD",
        "id": "__test__KyVnOuSHufvfo16",
        "next_billing_at": 1519899922,
        "object": "subscription_estimate",
        "status": "active"
    }
}}

{"estimate": {
    "created_at": 1517480701,
    "object": "estimate",
    "subscription_estimate": {
        "currency_code": "USD",
        "id": "__test__KyVnOuSHufpzqv",
        "next_billing_at": 1519899900,
        "object": "subscription_estimate",
        "status": "active"
    },
    "unbilled_charge_estimates": [
        {
            "amount": 384,
            "currency_code": "USD",
            "customer_id": "__test__KyVnOuSHufpzqv",
            "date_from": 1518344700,
            "date_to": 1519381500,
            "deleted": false,
            "description": "No Trial - Prorated Charges",
            "discount_amount": 0,
            "entity_id": "no_trial",
            "entity_type": "plan",
            "id": "li___test__KyVnOuSHufqEa15",
            "is_voided": false,
            "object": "unbilled_charge",
            "pricing_model": "per_unit",
            "quantity": 1,
            "subscription_id": "__test__KyVnOuSHufpzqv",
            "unit_amount": 384
        },
        {..}
    ]
}}

curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl2pw2aa/upcoming_invoices_estimate \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWl2pw2aa/upcoming_invoices_estimate \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkzRq2Zh/change_term_end_estimate \
     -u {site_api_key}:\
     -d term_ends_at=1566697500

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkzRq2Zh/change_term_end_estimate \
     -u {site_api_key}:\
     -d term_ends_at=1566697500

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkz4Y2Za/cancel_subscription_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d end_of_term="true"

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkz4Y2Za/cancel_subscription_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d end_of_term="true"

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWl1SO2aC/pause_subscription_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d pause_option="specific_date" \
     -d subscription[pause_date]=1566698400

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWl1SO2aC/pause_subscription_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d pause_option="specific_date" \
     -d subscription[pause_date]=1566698400

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWl1p52aJ/resume_subscription_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d resume_option="immediately"

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWl1p52aJ/resume_subscription_estimate \
     -X POST  \
     -u {site_api_key}:\
     -d resume_option="immediately"

curl  https://{site}.chargebee.com/api/v2/estimates/gift_subscription \
     -u {site_api_key}:\
     -d subscription[plan_id]="GiftPlan$100" \
     -d gifter[customer_id]="gifter" \
     -d gifter[signature]="Sam" \
     -d gift_receiver[customer_id]="receiver" \
     -d gift_receiver[first_name]="James" \
     -d gift_receiver[last_name]="William" \
     -d gift_receiver[email]="james@user.com"

curl  https://{site}.chargebee.com/api/v2/estimates/gift_subscription \
     -u {site_api_key}:\
     -d subscription[plan_id]="GiftPlan$100" \
     -d gifter[customer_id]="gifter" \
     -d gifter[signature]="Sam" \
     -d gift_receiver[customer_id]="receiver" \
     -d gift_receiver[first_name]="James" \
     -d gift_receiver[last_name]="William" \
     -d gift_receiver[email]="james@user.com"

curl  https://{site}.chargebee.com/api/v2/estimates/create_invoice \
     -u {site_api_key}:\
     -d invoice[customer_id]="__test__KyVnHhSBWl0D02Zw" \
     -d charges[amount][0]=1000 \
     -d charges[description][0]="Adhoc charge"

curl  https://{site}.chargebee.com/api/v2/estimates/create_invoice \
     -u {site_api_key}:\
     -d invoice[customer_id]="__test__KyVnHhSBWl0D02Zw" \
     -d charges[amount][0]=1000 \
     -d charges[description][0]="Adhoc charge"