Purchases

The purchase resource represents a collection of item prices bought together. A purchase can contain one or more of the following:

subscriptions (a subscription resource consists of item prices such that at least one of the item prices belongs to an item of type plan.)
group of one-time charges (aka charge item prices)

Prerequisite

Purchases must be enabled explicitly for the site. If not already enabled, contact Chargebee Support. Purchases 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 created as part of this purchase. These IDs remain even when the associated subscriptions have been deleted.

invoice_ids

optional, list of string
The unique identifier of the invoice(s) created immediately as part of this purchase.

Creates a purchase resource. A purchase can contain one or more of the following:

subscriptions (a subscription resource consists of item prices such that at least one of the item prices belongs to an item of type plan.)
group of one-time charges (aka charge item prices)

When you call this API, the invoices for the subscription(s) and one-time charge(s) are created immediately and not left unbilled.

Note

Providing shipping_addresses[] is required when the Orders feature has been enabled.

Specifying `purchase_item` groups

When creating a purchase, you must specify the group or index to which each item price belongs. You can do this by setting the purchase_items[index] for each item price. Item prices with the same purchase_items[index] belong to the same group.

The grouping of item prices allows you to specify the discounts[] applicable for each group and indicate which item prices should be added to any subscriptions you want to create. Groups can be one of two types:

Subscription groups
One-time charge groups

The following subsections describe the types of groups in detail.

Note

You can specify up to 10 groups,

with a recommended subscription group of 5. To increase this limit to a maximum of 8, contact Chargebee Support.
with a maximum of 10 one-time charge groups by default.

The total limit for group items for a single purchase is 60.

Subscription groups

To create a subscription, specify a subscription group. A subscription group is a group of item prices that contains exactly one item price of type plan. To create multiple subscriptions, provide multiple subscription groups.

Note

A subscription group can have up to 20 non-plan item prices. To increase this limit to a maximum of 60, contact Chargebee Support.

Custom Fields

Purchase API supports custom fields of Subscriptions, use the following format to specify custom fields in Purchase API: subscription_info[custom_field].

One-time charge groups

A one-time charge group is a group of charge item prices (i.e. item prices belonging to items of type charge). Charge item prices can be added to subscription groups as well. The charges within and across each one-time group must be unique.

Note

A one-time charge group can have up to 20 item prices. To increase this limit to a maximum of 60, contact Chargebee Support.
A charge item price can only be added to a single one-time charge group. However, it can be part of multiple subscription groups.

Applying discounts

Discounts, both manual discounts and coupons, can be applied to groups by specifying the discounts[] array. The following table describes the method of application based on whether discounts[index][i] is provided:

	`discounts[index][i]` is provided	`discounts[index][i]` is not provided
Coupons	The coupon is applied exclusively to the invoice for group `i`. The coupon is applied exclusively to the invoice created immediately upon invoking this API. If group `i` is a subscription group, then the coupon is applied to invoices for subscription renewals based on coupon attributes such as `duration_type` and `max_redemptions`.	The coupon is applied to all the invoices immediately generated upon invoking this API. The coupon is not applied to subsequent invoices, such as those generated upon subscription renewal.
Manual discounts	The manual discount is applied exclusively to the invoice for group `i`. The manual discount is applied exclusively to the invoice created immediately upon invoking this API. The manual discount is not applied to subsequent invoices, such as those generated upon subscription renewal.	The manual discount is applied to all the invoices immediately generated upon invoking this API. The manual discount is not applied to subsequent invoices, such as those generated upon subscription renewal.

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
The index or identifier of the group to which the item price belongs. The item prices assigned the same index belong to the same group.

purchase_items[item_price_id][0..n]

required, string, max chars=100
The unique identifier of the item price to be added to the group.

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. You can provide this value whether multi-decimal pricing is enabled or disabled.

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. By default multi-decimal pricing is enabled for purchase API, it is recommended to use the purchase_items[quantity_in_decimal][0..n] for providing quantity-based item prices when multi-decimal pricing is enabled. When multi-decimal pricing is disabled provide the value in purchase_items[quantity][0..n].

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
The index or identifier of the group 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. This parameter is mandatory when providing shipping information.

shipping_addresses[last_name][0..n]

optional, string, max chars=150
The last name of the contact. This parameter is mandatory when providing shipping information.

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. This parameter is mandatory when providing shipping information.

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. This parameter is mandatory when providing shipping information.

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. This parameter is mandatory when providing shipping information.

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. This parameter is mandatory when providing shipping information.

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
The index or identifier of the group 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.

See also:

Applying discounts

discounts[coupon_id][0..n]

optional, string, max chars=100

The unique ID of a coupon to be applied to the group. Alternatively, you may provide a coupon code. Applicable only for coupons.

See also:

Applying discounts

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

The percentage of the discount. Applicable only for manual discounts. For any given array index i, you must either provide discounts[percentage][i] or discounts[amount][i] and never both.

See also:

Applying discounts

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. Applicable only for manual discounts.

For any given array index i, you must either provide discounts[percentage][i] or discounts[amount][i] and never both.

See also:

Applying discounts

discounts[included_in_mrr][0..n]

optional, boolean

For manual discounts, 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.

See also:

Applying discounts

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
The index or identifier of the group to which this subscription information belongs. This must be a value from the purchase_items[index] array and the group must be a subscription group.

subscription_info[subscription_id][0..n]

optional, string, max chars=50
When specifying a subscription group, this is the unique identifier of the subscription to be created. This value must be unique for each subscription group.

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.

subscription_info[meta_data][0..n]

optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.

purchase

always returned
Resource object representing purchase

Returns an estimate for creating a purchase resource. The operation works exactly like Create a purchase, except that only an estimate resource is returned without an actual purchase resource being created.

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.

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]

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.

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]

required, integer, min=0
The index or identifier of the group to which the item price belongs. The item prices assigned the same index belong to the same group.

purchase_items[item_price_id][0..n]

required, string, max chars=100
The unique identifier of the item price to be added to the group.

purchase_items[quantity][0..n]

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]

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
The index or identifier of the group 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. This parameter is mandatory when providing shipping information.

shipping_addresses[last_name][0..n]

optional, string, max chars=150
The last name of the contact. This parameter is mandatory when providing shipping information.

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. This parameter is mandatory when providing shipping information.

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. This parameter is mandatory when providing shipping information.

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. This parameter is mandatory when providing shipping information.

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
The index or identifier of the group to which this discount or coupon information belongs.

See also:

Applying discounts

discounts[coupon_id][0..n]

optional, string, max chars=100

The unique ID of a coupon to be applied to the group. Alternatively, you may provide a coupon code. Applicable only for coupons.

See also:

Applying discounts

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

The percentage of the discount. Applicable only for manual discounts. For any given array index i, you must either provide discounts[percentage][i] or discounts[amount][i] and never both.

See also:

Applying discounts

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. Applicable only for manual discounts.

For any given array index i, you must either provide discounts[percentage][i] or discounts[amount][i] and never both.

See also:

Applying discounts

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.

See also:

Applying discounts

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]

subscription_info[subscription_id][0..n]

optional, string, max chars=50
When specifying a subscription group, this is the unique identifier of the subscription to be created. This value must be unique for each subscription group.

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¶

Specifying `purchase_item` groups

Subscription groups

Custom Fields

One-time charge groups

Applying discounts

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Estimates for purchase¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Purchases

Sample purchase [ JSON ]

API Index URL GET

Purchase attributes

Create a purchase¶

Specifying purchase_item groups

Subscription groups

Custom Fields

One-time charge groups

Applying discounts

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Estimates for purchase¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Specifying `purchase_item` groups