Purchases

The purchase resource represents a collection of subscriptions bought together. Since a subscription always has exactly one plan-item price, a purchase enables your customer to subscribe to multiple plans. This is particularly beneficial for the E-commerce domain where a customer can subscribe to plans for multiple items.

Prerequisite

Purchases must be enabled explicitly for the site. If not already enabled, contact Chargebee Support. Puchases require the following features to work so they’re automatically enabled along with them:

Note

Once created, Chargebee never modifies a purchase resource; it cannot be modified via API either.

Sample purchase [ JSON ]

{
    "created_at": 1651662622,
    "customer_id": "__test__rHsiT4rY1zmz",
    "id": "__test__rHsiT4rY2hC1A",
    "invoice_ids": [
        "__demo_inv__1",
        "__demo_inv__2"
    ],
    "object": "purchase",
    "subscription_ids": [
        "__test__rHsiT4rY2Lr12",
        "__test__rHsiT4rY2R615"
    ]
}

API Index URL GET

https://{site}.chargebee.com/api/v2/purchases

id

optional, string, max chars=100
The unique identifier of the purchase resource. This is always autogenerated.

customer_id

string, max chars=50
The unique identifier of the customer that made this purchase.

created_at

optional, timestamp(UTC) in seconds
The time at which this purchase was created.

modified_at

optional, timestamp(UTC) in seconds
The time at which the purchase was modified.

subscription_ids

optional, list of string
The unique identifiers of the subscriptions that are bundled as part of this purchase. Since the purchase resource is never modified, these IDs remain even when the associated subscriptions have been deleted.

invoice_ids

optional, list of string
The unique identifier of the invoice that is created immediately as part of this purchase. This array always has just one element.

Creates a purchase resource with associated subscriptions.

The subscriptions are created for this purchase with invoice_immediately set as true. In other words, charges are never left unbilled when calling this API and a single consolidated invoice is created immediately for all the subscriptions. Subsequently, if the criteria for consolidation are not met during subscription renewals, separate invoices are generated. For example, if Consolidated Invoicing is disabled after a purchase is made, subsequent renewals generate separate invoices.

Prerequisite

Limitations

No more than five subscriptions can be part of a single purchase.
For each subscription, there can be up to 3 non-mandatory addons or charges. For example, if there are 5 mandatory addons in one of the subscriptions, you can still add up to 3 more item prices to the subscription that are either addons or charges. In other words, you can add say, 1 addon and 2 charges, or 3 charges to that subscription.
You must contact Chargebee Support if you want to add more than 3 addons or charges, the maximum amount you can add is 10.

Sample Request

curl  https://{site}.chargebee.com/api/v2/purchases \
     -X POST  \
     -u {site_api_key}:\
     -d customer_id="__test__XpbG9acT88TIfH3T" \
     -d purchase_items[index][0]=1 \
     -d purchase_items[item_price_id][0]="basic-USD" \
     -d purchase_items[quantity][0]=10 \
     -d purchase_items[index][1]=2 \
     -d purchase_items[item_price_id][1]="basic-USD-yearly" \
     -d purchase_items[quantity][1]=5

copy

curl  https://{site}.chargebee.com/api/v2/purchases \
     -X POST  \
     -u {site_api_key}:\
     -d customer_id="__test__XpbG9acT88TIfH3T" \
     -d purchase_items[index][0]=1 \
     -d purchase_items[item_price_id][0]="basic-USD" \
     -d purchase_items[quantity][0]=10 \
     -d purchase_items[index][1]=2 \
     -d purchase_items[item_price_id][1]="basic-USD-yearly" \
     -d purchase_items[quantity][1]=5

curl  https://{site}.chargebee.com/api/v2/purchases \
     -X POST  \
     -u {site_api_key}:\
     -d customer_id="__test__XpbG9acT88TJ8h43" \
     -d purchase_items[index][0]=1 \
     -d purchase_items[item_price_id][0]="basic-USD" \
     -d purchase_items[quantity][0]=5 \
     -d purchase_items[index][1]=1 \
     -d purchase_items[item_price_id][1]="day-pass-USD" \
     -d purchase_items[index][2]=2 \
     -d purchase_items[item_price_id][2]="basic-USD-yearly" \
     -d purchase_items[quantity][2]=5 \
     -d purchase_items[index][3]=2 \
     -d purchase_items[item_price_id][3]="day-pass-USD"

