Settings
API Version
Product Catalog
Library

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.

The purchase resource represents a collection of item prices bought together. 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)

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.

Sample purchase [ JSON ]

{ "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" ] }

API Index URL GET

https://{site}.chargebee.com/api/v2/purchases

Model Class

 

      Purchase attributes
      
 
id
 

      optional, string, max chars=100
 The unique identifier of the purchase resource. This is always autogenerated. 
 
 
customer_id
 

      string, max chars=50
 The unique identifier of the customer that made this purchase. 
 
 
created_at
 

      optional, timestamp(UTC) in seconds
 The time at which this purchase was created. 
 
 
modified_at
 

      optional, timestamp(UTC) in seconds
 The time at which the purchase was modified. 
 
 
subscription_ids
 

      optional, list of string
 The unique identifiers of the subscriptions that are created as part of this purchase. These IDs remain even when the associated subscriptions have been deleted. 
 
 
invoice_ids
 

      optional, list of string
 The unique identifier of the invoice(s) created immediately as part of this purchase. 
 
 
 
 
id id
 

          optional, string, max chars=100
 The unique identifier of the purchase resource. This is always autogenerated. 
 
customer_id customer_id
 

          string, max chars=50
 The unique identifier of the customer that made this purchase. 
 
created_at created_at
 

          optional, timestamp(UTC) in seconds
 The time at which this purchase was created. 
 
modified_at modified_at
 

          optional, timestamp(UTC) in seconds
 The time at which the purchase was modified. 
 
subscription_ids subscription_ids
 

          optional, list of string
 The unique identifiers of the subscriptions that are created as part of this purchase. These IDs remain even when the associated subscriptions have been deleted. 
 
invoice_ids invoice_ids
 

          optional, list of string
 The unique identifier of the invoice(s) created immediately as part of this purchase. 
 
 
 
Consent Fields for Purchase
 
 
Custom Fields for Purchase
 
 

      Create a purchase
      
 
Idempotency Supported
 
 
 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
 

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

        		
    

    



  
Notes
 
 

      Sample Request
    
 
 
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" 
 

      copy
      
