Introducing OpenTelemetry for Chargebee SDKs — trace every API call in any telemetry tool.
Chargebeechargebee API

Create a purchase

Idempotency Supported

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 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.

Sample Request

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/purchases

Input Parameters

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>]
payment_schedule
Parameters for payment_schedule
pass parameters as payment_schedule[<param name>]
statement_descriptor
Parameters for statement_descriptor
pass parameters as statement_descriptor[<param name>]
payment_intent
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
purchase_items[0..n]
Parameters for purchase_items. Multiple purchase_items can be passed by specifying unique indices.
pass parameters as purchase_items[<param name>][<idx:0..n>]
item_tiers[0..n]
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
shipping_addresses[0..n]
Parameters for shipping_addresses. Multiple shipping_addresses can be passed by specifying unique indices.
pass parameters as shipping_addresses[<param name>][<idx:0..n>]
discounts[0..n]
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
subscription_info[0..n]
Parameters for subscription_info. Multiple subscription_info can be passed by specifying unique indices.
pass parameters as subscription_info[<param name>][<idx:0..n>]
contract_terms[0..n]
Parameters for contract_terms. Multiple contract_terms can be passed by specifying unique indices.
pass parameters as contract_terms[<param name>][<idx:0..n>]

Returns

purchase
Purchase object

Resource object representing purchase