Purchases

API Version

Product Catalog

Library

Deprecated The purchase resource and its associated operations on this page are deprecated. Avoid using them in your integrations. The ability to purchase multiple plans in a single subscription will be supported through the Subscriptions API in the future.

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

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.

Try in API Explorer

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.

Sample Request

Try in API Explorer

Only for Java

Only for Java

Only for Java

copy full code

Click to Copy

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

200:

STATUS

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",
            {..}
        ]
    }
}

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.

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.

replace_primary_payment_source[]

optional, boolean, default=true
Indicates whether the primary payment source is replaced with this payment source. If a payment_intent object is included in the request, replace_primary defaults to true. For all other cases, the default is false.

invoice_info

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

invoice_info[po_number]

optional, string, max chars=100

invoice_info[notes]

optional, string, max chars=2000

payment_schedule

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

payment_schedule[scheme_id]

optional, string, max chars=40

payment_schedule[amount]

optional, in cents, min=0

statement_descriptor

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

statement_descriptor[descriptor]

optional, string, max chars=65k

payment_intent

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

payment_intent[id]

optional, string, max chars=150

payment_intent[gateway_account_id]

required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

optional, string, max chars=65k

payment_intent[payment_method_type]

optional, enumerated string

Possible values are

payment_intent[reference_id]

optional, string, max chars=65k

payment_intent[additional_information]

optional, jsonobject

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

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

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

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

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

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

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

discounts[coupon_id][0..n]

optional, string, max chars=100

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

discounts[quantity][0..n]

optional, integer, min=1

discounts[amount][0..n]

optional, in cents, min=0

discounts[included_in_mrr][0..n]

optional, boolean

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

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

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

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

contract_terms[cancellation_cutoff_period][0..n]

optional, integer

purchase

always returned
Resource object representing purchase

Try in API Explorer

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

Try in API Explorer

Only for Java

Only for Java

Only for Java

copy full code

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

copy

Click to Copy

200:

STATUS

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"
    }
}

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

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

customer[entity_code]

optional, enumerated string

Possible values are

customer[exempt_number]

optional, string, max chars=100

customer[exemption_details]

optional

customer[customer_type]

optional, enumerated string

Possible values are

billing_address

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

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

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

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

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

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

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

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

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

discounts[coupon_id][0..n]

optional, string, max chars=100

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

discounts[quantity][0..n]

optional, integer, min=1

discounts[amount][0..n]

optional, in cents, min=0

discounts[included_in_mrr][0..n]

optional, boolean

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

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

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

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

contract_terms[cancellation_cutoff_period][0..n]

optional, integer

estimate

always returned
Resource object representing estimate

Sample purchase [ JSON ]

API Index URL

Model Class

Purchase attributes

Consent Fields for Purchase

Custom Fields for Purchase

Create a purchase ¶

Specifying `purchase_item` groups

Subscription groups

Custom Fields

One-time charge groups

Applying discounts

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Estimates for purchase ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Purchases

Sample purchase [ JSON ]

API Index URL

Model Class

Purchase attributes

Consent Fields for Purchase

Custom Fields for Purchase

Create a purchase ¶

Specifying purchase_item groups

Subscription groups

Custom Fields

One-time charge groups

Applying discounts

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Estimates for purchase ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Specifying `purchase_item` groups