Click to Copy
 
 
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 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "purchase": {
        "created_at": 1651662622,
        "customer_id": "__test__rHsiT4rY1zmz",
        "id": "__test__rHsiT4rY2hC1A",
        "invoice_ids": [
            "__demo_inv__1",
            {..}
        ],
        "object": "purchase",
        "subscription_ids": [
            "__test__rHsiT4rY2Lr12",
            {..}
        ]
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/purchases
    
 
Method
 
 
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. 
 
 
 
 
 
invoice_info[po_number]
 
optional, string, max chars=100 
 The purchase order number for this purchase. This is reflected in all the subscriptions and invoices under this purchase. 
invoice_info[notes]
 
optional, string, max chars=2000 
 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. 
 
 
payment_schedule[scheme_id]
 
optional, string, max chars=40 
 The identifier of the payment_schedule_scheme, used to create the payment schedules.  
payment_schedule[amount]
 
optional, in cents, min=0 
 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.  
 
 
statement_descriptor[descriptor]
 
optional, string, max chars=65k 
 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. 
 
 
payment_intent[id]
 
optional, string, max chars=150 
 Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed. 
payment_intent[gateway_account_id]
 
required if payment intent token provided, string, max chars=50 
 The gateway account used for performing the 3DS flow. 
payment_intent[gw_token]
 
optional, string, max chars=65k 
  Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer  3DS implementation in Chargebee  to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow. 
payment_intent[payment_method_type]
 
optional, enumerated string 
 The list of payment method types (For example, card, ideal, sofort, bancontact, etc.) this Payment Intent is allowed to use. If payment method type is empty, Card is taken as the default type for all gateways except Razorpay. 
Possible values are
 
cardcardidealidealsofortsofortbancontactbancontactgoogle_paygoogle_paydotpaydotpaygiropaygiropayapple_payapple_payupiupinetbanking_emandatesnetbanking_emandatespaypal_express_checkoutpaypal_express_checkoutdirect_debitdirect_debitboletoboletovenmoVenmo amazon_paymentsAmazon Paymentspay_toPayTo faster_paymentsFaster Payments sepa_instant_transferSepa Instant Transfer klarna_pay_nowKlarna Pay Now online_banking_polandOnline Banking Poland 
 
cardcardidealidealsofortsofortbancontactbancontact
 
google_paygoogle_paydotpaydotpaygiropaygiropayapple_payapple_payupiupinetbanking_emandatesnetbanking_emandatespaypal_express_checkoutpaypal_express_checkoutdirect_debitdirect_debitboletoboletovenmoVenmo amazon_paymentsAmazon Paymentspay_toPayTo faster_paymentsFaster Payments sepa_instant_transferSepa Instant Transfer klarna_pay_nowKlarna Pay Now online_banking_polandOnline Banking Poland 
 Show all values[+]
payment_intent[reference_id]
 
optional, string, max chars=65k 
 Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow. 
payment_intent[additional_information]
 
optional, jsonobject 
 
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
  • bank_of_america: While passing raw card details to Bank of America, your user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
  • ecentric: This parameter is used to verify and process payment method details in Ecentric. If the merchant_id parameter is included, Chargebee will vault it / perform a lookup and verification against this merchant_id, overriding the one configured in Chargebee. If tokens and processing occur in the same Merchant GUID, you can just skip this part. 
    • merchant_id: Merchant GUID where the card is vaulted or need to be vaulted.
      •  
     
  • ebanx: While passing raw card details to EBANX, the user's document is required for some countries and device_session_id can be added to perform additional validation and avoid fraudulent transactions. 
       
    •  payer: User related information. 
         
      •  document: Document is the user's identification number based on their country. 
        •  
       
      •  
    •  fraud: Fraud identification related information. 
         
      •  device_session_id: Session ID associated with the user's device 
        •  
       
      •  
      
  • dlocal: While passing raw card details to D-Local, the user's document is required for some countries to avoid fraudulent transactions. 
       
    •  document: Document is the user's identification number based on their country. 
      •  
      
 
 
 
purchase_items[index][0..n]
 
required, integer, min=0 
 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[item_price_id][0..n]
 
required, string, max chars=100 
 The unique identifier of the item price to be added to the group.
 
purchase_items[quantity][0..n]
 
optional, integer, default=1, min=1 
 The quantity of the item price. Applicable only when the 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[unit_amount][0..n]
 
optional, in cents, min=0 
 The price or per unit price of the item. You may provide this only when price overriding is enabled for the site. 
purchase_items[unit_amount_in_decimal][0..n]
 
optional, string, max chars=39 
 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. 
purchase_items[quantity_in_decimal][0..n]
 
optional, string, max chars=33 
 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]. 
 
 
item_tiers[index][0..n]
 
required, integer, min=0 
 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[item_price_id][0..n]
 
optional, string, max chars=100 
 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[starting_unit][0..n]
 
optional, integer, min=1 
 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][0..n]
 
optional, integer 
 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[price][0..n]
 
optional, in cents, default=0, min=0 
 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[starting_unit_in_decimal][0..n]
 
optional, string, max chars=33 
 The decimal representation of the 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[ending_unit_in_decimal][0..n]
 
optional, string, max chars=33 
 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. 
item_tiers[price_in_decimal][0..n]
 
optional, string, max chars=39 
 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. 
 
 
shipping_addresses[first_name][0..n]
 
optional, string, max chars=150 
 The first name of the contact. This parameter is mandatory when providing shipping information. 
shipping_addresses[last_name][0..n]
 
optional, string, max chars=150 
 The last name of the contact. This parameter is mandatory when providing shipping information. 
shipping_addresses[email][0..n]
 
optional, string, max chars=70 
 The email address. 
shipping_addresses[company][0..n]
 
optional, string, max chars=250 
 The company name. 
shipping_addresses[phone][0..n]
 
optional, string, max chars=50 
 The phone number. 
shipping_addresses[line1][0..n]
 
optional, string, max chars=150 
 Address line 1. This parameter is mandatory when providing shipping information. 
shipping_addresses[line2][0..n]
 
optional, string, max chars=150 
 Address line 2 
shipping_addresses[line3][0..n]
 
optional, string, max chars=150 
 Address line 3 
shipping_addresses[city][0..n]
 
