Pricing Templates
Log in Sign up
Integrations / Chargebee Product / ...

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:

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:

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.

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

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 provideddiscounts[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

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

Valid 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

Valid 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

Valid values:

  • "all-disabled"

Request body fields

Name Type Required Description
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, provide discounts[percentage][i] or discounts[quantity][i] or discounts[amount][i]

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 can provide discounts[percentage][i] or discounts[quantity][i] or discounts[amount][i]

See also:

Applying discounts
discounts.quantity[] Array No

The discount quantity. Applicable only for manual discounts. For any given array index i, provide discounts[percentage][i] or discounts[quantity][i] or discounts[amount][i]

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

Valid 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
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 <a href="https://apidocs.chargebee.com/docs/api/item_prices?prod_cat_ver=2#item_price_pricing_model\"\ >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.
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.
replace_primary_payment_source Boolean No

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.

Default value: true
customer_id String Yes

The unique identifier of the customer that made this purchase.
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.
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.

How to start integrating

  1. Add HTTP Task to your workflow definition.
  2. 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.
  3. Click Test request to test run your request to the API and see the API's response.
All third party trademarks (including logos and icons) are the property of their respective owners, which do not sponsor, authorize, or endorse this website.
Pricing Templates Integrations Blog Contact Us Help
© 2025 SimWorkflow
Terms of Service Privacy Policy