POST /purchases

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.

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 {#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 {#subscription}

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 {#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 {#one-time}

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}

Discounts, both manual discounts and , 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.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Possible values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Possible values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header `chargebee-request-origin-user` is ignored.
`chargebee-event-email`	String	No	skip only emails Possible values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`customer_id`	String	Yes	The unique identifier of the customer that made this purchase.
`discounts`	Object	No	Parameters for discounts
`discounts.included_in_mrr[]`	Array	No	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
`discounts.percentage[]`	Array	No	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[]`	Array	No	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.coupon_id[]`	Array	No	The unique ID of a coupon to be applied to the group. Alternatively, you may provide a coupon code. Applicable only for . See also: Applying discounts
`discounts.index[]`	Array	No	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
`invoice_info`	Object	No	Parameters for invoice_info
`invoice_info.notes`	String	No	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.
`invoice_info.po_number`	String	No	The purchase order number for this purchase. This is reflected in all the subscriptions and invoices under this purchase.
`subscription_info`	Object	No	Parameters for subscription_info
`subscription_info.meta_data[]`	Array	No	A collection of key-value pairs that provides extra information about the purchase. Note: There's a character limit of 65,535. Learn more.
`subscription_info.index[]`	Array	Yes	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.contract_term_billing_cycle_on_renewal[]`	Array	No	Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as `billing_cycles` or a custom value depending on the site configuration.
`subscription_info.subscription_id[]`	Array	No	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[]`	Array	No	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.
`payment_schedule`	Object	No	Parameters for `payment_schedule`
`payment_schedule.amount`	Integer	No	The part of the `invoice.amount_due` to be distributed across the payment schedules. If not specified, the entire `invoice.amount_due` is considered by default.
`payment_schedule.scheme_id`	String	No	The identifier of the `payment_schedule_scheme`, used to create the payment schedules.
`payment_intent`	Object	No
`payment_intent.id`	String	No
`payment_intent.gateway_account_id`	String	No
`payment_intent.payment_method_type`	String	No	null Possible values: `"bancontact"` `"upi"` `"amazon_payments"` `"online_banking_poland"` `"direct_debit"` `"sofort"` `"boleto"` `"netbanking_emandates"` `"giropay"` `"paypal_express_checkout"` `"apple_pay"` `"pay_to"` `"venmo"` `"payconiq_by_bancontact"` `"card"` `"klarna_pay_now"` `"dotpay"` `"faster_payments"` `"sepa_instant_transfer"` `"google_pay"` `"ideal"`
`payment_intent.additional_information`	Object	No
`payment_intent.gw_token`	String	No
`payment_intent.reference_id`	String	No
`item_tiers`	Object	No	Parameters for item_tiers
`item_tiers.starting_unit_in_decimal[]`	Array	No	The decimal representation of 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.price_in_decimal[]`	Array	No	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.
`item_tiers.price[]`	Array	No	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.ending_unit[]`	Array	No	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.item_price_id[]`	Array	No	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.index[]`	Array	Yes	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.starting_unit[]`	Array	No	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_in_decimal[]`	Array	No	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.
`purchase_items`	Object	No	Parameters for purchase_items
`purchase_items.unit_amount[]`	Array	No	The price or per unit price of the item. You may provide this only when price overriding is enabled for the site.
`purchase_items.item_price_id[]`	Array	Yes	The unique identifier of the item price to be added to the group.
`purchase_items.quantity[]`	Array	No	The quantity of the item price. Applicable only when the [pricing model]("https://apidocs.chargebee.com/docs/api/item_prices?prod_cat_ver=2#item_price_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.quantity_in_decimal[]`	Array	No	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]`.
`purchase_items.index[]`	Array	Yes	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.unit_amount_in_decimal[]`	Array	No	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.
`statement_descriptor`	Object	No	Parameters for statement_descriptor
`statement_descriptor.descriptor`	String	No	Payment transaction descriptor text to help your customer easily recognize the transaction. When you pass this value it will override the transaction descriptor text configured on your Chargebee site for the first consolidated invoice.
`shipping_addresses`	Object	No	Parameters for shipping_addresses
`shipping_addresses.first_name[]`	Array	No	The first name of the contact. This parameter is `mandatory` when providing shipping information.
`shipping_addresses.state[]`	Array	No	The state/province name.
`shipping_addresses.city[]`	Array	No	The name of the city. This parameter is `mandatory` when providing shipping information.
`shipping_addresses.validation_status[]`	Array	No
`shipping_addresses.line2[]`	Array	No	Address line 2
`shipping_addresses.line1[]`	Array	No	Address line 1. This parameter is `mandatory` when providing shipping information.
`shipping_addresses.email[]`	Array	No	The email address.
`shipping_addresses.last_name[]`	Array	No	The last name of the contact. This parameter is `mandatory` when providing shipping information.
`shipping_addresses.company[]`	Array	No	The company name.
`shipping_addresses.line3[]`	Array	No	Address line 3
`shipping_addresses.state_code[]`	Array	No	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.zip[]`	Array	No	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.phone[]`	Array	No	The phone number.
`shipping_addresses.country[]`	Array	No	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.
`payment_source_id`	String	No	Payment source attached to this purchase. If present, the customer's payment sources won't be used to collect any payment for this purchase.
`contract_terms`	Object	No	Parameters for contract_terms
`contract_terms.action_at_term_end[]`	Array	No
`contract_terms.index[]`	Array	Yes	The index number of the subscription/one-time group to which the item price is added. Provide a unique number between `0` and `9` (inclusive) for each group that is to be created. To increase this limit, contact Chargebee Support
`contract_terms.cancellation_cutoff_period[]`	Array	No	The number of days before `contract_end`, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.