curl  https://{site}.chargebee.com/api/v2/purchases \
     -X POST  \
     -u {site_api_key}:\
     -d customer_id="__test__XpbG9acT88TIuk3m" \
     -d purchase_items[index][0]=1 \
     -d purchase_items[item_price_id][0]="basic-USD" \
     -d purchase_items[quantity][0]=10 \
     -d purchase_items[index][1]=2 \
     -d purchase_items[item_price_id][1]="basic-USD-yearly" \
     -d purchase_items[quantity][1]=5 \
     -d subscription_info[index][0]=1 \
     -d subscription_info[subscription_id][0]="sub-1" \
     -d subscription_info[index][1]=2 \
     -d subscription_info[subscription_id][1]="sub-2"

Sample Response [ JSON ]

{"purchase": {
    "created_at": 1651662622,
    "customer_id": "__test__rHsiT4rY1zmz",
    "id": "__test__rHsiT4rY2hC1A",
    "invoice_ids": [
        "__demo_inv__1",
        {..}
    ],
    "object": "purchase",
    "subscription_ids": [
        "__test__rHsiT4rY2Lr12",
        {..}
    ]
}}

{"purchase": {
    "created_at": 1651662627,
    "customer_id": "__test__rHsiT4rY3cD1Z",
    "id": "__test__rHsiT4rY43w1k",
    "invoice_ids": [
        "__demo_inv__5",
        {..}
    ],
    "object": "purchase",
    "subscription_ids": [
        "sub_handle1",
        {..}
    ]
}}

{"purchase": {
    "created_at": 1651662625,
    "customer_id": "__test__rHsiT4rY2xO1I",
    "id": "__test__rHsiT4rY3Qg1R",
    "invoice_ids": [
        "__demo_inv__3",
        {..}
    ],
    "object": "purchase",
    "subscription_ids": [
        "sub1",
        {..}
    ]
}}

URL Format POST

https://{site}.chargebee.com/api/v2/purchases

customer_id

required, string, max chars=50
The unique identifier of the customer that made this purchase.

invoice_info

Parameters for invoice_info
pass parameters as invoice_info[<param name>]

invoice_info[po_number]

optional, string, max chars=100
The purchase order number for this purchase. This is reflected in all the subscriptions and invoices under this purchase.

invoice_info[notes]

optional, string, max chars=2000
A customer-facing note added to the PDF of the first invoice associated with this purchase. This is added to invoice.notes. Subsequent invoices do not have this note.

purchase_items

Parameters for purchase_items. Multiple purchase_items can be passed by specifying unique indices.
pass parameters as purchase_items[<param name>][<idx:0..n>]

purchase_items[index][0..n]

required, integer, min=0, max=4
The index number of the subscription to which the item price is added. Provide a unique number between 0 and 4 (inclusive) for each subscription that is to be created.

purchase_items[item_price_id][0..n]

required, string, max chars=100
The unique identifier of the item price to be added to the subscription. The subscription to which the item price is added is specified using index.

purchase_items[quantity][0..n]

optional, integer, default=1, min=1
The quantity of the item price. Applicable only when the pricing model of the item price is anything other than flat_fee.

purchase_items[unit_amount][0..n]

optional, in cents, min=0
The price or per unit price of the item. You may provide this only when price overriding is enabled for the site.

purchase_items[unit_amount_in_decimal][0..n]

optional, string, max chars=39
The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.

purchase_items[quantity_in_decimal][0..n]

optional, string, max chars=33
The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[index][0..n]

required, integer, min=0, max=4
The index number of the subscription to which this tier information belongs. This must be a value from the purchase_items[index] array.

item_tiers[item_price_id][0..n]

optional, string, max chars=100
The unique ID of the item price to which this tier information belongs. This must be a value from the purchase_items[item_price_id] array.

