The purchase
resource represents a collection of item prices bought together. A purchase can contain one or more of the following:
subscription
resource consists of item prices such that at least one of the item prices belongs to an item
of type
plan
.)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.
{
"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"
]
}
Creates a purchase
resource. A purchase can contain one or more of the following:
subscription
resource consists of item prices such that at least one of the item prices belongs to an item
of type
plan
.)Note
Providing shipping_addresses[]
is required when the Orders feature has been enabled.
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:
The following subsections describe the types of groups in detail.
Note
You can specify up to 10 groups,
The total limit for group items for a single purchase is 60.
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.
Purchase API supports custom fields of Subscriptions, use the following format to specify custom fields in Purchase API: subscription_info[custom_field]
.
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
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 |
|
|
Manual discounts |
|
|
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"
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.
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