API Version
Product Catalog
Library

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 eap@chargebee.com. 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

Model Class

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.
id id
optional, string, max chars=100
The unique identifier of the purchase resource. This is always autogenerated.
customer_id customer_id
string, max chars=50
The unique identifier of the customer that made this purchase.
created_at created_at
optional, timestamp(UTC) in seconds
The time at which this purchase was created.
modified_at modified_at
optional, timestamp(UTC) in seconds
The time at which the purchase was modified.
subscription_ids 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 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 eap@chargebee.com.
  • 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 eap@chargebee.com.

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 eap@chargebee.com.
  • 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.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/purchases \
     -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 \
     -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 \
     -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" 
copy
Click to Copy

Sample Response [ JSON ]

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

URL Format POST

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

Method

customer_id[]
required, string, max chars=50
The unique identifier of the customer that made this purchase.
payment_source_id[]
optional, string, max chars=40
Payment source attached to this purchase. If present, the customer's payment sources won't be used to collect any payment for this purchase.
invoice_info[po_number]
optional, string, max chars=100
invoice_info[notes]
optional, string, max chars=2000
installment_info[config_id]
optional, string, max chars=40
installment_info[amount]
optional, in cents, min=0
purchase_items[index][0..n]
required, integer, min=0
purchase_items[item_price_id][0..n]
required, string, max chars=100
purchase_items[quantity][0..n]
optional, integer, default=1, min=1
purchase_items[unit_amount][0..n]
optional, in cents, min=0
purchase_items[unit_amount_in_decimal][0..n]
optional, string, max chars=39
purchase_items[quantity_in_decimal][0..n]
optional, string, max chars=33
item_tiers[index][0..n]
required, integer, min=0
item_tiers[item_price_id][0..n]
optional, string, max chars=100
item_tiers[starting_unit][0..n]
optional, integer, min=1
item_tiers[ending_unit][0..n]
optional, integer
item_tiers[price][0..n]
optional, in cents, default=0, min=0
item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[price_in_decimal][0..n]
optional, string, max chars=39
shipping_addresses[first_name][0..n]
optional, string, max chars=150
shipping_addresses[last_name][0..n]
optional, string, max chars=150
shipping_addresses[email][0..n]
optional, string, max chars=70
shipping_addresses[company][0..n]
optional, string, max chars=250
shipping_addresses[phone][0..n]
optional, string, max chars=50
shipping_addresses[line1][0..n]
optional, string, max chars=150
shipping_addresses[line2][0..n]
optional, string, max chars=150
shipping_addresses[line3][0..n]
optional, string, max chars=150
shipping_addresses[city][0..n]
optional, string, max chars=50
shipping_addresses[state][0..n]
optional, string, max chars=50
shipping_addresses[state_code][0..n]
optional, string, max chars=50
shipping_addresses[country][0..n]
optional, string, max chars=50
shipping_addresses[zip][0..n]
optional, string, max chars=20
shipping_addresses[validation_status][0..n]
optional, enumerated string, default=not_validated
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.
Show all values[+]
discounts[index][0..n]
optional, integer, min=0
discounts[coupon_id][0..n]
optional, string, max chars=100
discounts[percentage][0..n]
optional, double, min=0.01, max=100.0
discounts[amount][0..n]
optional, in cents, min=0
discounts[included_in_mrr][0..n]
optional, boolean
subscription_info[index][0..n]
required, integer, min=0
subscription_info[subscription_id][0..n]
optional, string, max chars=50
subscription_info[billing_cycles][0..n]
optional, integer, min=0
subscription_info[contract_term_billing_cycle_on_renewal][0..n]
optional, integer, min=1, max=100
subscription_info[meta_data][0..n]
optional, jsonobject
contract_terms[index][0..n]
required, integer, min=0
contract_terms[action_at_term_end][0..n]
optional, enumerated string, default=renew
Possible values are
renewevergreencancelrenew_once
Show all values[+]
contract_terms[cancellation_cutoff_period][0..n]
optional, integer
purchase purchase
always returned
Resource object representing purchase

