Create a purchase

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 . The exception is a subscription group whose subscription starts in trial, which is possible when trial support for purchases is enabled for the site. No charges are raised for such a group until the trial ends. When no group in the purchase raises charges, no invoice is created and purchase.invoice_ids is empty.

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.

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. Multi-plan subscriptions are not supported: a group cannot contain more than one plan item price. To create multiple subscriptions, provide multiple subscription groups. Plans in different groups can belong to different item families. When item families are enabled, item prices in one group must belong to the same item family as that group's plan.

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.

Applying discounts

Discounts, both manual discounts and coupons, can be applied to groups by specifying the discounts[] array. You cannot target one item price in a group. A manual discount applies to the invoice for the group. A coupon with apply_on set to invoice_amount applies to the invoice sub_total. A coupon configured for specific item prices applies only to those item prices.

The following table describes the method of application based on whether discounts[index][i] is provided:

Limitations

Item prices in a subscription group are validated the same way as in Create a subscription. This operation also has the following limitations.

Item prices

• A subscription group contains exactly one item price of type plan. You cannot create one subscription with more than one plan item price. Multi-plan subscriptions are not supported.
• Plans in different subscription groups can belong to different item families. When item families are enabled, item prices in one group must belong to the same item family as that group's plan.
• You cannot set a service period for a charge. This operation has no equivalent of subscription_items[service_period_days].

Subscriptions

• You cannot set free_period.
• You cannot set start_date. Each subscription starts immediately. A group can start in trial only when trial support for purchases is enabled and you set subscription_info[trial_end].
• Calendar billing settings for the site apply. You cannot override them with billing_alignment_mode.
• Each subscription uses the customer's auto_collection. You cannot override it for the subscription.
• Only the current term is charged. You cannot set terms_to_charge.
• You cannot create ramps or schedule a subscription change in this request. After the subscriptions are created, use Create a subscription ramp or Update a subscription.
• The purchase resource cannot be changed after it is created. Update each subscription with the subscription operations.

Multiple business entities

This operation does not accept business_entity_id. Calling it on a site where multiple business entities are enabled returns an error.

Invoices

• When the purchase raises invoiceable charges and consolidated invoicing is enabled for the customer, Chargebee consolidates those charges. Subscription differences can still produce more than one invoice. When consolidated invoicing is disabled, each subscription gets its own invoice. A trial-only purchase, where every subscription group starts in trial and no one-time charges are raised, creates no invoice and purchase.invoice_ids is empty.
• Invoices for subscriptions and one-time charges are created immediately and are not left unbilled. A subscription group that starts in trial is the exception: no charges are raised for that group until the trial ends.
• This operation does not accept a net-term parameter. Net terms already set on the customer still apply. When those terms are greater than zero, the invoice is posted and payment collection waits until the due date. When the terms are zero and the customer's auto_collection is on, Chargebee attempts to collect payment while closing the invoice. The operation fails if the customer has no valid payment method, or if collection fails. When auto_collection is off, the invoice is closed with payment due.