The purchase
resource represents a collection of subscriptions bought together. Since a subscription
always has exactly one plan-item price, a purchase
enables your customer to subscribe to multiple plans. This is particularly beneficial for the E-commerce domain where a customer can subscribe to plans for multiple items.
Prerequisite
Purchases must be enabled explicitly for the site. If not already enabled, contact Chargebee Support. Puchases 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
optional, string, max chars=100
The unique identifier of the purchase resource. This is always autogenerated.
string, max chars=50The unique identifier of the
customer that made this purchase.
optional, timestamp(UTC) in seconds
The time at which this purchase was created.
optional, timestamp(UTC) in seconds
The time at which the purchase was modified.
optional, list of stringThe unique identifiers of the
subscriptions that are bundled as part of this purchase. Since the
purchase
resource is never modified, these IDs remain even when the associated subscriptions have been deleted.
optional, list of stringThe unique identifier of the
invoice that is created immediately as part of this purchase. This array always has just one element.
Creates a purchase
resource with associated subscriptions.
The subscriptions are created for this purchase with invoice_immediately
set as true
. In other words, charges are never left unbilled when calling this API and a single consolidated invoice is created immediately for all the subscriptions. Subsequently, if the criteria for consolidation are not met during subscription renewals, separate invoices are generated. For example, if Consolidated Invoicing is disabled after a purchase is made, subsequent renewals generate separate invoices.
Prerequisite
Purchases must be enabled explicitly for the site. If not already enabled, contact Chargebee Support. Puchases require the following features to work so they’re automatically enabled along with them:
Limitations
- No more than five subscriptions can be part of a single purchase.
- For each subscription, there can be up to 10 non-mandatory addons or charges. For example, if there are 5 mandatory addons in one of the subscriptions, you can still add up to 10 more item prices to the subscription that are either addons or charges. In other words, you can add say, 1 addon and 9 charges, or 6 addons and 4 charges to that subscription.
Sample Request
curl https://{site}.chargebee.com/api/v2/purchases \
-X POST \
-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
copy
curl https://{site}.chargebee.com/api/v2/purchases \
-X POST \
-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 \
-X POST \
-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 \
-X POST \
-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"
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",
{..}
]
}}
Show more...
{"purchase": {
"created_at": 1651662627,
"customer_id": "__test__rHsiT4rY3cD1Z",
"id": "__test__rHsiT4rY43w1k",
"invoice_ids": [
"__demo_inv__5",
{..}
],
"object": "purchase",
"subscription_ids": [
"sub_handle1",
{..}
]
}}
Show more...
{"purchase": {
"created_at": 1651662625,
"customer_id": "__test__rHsiT4rY2xO1I",
"id": "__test__rHsiT4rY3Qg1R",
"invoice_ids": [
"__demo_inv__3",
{..}
],
"object": "purchase",
"subscription_ids": [
"sub1",
{..}
]
}}
URL Format POST
https://{site}.chargebee.com/api/v2/purchases
required, string, max chars=50The unique identifier of the
customer that made this purchase.
Parameters for invoice_info
pass parameters as invoice_info[<param name>]
optional, string, max chars=100The
purchase order number for this purchase. This is reflected in all the subscriptions and invoices under this purchase.
optional, string, max chars=2000A 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.
Parameters for purchase_items. Multiple purchase_items can be passed by specifying unique indices.
pass parameters as purchase_items[<param name>][<idx:0..n>]
purchase_items[index][0..n]
required, integer, min=0, max=4
The index number of the subscription to which the item price is added. Provide a unique number between 0
and 4
(inclusive) for each subscription that is to be created.
purchase_items[item_price_id][0..n]
required, string, max chars=100The unique identifier of the
item price to be added to the subscription. The subscription to which the item price is added is specified using
index
.
purchase_items[quantity][0..n]
optional, integer, default=1, min=1The quantity of the item price. Applicable only when the
pricing model of the item price is anything other than
flat_fee
.
purchase_items[unit_amount][0..n]
optional, in cents, min=0The 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=33The 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=33The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when
multi-decimal pricing is enabled.
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
required, integer, min=0, max=4
The index number of the subscription 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.
optional, in cents, default=0, min=0The 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=33The 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=33The 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=33The 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.
Parameters for shipping_addresses. Multiple shipping_addresses can be passed by specifying unique indices.
pass parameters as shipping_addresses[<param name>][<idx:0..n>]
shipping_addresses[first_name][0..n]
optional, string, max chars=150
The first name of the contact.
shipping_addresses[last_name][0..n]
optional, string, max chars=150
The last name of the contact.
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
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.
shipping_addresses[state][0..n]
optional, string, max chars=50
The state/province name.
shipping_addresses[state_code][0..n]
optional, string, max chars=50The
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=50The 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.
shipping_addresses[zip][0..n]
optional, string, max chars=20Zip or postal code. The number of characters is validated according to the rules
specified here.
shipping_addresses[validation_status][0..n]
optional, enumerated string, default=not_validatedThe 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.
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
optional, integer, min=0, max=4The index number of the subscription 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_type
or coupon.max_redemptions
.
discounts[coupon_id][0..n]
optional, string, max chars=100The unique ID of a coupon to be applied to the subscription. Alternatively, you may provide a coupon code. The subscription is specified using discounts[index][i]
.
Note:
- For a given array index
i
, when passing this parameter, no other parameter for discounts[]
except discounts[index][i]
should be passed. Those parameters are for applying manual discounts. - If
discounts[index][i]
is not provided, the coupon is applied to the first invoice only.
discounts[percentage][0..n]
optional, double, min=0.01, max=100.0The percentage of the discount.
For any given array index i
:
- You must either provide
discounts[percentage][i]
or discounts[amount][i]
and never both. - Never pass
discounts[coupon_id][i]
when passing this parameter.
optional, in cents, min=0The absolute value of the discount. The currency units in which this value is expressed depends on the type of currency.
For any given array index i
:
- You must either provide
discounts[percentage][i]
or discounts[amount][i]
and never both. - Never pass
discounts[coupon_id][i]
when passing this parameter.
discounts[included_in_mrr][0..n]
optional, booleanSet 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:
Do not pass this for any array index i when discounts[coupon_id][i]
is passed.
Parameters for subscription_info. Multiple subscription_info can be passed by specifying unique indices.
pass parameters as subscription_info[<param name>][<idx:0..n>]
subscription_info[index][0..n]
required, integer, min=0, max=4
The index number of the subscription to which this subscription information belongs. This must be a value from the purchase_items[index]
array.
subscription_info[subscription_id][0..n]
optional, string, max chars=50The unique identifier of the
subscription to which the item price is added. Just like
index
, this must be provided as a unique value for each subscription.
subscription_info[billing_cycles][0..n]
optional, integer, min=0The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles
set for the plan-item price is used.
always returned
Resource object representing purchase
Returns an estimate for a purchase
.
The subscriptions are estimated for this purchase with invoice_immediately
set as true
. In other words, charges are never left unbilled when calling this API.
Prerequisite
Purchases must be enabled explicitly for the site. If not already enabled, contact Chargebee Support. Puchases require the following features to work so they’re automatically enabled along with them:
Limitations
- No more than five subscriptions can be part of a single purchase.
- For each subscription, there can be up to 10 non-mandatory addons or charges. For example, if there are 5 mandatory addons in one of the subscriptions, you can still add up to 10 more item prices to the subscription that are either addons or charges. In other words, you can add say, 1 addon and 9 charges, or 6 addons and 4 charges to that subscription.
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
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
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
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"
}}
Show more...
{"estimate": {
"created_at": 1651662619,
"invoice_estimates": [
{
"amount_due": 16500,
"amount_paid": 0,
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__rHsiT4rY0iyo",
"date": 1651662618,
"line_item_discounts": [],
"line_item_taxes": [],
"line_item_tiers": [
{
"ending_unit": 10,
"line_item_id": "li___test__rHsiT4rY1hQv",
"object": "line_item_tier",
"quantity_used": 5,
"starting_unit": 1,
"unit_amount": 1000
},
{..}
],
"line_items": [
{
"amount": 5000,
"customer_id": "__test__rHsiT4rY0iyo",
"date_from": 1651662618,
"date_to": 1654341018,
"description": "basic USD",
"discount_amount": 0,
"entity_id": "basic-USD",
"entity_type": "plan_item_price",
"id": "li___test__rHsiT4rY1dqs",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 5,
"subscription_id": "sub_handle1",
"tax_amount": 0,
"unit_amount": 1000
},
{..}
],
"object": "invoice_estimate",
"price_type": "tax_exclusive",
"recurring": true,
"round_off_amount": 0,
"sub_total": 16500,
"taxes": [],
"total": 16500
},
{..}
],
"object": "estimate"
}}
Show more...
{
"estimate": {
"created_at": 1654661087,
"invoice_estimates": [
{
"amount_due": 15000,
"amount_paid": 0,
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__XpbG9acT88TII837",
"date": 1654661087,
"line_item_discounts": [],
"line_item_taxes": [],
"line_item_tiers": [
{
"ending_unit": 10,
"line_item_id": "li___test__XpbG9acT88TIRV3F",
"object": "line_item_tier",
"quantity_used": 5,
"starting_unit": 1,
"unit_amount": 1000
},
{..}
],
"line_items": [
{
"amount": 10000,
"customer_id": "__test__XpbG9acT88TII837",
"date_from": 1654661087,
"date_to": 1657253087,
"description": "basic USD",
"discount_amount": 0,
"entity_id": "basic-USD",
"entity_type": "plan_item_price",
"id": "li___test__XpbG9acT88TIQp3C",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 10,
"subscription_id": "__test__XpbG9acT88TIQ83A",
"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"
},
"subscription_estimate": {
"object": "subscription_estimate",
"subscription_estimates": [
{
"currency_code": "USD",
"id": "__test__XpbG9acT88TIQ83A",
"next_billing_at": 1657253087,
"object": "subscription_estimate",
"status": "active"
},
{..}
]
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/purchases/estimate
optional, string, max chars=50The unique identifier of the
customer that made this purchase.
Parameters for invoice_info
pass parameters as invoice_info[<param name>]
optional, string, max chars=100The
purchase order number for this purchase. This is reflected in all the subscriptions and invoices under this purchase.
optional, string, max chars=2000A 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.
Parameters for customer
pass parameters as customer[<param name>]
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=10An 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, booleanConfirms 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.
optional, enumerated string, default=taxableSpecifies 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.
optional, enumerated stringThe 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
Show all values[+]
optional, string, max chars=100Any 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, jsonarrayIndicates 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.
optional, enumerated stringIndicates 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
Parameters for billing_address
pass parameters as billing_address[<param name>]
optional, string, max chars=150
Address line 1
optional, string, max chars=150
Address line 2
optional, string, max chars=150
Address line 3
optional, string, max chars=50
The name of the city.
billing_address[state_code]
optional, string, max chars=50The
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
).
optional, string, max chars=20Zip or postal code. The number of characters is validated according to the rules
specified here.
optional, string, max chars=50The 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_validatedThe 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.
Parameters for purchase_items. Multiple purchase_items can be passed by specifying unique indices.
pass parameters as purchase_items[<param name>][<idx:0..n>]
purchase_items[index][0..n]
required, integer, min=0, max=4
The index number of the subscription to which the item price is added. Provide a unique number between 0
and 4
(inclusive) for each subscription that is to be created.
purchase_items[item_price_id][0..n]
required, string, max chars=100The unique identifier of the
item price to be added to the subscription. The subscription to which the item price is added is specified using
index
.
purchase_items[quantity][0..n]
optional, integer, default=1, min=1The quantity of the item price. Applicable only when the
pricing model of the item price is anything other than
flat_fee
.
purchase_items[unit_amount][0..n]
optional, in cents, min=0The 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=33The 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=33The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when
multi-decimal pricing is enabled.
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
required, integer, min=0, max=4
The index number of the subscription 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.
optional, in cents, default=0, min=0The 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=33The 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=33The 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=33The 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.
Parameters for shipping_addresses. Multiple shipping_addresses can be passed by specifying unique indices.
pass parameters as shipping_addresses[<param name>][<idx:0..n>]
shipping_addresses[first_name][0..n]
optional, string, max chars=150
The first name of the contact.
shipping_addresses[last_name][0..n]
optional, string, max chars=150
The last name of the contact.
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
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.
shipping_addresses[state][0..n]
optional, string, max chars=50
The state/province name.
shipping_addresses[state_code][0..n]
optional, string, max chars=50The
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=50The 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.
shipping_addresses[zip][0..n]
optional, string, max chars=20Zip or postal code. The number of characters is validated according to the rules
specified here.
shipping_addresses[validation_status][0..n]
optional, enumerated string, default=not_validatedThe 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.
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
optional, integer, min=0, max=4The index number of the subscription 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_type
or coupon.max_redemptions
.
discounts[coupon_id][0..n]
optional, string, max chars=100The unique ID of a coupon to be applied to the subscription. Alternatively, you may provide a coupon code. The subscription is specified using discounts[index][i]
.
Note:
- For a given array index
i
, when passing this parameter, no other parameter for discounts[]
except discounts[index][i]
should be passed. Those parameters are for applying manual discounts. - If
discounts[index][i]
is not provided, the coupon is applied to the first invoice only.
discounts[percentage][0..n]
optional, double, min=0.01, max=100.0The percentage of the discount.
For any given array index i
:
- You must either provide
discounts[percentage][i]
or discounts[amount][i]
and never both. - Never pass
discounts[coupon_id][i]
when passing this parameter.
optional, in cents, min=0The absolute value of the discount. The currency units in which this value is expressed depends on the type of currency.
For any given array index i
:
- You must either provide
discounts[percentage][i]
or discounts[amount][i]
and never both. - Never pass
discounts[coupon_id][i]
when passing this parameter.
discounts[included_in_mrr][0..n]
optional, booleanSet 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:
Do not pass this for any array index i when discounts[coupon_id][i]
is passed.
Parameters for subscription_info. Multiple subscription_info can be passed by specifying unique indices.
pass parameters as subscription_info[<param name>][<idx:0..n>]
subscription_info[index][0..n]
required, integer, min=0, max=4
The index number of the subscription to which this subscription information belongs. This must be a value from the purchase_items[index]
array.
subscription_info[subscription_id][0..n]
optional, string, max chars=50The unique identifier of the
subscription to which the item price is added. Just like
index
, this must be provided as a unique value for each subscription.
subscription_info[billing_cycles][0..n]
optional, integer, min=0The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles
set for the plan-item price is used.
always returned
Resource object representing estimate