item_tiers[starting_unit][0..n]

optional, integer, min=1
The lowest value of quantity in this tier; this is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the very next lower tier.

item_tiers[ending_unit][0..n]

optional, integer
The highest value of quantity in this tier. For all other tiers,it must be equal to the starting_unit_in_decimal of the very next higher tier.

item_tiers[price][0..n]

optional, in cents, default=0, min=0
The per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the total price of the item. The currency units in which this value is expressed depends on the type of currency.

item_tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

item_tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

item_tiers[price_in_decimal][0..n]

optional, string, max chars=39
The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.

shipping_addresses

Parameters for shipping_addresses. Multiple shipping_addresses can be passed by specifying unique indices.
pass parameters as shipping_addresses[<param name>][<idx:0..n>]

shipping_addresses[first_name][0..n]

optional, string, max chars=150
The first name of the contact.

shipping_addresses[last_name][0..n]

optional, string, max chars=150
The last name of the contact.

shipping_addresses[email][0..n]

optional, string, max chars=70
The email address.

shipping_addresses[company][0..n]

optional, string, max chars=250
The company name.

shipping_addresses[phone][0..n]

optional, string, max chars=50
The phone number.

shipping_addresses[line1][0..n]

optional, string, max chars=150
Address line 1

shipping_addresses[line2][0..n]

optional, string, max chars=150
Address line 2

shipping_addresses[line3][0..n]

optional, string, max chars=150
Address line 3

shipping_addresses[city][0..n]

optional, string, max chars=50
The name of the city.

shipping_addresses[state][0..n]

optional, string, max chars=50
The state/province name.

shipping_addresses[state_code][0..n]

optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).

shipping_addresses[country][0..n]

optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

shipping_addresses[zip][0..n]

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

shipping_addresses[validation_status][0..n]

optional, enumerated string, default=not_validated
The address verification status.

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[index][0..n]

optional, integer, min=0, max=4
The index number of the subscription to which this discount or coupon information belongs.

This must be a value from the purchase_items[index] array. When not provided, the coupon is applied to the first invoice only; irrespective of the values set for coupon.duration_typeor coupon.max_redemptions.

Note:

Manual discounts are applied only to the first invoice for the purchase.

discounts[coupon_id][0..n]

optional, string, max chars=100

The unique ID of a coupon to be applied to the subscription. Alternatively, you may provide a coupon code. The subscription is specified using discounts[index][i].

Note:

For a given array index i, when passing this parameter, no other parameter for discounts[] except discounts[index][i] should be passed. Those parameters are for applying manual discounts.
If discounts[index][i] is not provided, the coupon is applied to the first invoice only.

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

The percentage of the discount.

For any given array index i:

You must either provide discounts[percentage][i] or discounts[amount][i] and never both.
Never pass discounts[coupon_id][i] when passing this parameter.

Note:

Manual discounts are applied only to the first invoice for the purchase.

discounts[amount][0..n]

optional, in cents, min=0

The absolute value of the discount. The currency units in which this value is expressed depends on the type of currency.

For any given array index i:

You must either provide discounts[percentage][i] or discounts[amount][i] and never both.
Never pass discounts[coupon_id][i] when passing this parameter.

Note:

Manual discounts are applied only to the first invoice for the purchase.

discounts[included_in_mrr][0..n]

optional, boolean

Set this to false if this manual discount should be excluded from monthly recurring revenue (MRR) calculations for the site. The following prerequisites must be met to allow this parameter to be passed:

The feature must be enabled in Chargebee.
The site-level setting must be to include coupons in MRR calculations.

Do not pass this for any array index i when discounts[coupon_id][i] is passed.

Note:

Manual discounts are applied only to the first invoice for the purchase.

subscription_info

Parameters for subscription_info. Multiple subscription_info can be passed by specifying unique indices.
pass parameters as subscription_info[<param name>][<idx:0..n>]

subscription_info[index][0..n]

required, integer, min=0, max=4
The index number of the subscription to which this subscription information belongs. This must be a value from the purchase_items[index] array.

subscription_info[subscription_id][0..n]