Sample admin console URL

https://{site}.chargebee.com/admin-console/purchases/123x

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.

Notes

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 
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 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "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"
    }
}

URL Format POST

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

Method

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[vat_number]
optional, string, max chars=20
customer[vat_number_prefix]
optional, string, max chars=10
customer[registered_for_gst]
optional, boolean
customer[taxability]
optional, enumerated string, default=taxable
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.
Show all values[+]
customer[entity_code]
optional, enumerated string
Possible values are
aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat
Show all values[+]
customer[exempt_number]
optional, string, max chars=100
customer[exemption_details]
optional, jsonarray
customer[customer_type]
optional, enumerated string
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
Show all values[+]
billing_address[line1]
optional, string, max chars=150
billing_address[line2]
optional, string, max chars=150
billing_address[line3]
optional, string, max chars=150
billing_address[city]
optional, string, max chars=50
billing_address[state_code]
optional, string, max chars=50
billing_address[zip]
optional, string, max chars=20
billing_address[country]
optional, string, max chars=50
billing_address[validation_status]
optional, enumerated string, default=not_validated
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.
Show all values[+]
purchase_items[index][0..n]
required, integer, min=0
purchase_items[item_price_id][0..n]
required, string, max chars=100
purchase_items[quantity][0..n]
optional, integer, default=1, min=1
purchase_items[unit_amount][0..n]
optional, in cents, min=0
purchase_items[unit_amount_in_decimal][0..n]
optional, string, max chars=39
purchase_items[quantity_in_decimal][0..n]
optional, string, max chars=33
item_tiers[index][0..n]
required, integer, min=0
item_tiers[item_price_id][0..n]
optional, string, max chars=100
item_tiers[starting_unit][0..n]
optional, integer, min=1
item_tiers[ending_unit][0..n]
optional, integer
item_tiers[price][0..n]
optional, in cents, default=0, min=0
item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[price_in_decimal][0..n]
optional, string, max chars=39
shipping_addresses[first_name][0..n]
optional, string, max chars=150
shipping_addresses[last_name][0..n]
optional, string, max chars=150
shipping_addresses[email][0..n]
optional, string, max chars=70
shipping_addresses[company][0..n]
optional, string, max chars=250
shipping_addresses[phone][0..n]
optional, string, max chars=50
shipping_addresses[line1][0..n]
optional, string, max chars=150
shipping_addresses[line2][0..n]
optional, string, max chars=150
shipping_addresses[line3][0..n]
optional, string, max chars=150
shipping_addresses[city][0..n]
optional, string, max chars=50
shipping_addresses[state][0..n]
optional, string, max chars=50
shipping_addresses[state_code][0..n]
optional, string, max chars=50
shipping_addresses[country][0..n]
optional, string, max chars=50
shipping_addresses[zip][0..n]
optional, string, max chars=20
shipping_addresses[validation_status][0..n]
optional, enumerated string, default=not_validated
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.
Show all values[+]
discounts[index][0..n]
optional, integer, min=0
discounts[coupon_id][0..n]
optional, string, max chars=100
discounts[percentage][0..n]
optional, double, min=0.01, max=100.0
discounts[amount][0..n]
optional, in cents, min=0
discounts[included_in_mrr][0..n]
optional, boolean
subscription_info[index][0..n]
required, integer, min=0
subscription_info[subscription_id][0..n]
optional, string, max chars=50
subscription_info[billing_cycles][0..n]
optional, integer, min=0
subscription_info[contract_term_billing_cycle_on_renewal][0..n]
optional, integer, min=1, max=100
contract_terms[index][0..n]
required, integer, min=0
contract_terms[action_at_term_end][0..n]
optional, enumerated string, default=renew
Possible values are
renewevergreencancelrenew_once
Show all values[+]
contract_terms[cancellation_cutoff_period][0..n]
optional, integer
estimate estimate
always returned
Resource object representing estimate

Sample admin console URL

https://{site}.chargebee.com/admin-console/purchases/123x