optional, string, max chars=50 
 The name of the city. This parameter is mandatory when providing shipping information. 
shipping_addresses[state][0..n]
 
optional, string, max chars=50 
 The state/province name. 
shipping_addresses[state_code][0..n]
 
optional, string, max chars=50 
 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[country][0..n]
 
optional, string, max chars=50 
 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.
 


 
shipping_addresses[zip][0..n]
 
optional, string, max chars=20 
 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[validation_status][0..n]
 
optional, enumerated string, default=not_validated 
 The address verification status. 
Possible values are
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
 Show all values[+]
 
 
discounts[index][0..n]
 
optional, integer, min=0 
 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
 
discounts[coupon_id][0..n]
 
optional, string, max chars=100 
 
The unique ID of a coupon to be applied to the group. Alternatively, you may provide a coupon code. Applicable only for coupons.



    
See also:
Applying discounts
 
discounts[percentage][0..n]
 
optional, double, min=0.01, max=100.0 
 
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][0..n]
 
optional, in cents, min=0 
 
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[included_in_mrr][0..n]
 
optional, boolean 
 
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:


 
See also:
 
Applying discounts
 
 
 
 
subscription_info[index][0..n]
 
required, integer, min=0 
 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[subscription_id][0..n]
 
optional, string, max chars=50 
 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][0..n]
 
optional, integer, min=0 
 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. 
subscription_info[contract_term_billing_cycle_on_renewal][0..n]
 
optional, integer, min=1, max=100 
 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[meta_data][0..n]
 
optional, jsonobject 
 A collection of key-value pairs that provides extra information about the purchase. 
Note: There's a character limit of 65,535.
 Learn more. 
 
 
contract_terms[index][0..n]
 
required, integer, min=0 
 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[action_at_term_end][0..n]
 
optional, enumerated string, default=renew 
 Action to be taken when the contract term completes. 
Possible values are
 
renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
    • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following: 
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to cancel.
    •  
    renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
    • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following: 
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to cancel.
    •  
     Show all values[+]
    contract_terms[cancellation_cutoff_period][0..n]
     
    optional, integer 
     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 
       
     
    Returns
     
    purchase  purchase
     
    
      always returned 
     Resource object representing purchase
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/purchases/123x
    
    
      Estimates for purchase
      
      
     
     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.
     
    
    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.

    

      
    Notes
     
     
    
      Sample Request
    
     
     
    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 
     
    
      copy
      
    Click to Copy
     
     
    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 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "estimate": {
        "created_at": 1651662607,
        "invoice_estimates": [
            {
                "amount_due": 15000,
                "amount_paid": 0,
                "credits_applied": 0,
                "currency_code": "USD",
                "customer_id": "__test__rHsiT4rXxy4U",
                "date": 1651662606,
                "line_item_discounts": [],
                "line_item_taxes": [],
                "line_item_tiers": [
                    {
                        "ending_unit": 10,
                        "line_item_id": "li___test__rHsiT4rXyUya",
                        "object": "line_item_tier",
                        "quantity_used": 5,
                        "starting_unit": 1,
                        "unit_amount": 1000
                    },
                    {..}
                ],
                "line_items": [
                    {
                        "amount": 10000,
                        "customer_id": "__test__rHsiT4rXxy4U",
                        "date_from": 1651662604,
                        "date_to": 1654341004,
                        "description": "basic USD",
                        "discount_amount": 0,
                        "entity_id": "basic-USD",
                        "entity_type": "plan_item_price",
                        "id": "li___test__rHsiT4rXyJmX",
                        "is_taxed": false,
                        "item_level_discount_amount": 0,
                        "object": "line_item",
                        "pricing_model": "per_unit",
                        "quantity": 10,
                        "subscription_id": "__test__rHsiT4rXxzvV",
                        "tax_amount": 0,
                        "unit_amount": 1000
                    },
                    {..}
                ],
                "object": "invoice_estimate",
                "price_type": "tax_exclusive",
                "recurring": true,
                "round_off_amount": 0,
                "sub_total": 15000,
                "taxes": [],
                "total": 15000
            },
            {..}
        ],
        "object": "estimate"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/purchases/estimate
    
     
    Method
     
     
    Input Parameters
     
      
     
    client_profile_id[]
     
    
      optional, string, max chars=50 
     Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration. 
     
    customer_id[]
     
    
      optional, string, max chars=50 
     The unique identifier of the customer that made this purchase. 
     
     
     
     
     
    customer[vat_number]
     
    optional, string, max chars=20 
     VAT number of this customer. If not provided then taxes are not calculated for the estimate. Applicable only when taxes are configured for the EU or UK region. VAT validation is not done for this. 
    customer[vat_number_prefix]
     
    optional, string, max chars=10 
     An overridden value for the first two characters of the full VAT
    number. Only applicable specifically for customers with billing_address
country as XI (which is United Kingdom - Northern Ireland).

    

When you have enabled EU VAT in 2021 or have manually
    enabled the Brexit configuration, you have the option of setting billing_address
country as XI. That’s the code for United Kingdom - Northern
    Ireland. The first two characters of the VAT number in such a case is
XI by default. However, if the VAT number was registered in UK, the value should be GB. Set
vat_number_prefix to GB for such cases.     
    customer[registered_for_gst]
     
    optional, boolean 
     Confirms that a customer is registered under GST. If set to true then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site. 
    customer[taxability]
     
    optional, enumerated string, default=taxable 
     Specifies if the customer is liable for tax 
    Possible values are
     
    taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt
    • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
    • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
     
    taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt
    • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
    • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
     
     Show all values[+]
    customer[entity_code]
     
    optional, enumerated string 
     The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration. 
    Possible values are
     
    aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomateCharitable or benevolent organizationfReligious organizationgResalehCommercial agricultural productioniIndustrial production/manufacturerjDirect pay permitkDirect maillOther or custommEducational organizationnLocal governmentpCommercial aquacultureqCommercial FisheryrNon-residentmed1US Medical Device Excise Tax with exempt sales taxmed2US Medical Device Excise Tax with taxable sales tax
     
    aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat
     
    eCharitable or benevolent organizationfReligious organizationgResalehCommercial agricultural productioniIndustrial production/manufacturerjDirect pay permitkDirect maillOther or custommEducational organizationnLocal governmentpCommercial aquacultureqCommercial FisheryrNon-residentmed1US Medical Device Excise Tax with exempt sales taxmed2US Medical Device Excise Tax with taxable sales tax
     Show all values[+]
    customer[exempt_number]
     
    optional, string, max chars=100 
     Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's AvaTax for Sales integration. 
    customer[exemption_details]
     
    optional, jsonarray 
     Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
     To know more about what values you need to provide, refer to this Avalara’s API document.     
    customer[customer_type]
     
    optional, enumerated string 
     Indicates the type of the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration. 
    Possible values are
     
    residentialWhen the purchase is made by a customer for home usebusinessWhen the purchase is made at a place of businesssenior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaksindustrialWhen the purchase is made by an industrial business
     
    residentialWhen the purchase is made by a customer for home usebusinessWhen the purchase is made at a place of businesssenior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaksindustrialWhen the purchase is made by an industrial business
     
     Show all values[+]
     
     
    billing_address[line1]
     
    optional, string, max chars=150 
     Address line 1 
    billing_address[line2]
     
    optional, string, max chars=150 
     Address line 2 
    billing_address[line3]
     
    optional, string, max chars=150 
     Address line 3 
    billing_address[city]
     
    optional, string, max chars=50 
     The name of the city. 
    billing_address[state_code]
     
    optional, string, max chars=50 
     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). 
    billing_address[zip]
     
    optional, string, max chars=20 
     Zip or postal code. The number of characters is validated according to the rules specified here. 
    billing_address[country]
     
    optional, string, max chars=50 
     The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.


    
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.
    
    

     
    billing_address[validation_status]
     
    optional, enumerated string, default=not_validated 
     The address verification status. 
    Possible values are
     
    not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
     
    not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
     
     Show all values[+]
     
     
    purchase_items[index][0..n]
     
    required, integer, min=0 
     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[item_price_id][0..n]
     
    required, string, max chars=100 
     The unique identifier of the item price to be added to the group.
 
    purchase_items[quantity][0..n]
     
    optional, integer, default=1, min=1 
     The quantity of the item price. Applicable only when the 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[unit_amount][0..n]
     
    optional, in cents, min=0 
     The price or per unit price of the item. You may provide this only when price overriding is enabled for the site. 
    purchase_items[unit_amount_in_decimal][0..n]
     
    optional, string, max chars=39 
     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. 
    purchase_items[quantity_in_decimal][0..n]
     
    optional, string, max chars=33 
     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]. 
     
     
    item_tiers[index][0..n]
     
    required, integer, min=0 
     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[item_price_id][0..n]
     
    optional, string, max chars=100 
     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[starting_unit][0..n]
     
    optional, integer, min=1 
     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][0..n]
     
    optional, integer 
     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[price][0..n]
     
    optional, in cents, default=0, min=0 
     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[starting_unit_in_decimal][0..n]
     
    optional, string, max chars=33 
     The decimal representation of the 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[ending_unit_in_decimal][0..n]
     
    optional, string, max chars=33 
     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. 
    item_tiers[price_in_decimal][0..n]
     
    optional, string, max chars=39 
     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. 
     
     
    shipping_addresses[first_name][0..n]
     
    optional, string, max chars=150 
     The first name of the contact. This parameter is mandatory when providing shipping information. 
    shipping_addresses[last_name][0..n]
     
    optional, string, max chars=150 
     The last name of the contact. This parameter is mandatory when providing shipping information. 
    shipping_addresses[email][0..n]
     
    optional, string, max chars=70 
     The email address. 
    shipping_addresses[company][0..n]
     
    optional, string, max chars=250 
     The company name. 
    shipping_addresses[phone][0..n]
     
    optional, string, max chars=50 
     The phone number. 
    shipping_addresses[line1][0..n]
     
    optional, string, max chars=150 
     Address line 1. This parameter is mandatory when providing shipping information. 
    shipping_addresses[line2][0..n]
     
    optional, string, max chars=150 
     Address line 2 
    shipping_addresses[line3][0..n]
     
    optional, string, max chars=150 
     Address line 3 
    shipping_addresses[city][0..n]
     
    optional, string, max chars=50 
     The name of the city. This parameter is mandatory when providing shipping information. 
    shipping_addresses[state][0..n]
     
    optional, string, max chars=50 
     The state/province name. 
    shipping_addresses[state_code][0..n]
     
    optional, string, max chars=50 
     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[country][0..n]
     
    optional, string, max chars=50 
     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.
    
    

     
    shipping_addresses[zip][0..n]
     
    optional, string, max chars=20 
     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[validation_status][0..n]
     
    optional, enumerated string, default=not_validated 
     The address verification status. 
    Possible values are
     
    not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
     
    not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
     
     Show all values[+]
     
     
    discounts[index][0..n]
     
    optional, integer, min=0 
     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
     
    discounts[coupon_id][0..n]
     
    optional, string, max chars=100 
     
    The unique ID of a coupon to be applied to the group. Alternatively, you may provide a coupon code. Applicable only for coupons.
    

    
    
    See also:
    Applying discounts
     
    discounts[percentage][0..n]
     
    optional, double, min=0.01, max=100.0 
     
    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][0..n]
     
    optional, in cents, min=0 
     
    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[included_in_mrr][0..n]
     
    optional, boolean 
     
    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:
    

     
    See also:
     
    Applying discounts
     
     
     
     
    subscription_info[index][0..n]
     
    required, integer, min=0 
     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[subscription_id][0..n]
     
    optional, string, max chars=50 
     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][0..n]
     
    optional, integer, min=0 
     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. 
    subscription_info[contract_term_billing_cycle_on_renewal][0..n]
     
    optional, integer, min=1, max=100 
     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. 
     
     
    contract_terms[index][0..n]
     
    required, integer, min=0 
     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[action_at_term_end][0..n]
     
    optional, enumerated string, default=renew 
     Action to be taken when the contract term completes. 
    Possible values are
     
    renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
    • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following: 
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to cancel.
    •  
    renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
    • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following: 
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to cancel.
    •  
     Show all values[+]
    contract_terms[cancellation_cutoff_period][0..n]
     
    optional, integer 
     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 
       
     
    Returns
     
    estimate  estimate
     
    
      always returned 
     Resource object representing estimate
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/purchases/123x