optional, string, max chars=50
The unique identifier of the subscription to which the item price is added. Just like index, this must be provided as a unique value for each subscription.

subscription_info[billing_cycles][0..n]

optional, integer, min=0
The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan-item price is used.

purchase

always returned
Resource object representing purchase

Returns an estimate for a purchase.

The subscriptions are estimated for this purchase with invoice_immediately set as true. In other words, charges are never left unbilled when calling this API.

Prerequisite

Limitations

No more than five subscriptions can be part of a single purchase.
For each subscription, there can be up to 3 non-mandatory addons or charges. For example, if there are 5 mandatory addons in one of the subscriptions, you can still add up to 3 more item prices to the subscription that are either addons or charges. In other words, you can add say, 1 addon and 2 charges, or 3 charges to that subscription.
You must contact Chargebee Support if you want to add more than 3 addons or charges, the maximum amount you can add is 10.

Sample Request

curl  https://{site}.chargebee.com/api/v2/purchases/estimate \
     -u {site_api_key}:\
     -d purchase_items[index][0]=1 \
     -d purchase_items[item_price_id][0]="basic-USD" \
     -d purchase_items[quantity][0]=10 \
     -d purchase_items[index][1]=2 \
     -d purchase_items[item_price_id][1]="basic-USD-yearly" \
     -d purchase_items[quantity][1]=5

copy

curl  https://{site}.chargebee.com/api/v2/purchases/estimate \
     -u {site_api_key}:\
     -d purchase_items[index][0]=1 \
     -d purchase_items[item_price_id][0]="basic-USD" \
     -d purchase_items[quantity][0]=10 \
     -d purchase_items[index][1]=2 \
     -d purchase_items[item_price_id][1]="basic-USD-yearly" \
     -d purchase_items[quantity][1]=5

curl  https://{site}.chargebee.com/api/v2/purchases/estimate \
     -u {site_api_key}:\
     -d customer_id="__test__XpbG9acT88TIUT3H" \
     -d purchase_items[index][0]=1 \
     -d purchase_items[item_price_id][0]="basic-USD" \
     -d purchase_items[quantity][0]=5 \
     -d purchase_items[index][1]=1 \
     -d purchase_items[item_price_id][1]="day-pass-USD" \
     -d purchase_items[index][2]=2 \
     -d purchase_items[item_price_id][2]="basic-USD-yearly" \
     -d purchase_items[quantity][2]=5 \
     -d purchase_items[index][3]=2 \
     -d purchase_items[item_price_id][3]="day-pass-USD"

curl  https://{site}.chargebee.com/api/v2/purchases/estimate \
     -u {site_api_key}:\
     -d customer_id="__test__XpbG9acT88TII837" \
     -d purchase_items[index][0]=1 \
     -d purchase_items[item_price_id][0]="basic-USD" \
     -d purchase_items[quantity][0]=10 \
     -d purchase_items[index][1]=2 \
     -d purchase_items[item_price_id][1]="basic-USD-yearly" \
     -d purchase_items[quantity][1]=5

Sample Response [ JSON ]

{"estimate": {
    "created_at": 1651662607,
    "invoice_estimates": [
        {
            "amount_due": 15000,
            "amount_paid": 0,
            "credits_applied": 0,
            "currency_code": "USD",
            "customer_id": "__test__rHsiT4rXxy4U",
            "date": 1651662606,
            "line_item_discounts": [],
            "line_item_taxes": [],
            "line_item_tiers": [
                {
                    "ending_unit": 10,
                    "line_item_id": "li___test__rHsiT4rXyUya",
                    "object": "line_item_tier",
                    "quantity_used": 5,
                    "starting_unit": 1,
                    "unit_amount": 1000
                },
                {..}
            ],
            "line_items": [
                {
                    "amount": 10000,
                    "customer_id": "__test__rHsiT4rXxy4U",
                    "date_from": 1651662604,
                    "date_to": 1654341004,
                    "description": "basic USD",
                    "discount_amount": 0,
                    "entity_id": "basic-USD",
                    "entity_type": "plan_item_price",
                    "id": "li___test__rHsiT4rXyJmX",
                    "is_taxed": false,
                    "item_level_discount_amount": 0,
                    "object": "line_item",
                    "pricing_model": "per_unit",
                    "quantity": 10,
                    "subscription_id": "__test__rHsiT4rXxzvV",
                    "tax_amount": 0,
                    "unit_amount": 1000
                },
                {..}
            ],
            "object": "invoice_estimate",
            "price_type": "tax_exclusive",
            "recurring": true,
            "round_off_amount": 0,
            "sub_total": 15000,
            "taxes": [],
            "total": 15000
        },
        {..}
    ],
    "object": "estimate"
}}

{"estimate": {
    "created_at": 1651662619,
    "invoice_estimates": [
        {
            "amount_due": 16500,
            "amount_paid": 0,
            "credits_applied": 0,
            "currency_code": "USD",
            "customer_id": "__test__rHsiT4rY0iyo",
            "date": 1651662618,
            "line_item_discounts": [],
            "line_item_taxes": [],
            "line_item_tiers": [
                {
                    "ending_unit": 10,
                    "line_item_id": "li___test__rHsiT4rY1hQv",
                    "object": "line_item_tier",
                    "quantity_used": 5,
                    "starting_unit": 1,
                    "unit_amount": 1000
                },
                {..}
            ],
            "line_items": [
                {
                    "amount": 5000,
                    "customer_id": "__test__rHsiT4rY0iyo",
                    "date_from": 1651662618,
                    "date_to": 1654341018,
                    "description": "basic USD",
                    "discount_amount": 0,
                    "entity_id": "basic-USD",
                    "entity_type": "plan_item_price",
                    "id": "li___test__rHsiT4rY1dqs",
                    "is_taxed": false,
                    "item_level_discount_amount": 0,
                    "object": "line_item",
                    "pricing_model": "per_unit",
                    "quantity": 5,
                    "subscription_id": "sub_handle1",
                    "tax_amount": 0,
                    "unit_amount": 1000
                },
                {..}
            ],
            "object": "invoice_estimate",
            "price_type": "tax_exclusive",
            "recurring": true,
            "round_off_amount": 0,
            "sub_total": 16500,
            "taxes": [],
            "total": 16500
        },
        {..}
    ],
    "object": "estimate"
}}

{
    "estimate": {
        "created_at": 1654661087,
        "invoice_estimates": [
            {
                "amount_due": 15000,
                "amount_paid": 0,
                "credits_applied": 0,
                "currency_code": "USD",
                "customer_id": "__test__XpbG9acT88TII837",
                "date": 1654661087,
                "line_item_discounts": [],
                "line_item_taxes": [],
                "line_item_tiers": [
                    {
                        "ending_unit": 10,
                        "line_item_id": "li___test__XpbG9acT88TIRV3F",
                        "object": "line_item_tier",
                        "quantity_used": 5,
                        "starting_unit": 1,
                        "unit_amount": 1000
                    },
                    {..}
                ],
                "line_items": [
                    {
                        "amount": 10000,
                        "customer_id": "__test__XpbG9acT88TII837",
                        "date_from": 1654661087,
                        "date_to": 1657253087,
                        "description": "basic USD",
                        "discount_amount": 0,
                        "entity_id": "basic-USD",
                        "entity_type": "plan_item_price",
                        "id": "li___test__XpbG9acT88TIQp3C",
                        "is_taxed": false,
                        "item_level_discount_amount": 0,
                        "object": "line_item",
                        "pricing_model": "per_unit",
                        "quantity": 10,
                        "subscription_id": "__test__XpbG9acT88TIQ83A",
                        "tax_amount": 0,
                        "unit_amount": 1000
                    },
                    {..}
                ],
                "object": "invoice_estimate",
                "price_type": "tax_exclusive",
                "recurring": true,
                "round_off_amount": 0,
                "sub_total": 15000,
                "taxes": [],
                "total": 15000
            },
            {..}
        ],
        "object": "estimate"
    },
    "subscription_estimate": {
        "object": "subscription_estimate",
        "subscription_estimates": [
            {
                "currency_code": "USD",
                "id": "__test__XpbG9acT88TIQ83A",
                "next_billing_at": 1657253087,
                "object": "subscription_estimate",
                "status": "active"
            },
            {..}
        ]
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/purchases/estimate

client_profile_id

optional, string, max chars=50
Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.

customer_id

optional, string, max chars=50
The unique identifier of the customer that made this purchase.

invoice_info

Parameters for invoice_info
pass parameters as invoice_info[<param name>]

invoice_info[po_number]

optional, string, max chars=100
The purchase order number for this purchase. This is reflected in all the subscriptions and invoices under this purchase.

invoice_info[notes]

optional, string, max chars=2000
A customer-facing note added to the PDF of the first invoice associated with this purchase. This is added to invoice.notes. Subsequent invoices do not have this note.

customer

Parameters for customer
pass parameters as customer[<param name>]

customer[vat_number]

optional, string, max chars=20
VAT number of this customer. If not provided then taxes are not calculated for the estimate. Applicable only when taxes are configured for the EU or UK region. VAT validation is not done for this.

customer[vat_number_prefix]

optional, string, max chars=10
An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address country as XI (which is United Kingdom - Northern Ireland).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address country as XI. That’s the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.

customer[registered_for_gst]

optional, boolean
Confirms that a customer is registered under GST. If set to true then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.

customer[taxability]

optional, enumerated string, default=taxable
Specifies if the customer is liable for tax

Possible values are

taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt

Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.

customer[entity_code]

optional, enumerated string
The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration.

Possible values are

aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat

eCharitable or benevolent organizationfReligious organizationgResalehCommercial agricultural productioniIndustrial production/manufacturerjDirect pay permitkDirect maillOther or custommEducational organizationnLocal governmentpCommercial aquacultureqCommercial FisheryrNon-residentmed1US Medical Device Excise Tax with exempt sales taxmed2US Medical Device Excise Tax with taxable sales tax

Show all values[+]

customer[exempt_number]

optional, string, max chars=100
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's AvaTax for Sales integration.

customer[exemption_details]

optional, jsonarray
Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
To know more about what values you need to provide, refer to this Avalara’s API document.

customer[customer_type]

optional, enumerated string
Indicates the type of the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.

Possible values are

residentialWhen the purchase is made by a customer for home usebusinessWhen the purchase is made at a place of businesssenior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaksindustrialWhen the purchase is made by an industrial business

billing_address

Parameters for billing_address
pass parameters as billing_address[<param name>]

billing_address[line1]

optional, string, max chars=150
Address line 1

billing_address[line2]

optional, string, max chars=150
Address line 2

billing_address[line3]

optional, string, max chars=150
Address line 3

billing_address[city]

optional, string, max chars=50
The name of the city.

billing_address[state_code]

billing_address[zip]

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

billing_address[country]

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

billing_address[validation_status]

optional, enumerated string, default=not_validated
The address verification status.

Possible values are

purchase_items

Parameters for purchase_items. Multiple purchase_items can be passed by specifying unique indices.
pass parameters as purchase_items[<param name>][<idx:0..n>]

purchase_items[index][0..n]

purchase_items[item_price_id][0..n]

required, string, max chars=100
The unique identifier of the item price to be added to the subscription. The subscription to which the item price is added is specified using index.

purchase_items[quantity][0..n]

optional, integer, default=1, min=1
The quantity of the item price. Applicable only when the pricing model of the item price is anything other than flat_fee.

purchase_items[unit_amount][0..n]

optional, in cents, min=0
The price or per unit price of the item. You may provide this only when price overriding is enabled for the site.

purchase_items[unit_amount_in_decimal][0..n]

purchase_items[quantity_in_decimal][0..n]

optional, string, max chars=33
The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[index][0..n]

required, integer, min=0, max=4
The index number of the subscription to which this tier information belongs. This must be a value from the purchase_items[index] array.

item_tiers[item_price_id][0..n]

optional, string, max chars=100
The unique ID of the item price to which this tier information belongs. This must be a value from the purchase_items[item_price_id] array.

item_tiers[starting_unit][0..n]

optional, integer, min=1
The lowest value of quantity in this tier; this is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the very next lower tier.

item_tiers[ending_unit][0..n]

optional, integer
The highest value of quantity in this tier. For all other tiers,it must be equal to the starting_unit_in_decimal of the very next higher tier.

item_tiers[price][0..n]

item_tiers[starting_unit_in_decimal][0..n]

item_tiers[ending_unit_in_decimal][0..n]

item_tiers[price_in_decimal][0..n]

shipping_addresses

Parameters for shipping_addresses. Multiple shipping_addresses can be passed by specifying unique indices.
pass parameters as shipping_addresses[<param name>][<idx:0..n>]

shipping_addresses[first_name][0..n]

optional, string, max chars=150
The first name of the contact.

shipping_addresses[last_name][0..n]

optional, string, max chars=150
The last name of the contact.

shipping_addresses[email][0..n]

optional, string, max chars=70
The email address.

shipping_addresses[company][0..n]

optional, string, max chars=250
The company name.

shipping_addresses[phone][0..n]

optional, string, max chars=50
The phone number.

shipping_addresses[line1][0..n]

optional, string, max chars=150
Address line 1

shipping_addresses[line2][0..n]

optional, string, max chars=150
Address line 2

shipping_addresses[line3][0..n]

optional, string, max chars=150
Address line 3

shipping_addresses[city][0..n]

optional, string, max chars=50
The name of the city.

shipping_addresses[state][0..n]

optional, string, max chars=50
The state/province name.

shipping_addresses[state_code][0..n]

shipping_addresses[country][0..n]

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

shipping_addresses[zip][0..n]

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

shipping_addresses[validation_status][0..n]

optional, enumerated string, default=not_validated
The address verification status.

Possible values are

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[index][0..n]

optional, integer, min=0, max=4
The index number of the subscription to which this discount or coupon information belongs.

Note:

Manual discounts are applied only to the first invoice for the purchase.

discounts[coupon_id][0..n]

optional, string, max chars=100

The unique ID of a coupon to be applied to the subscription. Alternatively, you may provide a coupon code. The subscription is specified using discounts[index][i].

Note:

For a given array index i, when passing this parameter, no other parameter for discounts[] except discounts[index][i] should be passed. Those parameters are for applying manual discounts.
If discounts[index][i] is not provided, the coupon is applied to the first invoice only.

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

The percentage of the discount.

For any given array index i:

You must either provide discounts[percentage][i] or discounts[amount][i] and never both.
Never pass discounts[coupon_id][i] when passing this parameter.

Note:

Manual discounts are applied only to the first invoice for the purchase.

discounts[amount][0..n]

optional, in cents, min=0

The absolute value of the discount. The currency units in which this value is expressed depends on the type of currency.

For any given array index i:

You must either provide discounts[percentage][i] or discounts[amount][i] and never both.
Never pass discounts[coupon_id][i] when passing this parameter.

Note:

Manual discounts are applied only to the first invoice for the purchase.

discounts[included_in_mrr][0..n]

optional, boolean

The feature must be enabled in Chargebee.
The site-level setting must be to include coupons in MRR calculations.

Do not pass this for any array index i when discounts[coupon_id][i] is passed.

Note:

Manual discounts are applied only to the first invoice for the purchase.

subscription_info

Parameters for subscription_info. Multiple subscription_info can be passed by specifying unique indices.
pass parameters as subscription_info[<param name>][<idx:0..n>]

subscription_info[index][0..n]

required, integer, min=0, max=4
The index number of the subscription to which this subscription information belongs. This must be a value from the purchase_items[index] array.

subscription_info[subscription_id][0..n]

optional, string, max chars=50
The unique identifier of the subscription to which the item price is added. Just like index, this must be provided as a unique value for each subscription.

subscription_info[billing_cycles][0..n]

optional, integer, min=0
The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan-item price is used.

estimate

always returned
Resource object representing estimate

Sample purchase [ JSON ]

API Index URL GET

Purchase attributes

Create a purchase¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Estimates for purchase¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns