Plans

Specifies the price with billing frequency for a subscription. Create separate plans for varied price or billing frequency. For example, if you need to charge $10 per month for a group of customers and $100 per year for another group of customers, then create separate plans for each.

Sample plan [ JSON ]

{
    "addon_applicability": "all",
    "charge_model": "flat_fee",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "silver",
    "invoice_name": "sample plan",
    "is_shippable": false,
    "name": "Silver",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 5000,
    "pricing_model": "flat_fee",
    "resource_version": 1517505797000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "updated_at": 1517505797
}

API Index URL GET

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

id

A unique ID for your system to identify the plan.
string, max chars=100

name

The display name used in web interface for identifying the plan.
string, max chars=50

invoice_name

Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100

description

Description about the plan to show in the hosted pages & customer portal.
optional, string, max chars=500

price

The price of the plan.
optional, in cents, min=0

currency_code

The currency code (ISO 4217 format) of the plan.
string, max chars=3

period

Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
integer, default=1, min=1

period_unit

Defines billing frequency in association with billing period.
enumerated string, default=month

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

trial_period

The free time window for your customer to try your product.
optional, integer, min=1

trial_period_unit

Time unit for the trial period.
optional, enumerated string

Possible values are

dayIn days.monthIn months.

pricing_model

Defines how the recurring charges for the subscription is calculated.
enumerated string, default=flat_fee

Possible values are

flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.

free_quantity

Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
integer, default=0, min=0

setup_cost

One-time setup fee charged as part of the first invoice.
optional, in cents, min=1

status

The plan state.
enumerated string, default=active

Possible values are

activeNew subscriptions can be created with the plan.archivedNo new subscriptions allowed for the plan. Existing subscriptions on this plan will remain as-is and can be migrated to another active plan if required.

archived_at

Time at which the plan was moved to archived status.
optional, timestamp(UTC) in seconds

billing_cycles

The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
optional, integer, min=1

redirect_url

The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
optional, string, max chars=500

enabled_in_hosted_pages

If true, allow checkout through plan specific hosted page URL for this plan.
boolean, default=true

enabled_in_portal

If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
boolean, default=true

addon_applicability

Indicates if all or only some addons are applicable with the plan.
enumerated string, default=all

Possible values are

allAll addons are applicable with this plan.restrictedOnly addons marked as 'applicable_addons' are applicable with the plan.

tax_code

The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's AvaTax for Sales integration.
optional, string, max chars=50

taxjar_product_code

The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
optional, string, max chars=50

avalara_sale_type

Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction is for an item that is subject to vendor use tax.

avalara_transaction_type

Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

avalara_service_type

Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

sku

The field is used as Product name/code in your third party accounting application. Chargebee will use it as an alternate name in your accounting application.
optional, string, max chars=100

accounting_code

This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100

accounting_category1

The name of the category of your product in Xero. If you've integrated with QuickBooks, this will be the "Class". Use the format "<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100

accounting_category2

The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100

is_shippable

If enabled, charges for this plan/addon will be added to orders.
optional, boolean, default=false

shipping_frequency_period

Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, integer, min=1

shipping_frequency_period_unit

Defines the shipping frequency in association with shipping period.
optional, enumerated string

Possible values are

yearShip based on year(s).monthShip based on month(s).weekShip based on week(s).dayShip based on day(s).

resource_version

Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long

updated_at

Timestamp indicating when this plan was last updated. This attribute will be present only if the resource has been updated after 2016-11-09.
optional, timestamp(UTC) in seconds

giftable

Specifies if the plan should be gifted or not.
boolean, default=false

claim_url

The url to redirect on successful claim. Eg: https://yoursite.com/claim_success.html?plan=basic.
optional, string, max chars=500

free_quantity_in_decimal

The quantity of the plan that is available free-of-charge, represented in decimal. When a subscription is created for this plan or when the plan of a subscription is changed to this one, only the quantity above this number is charged for. Applicable for quantity-based plans and only when multi-decimal pricing is enabled.
optional, string, max chars=33

price_in_decimal

The price of the plan when the pricing_model is flat_fee. When the pricing model is per_unit, it is the price per unit quantity of the item. Not applicable for the other pricing models. The value is in decimal and in major units of the currency. Also, this is only applicable when multi-decimal pricing is enabled.
optional, string, max chars=33

invoice_notes

Invoice Notes for this resource.
optional, string, max chars=2000

taxable

Specifies if the plan should be taxed or not.
optional, boolean, default=true

tax_profile_id

Tax profile of the plan.
optional, string, max chars=50

meta_data

A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject

show_description_in_invoices

Whether the plan description should be shown on invoice PDFs. If this Boolean is changed, only invoices generated (or regenerated) after the change are affected; past invoices are not.
optional, boolean, default=false

show_description_in_quotes

Whether the plan description should be shown on quote PDFs. If this Boolean is changed, only quotes created after the change are affected; past quotes are not.
optional, boolean, default=false

tiers
Show attributes[+]

List of tiers for this plan(applicable only if it is tiered/volume/stairtstep pricing.
optional, list of tier

Tier attributes

starting_unit

The lower limit of a range of units for the tier.
integer, min=1

ending_unit

The upper limit of a range of units for the tier.
optional, integer

price

The per-unit price for the tier when the pricing_model is tiered or volume; the total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.
in cents, default=0, min=0

starting_unit_in_decimal

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.
optional, string, max chars=33

ending_unit_in_decimal

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.
optional, string, max chars=33

price_in_decimal

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 addon. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33

applicable_addons
Show attributes[+]

List of addons applicable with this plan.
optional, list of applicable_addon

Applicable addon attributes

id

Identifier of the addon appplicable to the plan.
string, max chars=100

attached_addons
Show attributes[+]

Indicates if the addon is attached with the plan as mandatory or recommended.
optional, list of attached_addon

Attached addon attributes

id

Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
string, max chars=100

quantity

Quantity of the addon. Applicable only for the quantity based addons.
integer, min=1

billing_cycles

The number of billing cycles this addon will be attached to the plan.
optional, integer, min=1

type

Specifies attachment type of the addon to the plan.
enumerated string

Possible values are

recommendedAddon will be charged with this plan unless specifically removed.mandatoryAddon will be always charged with this plan.

quantity_in_decimal

The decimal representation of the quantity of the addon. Returned for quantity-based addons when multi-decimal pricing is enabled.
optional, string, max chars=33

event_based_addons
Show attributes[+]

List of addons that will be charged on occurrence of specific event on subscribing to the plan.
optional, list of event_based_addon

Event based addon attributes

id

Identifier of the addon. Multiple addons can be passed.
string, max chars=100

quantity

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
integer, min=1

on_event

Event on which the addon will be charged.
enumerated string

Possible values are

subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.contract_terminationAddon will be charged on contract termination.

charge_once

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
boolean, default=true

quantity_in_decimal

The decimal representation of the quantity of the addon. Returned for quantity-based addons when multi-decimal pricing is enabled.
optional, string, max chars=33

Create a new plan.

Sample Request

curl  https://{site}.chargebee.com/api/v2/plans \
     -u {site_api_key}:\
     -d id="silver" \
     -d name="Silver" \
     -d invoice_name="sample plan" \
     -d price=5000

copy

curl  https://{site}.chargebee.com/api/v2/plans \
     -u {site_api_key}:\
     -d id="silver" \
     -d name="Silver" \
     -d invoice_name="sample plan" \
     -d price=5000

# creates a plan with addon applicability factor.
curl  https://{site}.chargebee.com/api/v2/plans \
     -u {site_api_key}:\
     -d id="gold" \
     -d name="Gold" \
     -d price=500 \
     -d addon_applicability="restricted" \
     -d applicable_addons[id][0]="sub_ssl"

# creates a plan with tiered pricing model.
curl  https://{site}.chargebee.com/api/v2/plans \
     -u {site_api_key}:\
     -d id="tiered_plan" \
     -d name="Tiered Plan" \
     -d invoice_name="sample Tiered Plan" \
     -d pricing_model="tiered" \
     -d tiers[starting_unit][0]=1 \
     -d tiers[ending_unit][0]=10 \
     -d tiers[price][0]=100 \
     -d tiers[starting_unit][1]=11 \
     -d tiers[ending_unit][1]=20 \
     -d tiers[price][1]=300 \
     -d tiers[starting_unit][2]=21 \
     -d tiers[price][2]=500

# creates a plan with trial period.
curl  https://{site}.chargebee.com/api/v2/plans \
     -u {site_api_key}:\
     -d id="trial_plan" \
     -d name="Trial Plan" \
     -d invoice_name="sample trial plan" \
     -d trial_period_unit="day" \
     -d trial_period=14 \
     -d pricing_model="per_unit" \
     -d price=100

Sample Response [ JSON ]

{"plan": {
    "addon_applicability": "all",
    "charge_model": "flat_fee",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "silver",
    "invoice_name": "sample plan",
    "is_shippable": false,
    "name": "Silver",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 5000,
    "pricing_model": "flat_fee",
    "resource_version": 1517505797000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "updated_at": 1517505797
}}

{"plan": {
    "addon_applicability": "restricted",
    "applicable_addons": [
        {
            "id": "sub_ssl",
            "object": "applicable_addon"
        },
        {..}
    ],
    "charge_model": "flat_fee",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "gold",
    "is_shippable": false,
    "name": "Gold",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 500,
    "pricing_model": "flat_fee",
    "resource_version": 1517505800000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "updated_at": 1517505800
}}

{"plan": {
    "addon_applicability": "all",
    "charge_model": "tiered",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "tiered_plan",
    "invoice_name": "sample Tiered Plan",
    "is_shippable": false,
    "name": "Tiered Plan",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "pricing_model": "tiered",
    "resource_version": 1517505798000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "tiers": [
        {
            "ending_unit": 10,
            "object": "tier",
            "price": 100,
            "starting_unit": 1
        },
        {..}
    ],
    "updated_at": 1517505798
}}

{"plan": {
    "addon_applicability": "all",
    "charge_model": "per_unit",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "trial_plan",
    "invoice_name": "sample trial plan",
    "is_shippable": false,
    "name": "Trial Plan",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 100,
    "pricing_model": "per_unit",
    "resource_version": 1517505799000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "trial_period": 14,
    "trial_period_unit": "day",
    "updated_at": 1517505799
}}

URL Format POST

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

id

A unique ID for your system to identify the plan.
required, string, max chars=100

name

The display name used in web interface for identifying the plan.
required, string, max chars=50

invoice_name

Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100

description

Description about the plan to show in the hosted pages & customer portal.
optional, string, max chars=500

trial_period

The free time window for your customer to try your product.
optional, integer, min=1

trial_period_unit

Time unit for the trial period.
optional, enumerated string

Possible values are

dayIn days.monthIn months.

period

Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
optional, integer, default=1, min=1

period_unit

Defines billing frequency in association with billing period.
optional, enumerated string, default=month

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

setup_cost

One-time setup fee charged as part of the first invoice.
optional, in cents, min=1

price

The price of the plan.
optional, in cents, min=0

price_in_decimal

The price of the plan when the pricing_model is flat_fee. When the pricing model is per_unit, it is the price per unit quantity of the plan. Not applicable for the other pricing models. The value is in decimal and in major units of the currency. Also, this is only applicable when multi-decimal pricing is enabled. .
optional, string, max chars=33

currency_code

The currency code (ISO 4217 format) of the plan.
required if Multicurrency is enabled, string, max chars=3

billing_cycles

The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
optional, integer, min=1

pricing_model

Defines how the recurring charges for the subscription is calculated.
optional, enumerated string, default=flat_fee

Possible values are

free_quantity

Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
optional, integer, default=0, min=0

free_quantity_in_decimal

addon_applicability

Indicates if all or only some addons are applicable with the plan.
optional, enumerated string, default=all

Possible values are

allAll addons are applicable with this plan.restrictedOnly addons marked as 'applicable_addons' are applicable with the plan.

redirect_url

The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
optional, string, max chars=500

enabled_in_hosted_pages

If true, allow checkout through plan specific hosted page URL for this plan.
optional, boolean, default=true

enabled_in_portal

If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
optional, boolean, default=true

taxable

Specifies if the plan should be taxed or not.
optional, boolean, default=true

tax_profile_id

Tax profile of the plan.
optional, string, max chars=50

tax_code

The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's AvaTax for Sales integration.
optional, string, max chars=50

taxjar_product_code

The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
optional, string, max chars=50

avalara_sale_type

Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

avalara_transaction_type

Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

avalara_service_type

sku

The field is used as Product name/code in your third party accounting application. Chargebee will use it as an alternate name in your accounting application.
optional, string, max chars=100

accounting_code

This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100

accounting_category1

accounting_category2

The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100

is_shippable

If enabled, charges for this plan/addon will be added to orders.
optional, boolean, default=false

shipping_frequency_period

Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, integer, min=1

shipping_frequency_period_unit

Defines the shipping frequency in association with shipping period.
optional, enumerated string

Possible values are

yearShip based on year(s).monthShip based on month(s).weekShip based on week(s).dayShip based on day(s).

invoice_notes

Invoice Notes for this resource.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject

show_description_in_invoices

show_description_in_quotes

Whether the plan description should be shown on quote PDFs. If this Boolean is changed, only quotes created after the change are affected; past quotes are not.
optional, boolean, default=false

giftable

Specifies if the plan should be gifted or not.
optional, boolean, default=false

status

The plan state.
optional, enumerated string, default=active

Possible values are

claim_url

The url to redirect on successful claim. Eg: https://yoursite.com/claim_success.html?plan=basic.
optional, string, max chars=500

tiers

Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]

tiers[starting_unit][0..n]

The lower limit of a range of units for the tier.
optional, integer, min=1

tiers[ending_unit][0..n]

The upper limit of a range of units for the tier.
optional, integer

tiers[price][0..n]

tiers[starting_unit_in_decimal][0..n]

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. Applicable only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled. .
optional, string, max chars=33

tiers[ending_unit_in_decimal][0..n]

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. Applicable only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled. .
optional, string, max chars=33

tiers[price_in_decimal][0..n]

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 plan. The value is in major units of the currency. Applicable when the plan is quantity-based and multi-decimal pricing is enabled. .
optional, string, max chars=33

applicable_addons

Parameters for applicable_addons. Multiple applicable_addons can be passed by specifying unique indices.
pass parameters as applicable_addons[<param name>][<idx:0..n>]

applicable_addons[id][0..n]

Identifier of the addon appplicable to the plan.
optional, string, max chars=100

event_based_addons

Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.
pass parameters as event_based_addons[<param name>][<idx:0..n>]

event_based_addons[id][0..n]

Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100

event_based_addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1

event_based_addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon purchased. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled. .
optional, string, max chars=33

event_based_addons[on_event][0..n]

Event on which the addon will be charged.
optional, enumerated string

Possible values are

event_based_addons[charge_once][0..n]

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true

attached_addons

Parameters for attached_addons. Multiple attached_addons can be passed by specifying unique indices.
pass parameters as attached_addons[<param name>][<idx:0..n>]

attached_addons[id][0..n]

Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
optional, string, max chars=100

attached_addons[quantity][0..n]

Quantity of the addon. Applicable only for the quantity based addons.
optional, integer, min=1

attached_addons[quantity_in_decimal][0..n]

The default quantity of the addon to be attached when the quantity is not specified while creating/ updating the subscription. The value is in decimal. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled. .
optional, string, max chars=33

attached_addons[billing_cycles][0..n]

The number of billing cycles this addon will be attached to the plan.
optional, integer, min=1

attached_addons[type][0..n]

Specifies attachment type of the addon to the plan.
optional, enumerated string

Possible values are

recommendedAddon will be charged with this plan unless specifically removed.mandatoryAddon will be always charged with this plan.

plan

Resource object representing plan.
always returned

When updating plans that are already linked to an invoice or a subscription, you can only update the following parameters:

name
invoice_name
setup_cost
price
trial_period
trial_period_unit
redirect_url
enabled_in_hosted_pages
meta_data

Sample Request

curl  https://{site}.chargebee.com/api/v2/plans/cb_trial \
     -u {site_api_key}:\
     -d invoice_name="sample plan"

copy

curl  https://{site}.chargebee.com/api/v2/plans/cb_trial \
     -u {site_api_key}:\
     -d invoice_name="sample plan"

Sample Response [ JSON ]

{"plan": {
    "addon_applicability": "all",
    "charge_model": "flat_fee",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "cb_trial",
    "invoice_name": "sample plan",
    "is_shippable": false,
    "name": "CB Trial",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 0,
    "pricing_model": "flat_fee",
    "resource_version": 1517505805000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "updated_at": 1517505805
}}

URL Format POST

https://{site}.chargebee.com/api/v2/plans/{plan_id}

name

The display name used in web interface for identifying the plan.
optional, string, max chars=50

invoice_name

Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100

description

Description about the plan to show in the hosted pages & customer portal.
optional, string, max chars=500

trial_period

The free time window for your customer to try your product. If zero is passed, the trial period will be removed.
optional, integer, min=0

trial_period_unit

Time unit for the trial period.
optional, enumerated string

Possible values are

dayIn days.monthIn months.

period

Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
optional, integer, min=1

period_unit

Defines billing frequency in association with billing period.
optional, enumerated string

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

setup_cost

One-time setup fee charged as part of the first invoice.
optional, in cents, min=1

price

The price of the plan.
optional, in cents, min=0

price_in_decimal

currency_code

The currency code (ISO 4217 format) of the plan. Applicable if Multicurrency is enabled.
optional, string, max chars=3

billing_cycles

The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
optional, integer, min=1

pricing_model

Defines how the recurring charges for the subscription is calculated.
optional, enumerated string

Possible values are

free_quantity

Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
optional, integer, min=0

free_quantity_in_decimal

addon_applicability

Indicates if all or only some addons are applicable with the plan.
optional, enumerated string

Possible values are

allAll addons are applicable with this plan.restrictedOnly addons marked as 'applicable_addons' are applicable with the plan.

redirect_url

The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
optional, string, max chars=500

enabled_in_hosted_pages

If true, allow checkout through plan specific hosted page URL for this plan.
optional, boolean

enabled_in_portal

If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
optional, boolean

taxable

Specifies if the plan should be taxed or not.
optional, boolean

tax_profile_id

Tax profile of the plan.
optional, string, max chars=50

tax_code

The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's AvaTax for Sales integration.
optional, string, max chars=50

taxjar_product_code

The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
optional, string, max chars=50

avalara_sale_type

Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

avalara_transaction_type

Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

avalara_service_type

sku

The field is used as Product name/code in your third party accounting application. Chargebee will use it as an alternate name in your accounting application.
optional, string, max chars=100

accounting_code

This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100

accounting_category1

accounting_category2

The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100

is_shippable

If enabled, charges for this plan/addon will be added to orders.
optional, boolean

shipping_frequency_period

Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, integer, min=1

shipping_frequency_period_unit

Defines the shipping frequency in association with shipping period.
optional, enumerated string

Possible values are

yearShip based on year(s).monthShip based on month(s).weekShip based on week(s).dayShip based on day(s).

invoice_notes

Invoice Notes for this resource.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject

show_description_in_invoices

show_description_in_quotes

Whether the plan description should be shown on quote PDFs. If this Boolean is changed, only quotes created after the change are affected; past quotes are not.
optional, boolean

tiers

Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]

tiers[starting_unit][0..n]

The lower limit of a range of units for the tier.
optional, integer, min=1

tiers[ending_unit][0..n]

The upper limit of a range of units for the tier.
optional, integer

tiers[price][0..n]

tiers[starting_unit_in_decimal][0..n]

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. Applicable only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled. .
optional, string, max chars=33

tiers[ending_unit_in_decimal][0..n]

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. Applicable only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled. .
optional, string, max chars=33

tiers[price_in_decimal][0..n]

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 plan. The value is in major units of the currency. Applicable when the plan is quantity-based and multi-decimal pricing is enabled. .
optional, string, max chars=33

applicable_addons

Parameters for applicable_addons. Multiple applicable_addons can be passed by specifying unique indices.
pass parameters as applicable_addons[<param name>][<idx:0..n>]

applicable_addons[id][0..n]

Identifier of the addon appplicable to the plan.
optional, string, max chars=100

event_based_addons

Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.
pass parameters as event_based_addons[<param name>][<idx:0..n>]

event_based_addons[id][0..n]

Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100

event_based_addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1

event_based_addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon purchased. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled. .
optional, string, max chars=33

event_based_addons[on_event][0..n]

Event on which the addon will be charged.
optional, enumerated string

Possible values are

event_based_addons[charge_once][0..n]

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean

attached_addons

Parameters for attached_addons. Multiple attached_addons can be passed by specifying unique indices.
pass parameters as attached_addons[<param name>][<idx:0..n>]

attached_addons[id][0..n]

Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
optional, string, max chars=100

attached_addons[quantity][0..n]

Quantity of the addon. Applicable only for the quantity based addons.
optional, integer, min=1

attached_addons[quantity_in_decimal][0..n]

attached_addons[billing_cycles][0..n]

The number of billing cycles this addon will be attached to the plan.
optional, integer, min=1

attached_addons[type][0..n]

Specifies attachment type of the addon to the plan.
optional, enumerated string

Possible values are

recommendedAddon will be charged with this plan unless specifically removed.mandatoryAddon will be always charged with this plan.

plan

Resource object representing plan.
always returned

This API fetches all the active and archived plans. If the limit parameter is not set, it will return upto 10 plans. .

Sample Request

curl  https://{site}.chargebee.com/api/v2/plans \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode status[is]="active"

copy

curl  https://{site}.chargebee.com/api/v2/plans \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode status[is]="active"

Sample Response [ JSON ]

{
    "list": [
        {"plan": {
            "addon_applicability": "all",
            "charge_model": "tiered",
            "currency_code": "USD",
            "enabled_in_hosted_pages": true,
            "enabled_in_portal": true,
            "free_quantity": 0,
            "giftable": false,
            "id": "tiered_plan",
            "invoice_name": "sample Tiered Plan",
            "is_shippable": false,
            "name": "Tiered Plan",
            "object": "plan",
            "period": 1,
            "period_unit": "month",
            "pricing_model": "tiered",
            "resource_version": 1517505798000,
            "show_description_in_invoices": false,
            "show_description_in_quotes": false,
            "status": "active",
            "taxable": true,
            "tiers": [
                {
                    "ending_unit": 10,
                    "object": "tier",
                    "price": 100,
                    "starting_unit": 1
                },
                {..}
            ],
            "updated_at": 1517505798
        }},
        {..}
    ],
    "next_offset": "[\"100\",\"149000010672\"]"
}

URL Format GET

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

limit

The number of resources to be returned.
optional, integer, default=10, min=1, max=100

offset

Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
optional, string, max chars=1000

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

A unique ID for your system to identify the plan.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "Enterprise"
optional, string filter

name[<operator>]

The display name used in web interface for identifying the plan.
Supported operators : is, is_not, starts_with, in, not_in

Example → name[is] = "plan_enterprise"
optional, string filter

price[<operator>]

The price of the plan.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → price[lte] = "1200"
optional, in cents filter

period[<operator>]

Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → period[is] = "3"
optional, integer filter

period_unit[<operator>]

Defines billing frequency in association with billing period. Possible values are : day, week, month, year.
Supported operators : is, is_not, in, not_in

Example → period_unit[is] = "month"
optional, enumerated string filter

trial_period[<operator>]

The free time window for your customer to try your product.
Supported operators : is, is_not, lt, lte, gt, gte, between, is_present

Example → trial_period[is] = "14"
optional, integer filter

trial_period_unit[<operator>]

Time unit for the trial period. Possible values are : day, month.
Supported operators : is, is_not, in, not_in

Example → trial_period_unit[is] = "day"
optional, enumerated string filter

addon_applicability[<operator>]

Indicates if all or only some addons are applicable with the plan. Possible values are : all, restricted.
Supported operators : is, is_not, in, not_in

Example → addon_applicability[is] = "all"
optional, enumerated string filter

giftable[<operator>]

Specifies if the plan should be gifted or not. Possible values are : true, false
Supported operators : is

Example → giftable[is] = "true"
optional, boolean filter

pricing_model[<operator>]

Defines how the recurring charges for the subscription is calculated. Possible values are : flat_fee, per_unit, tiered, volume, stairstep.
Supported operators : is, is_not, in, not_in

Example → pricing_model[is] = "flat_fee"
optional, enumerated string filter

status[<operator>]

The plan state. Possible values are : active, archived.
Supported operators : is, is_not, in, not_in

Example → status[is_not] = "active"
optional, enumerated string filter

updated_at[<operator>]

To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-11-09.
Supported operators : after, before, on, between

Example → updated_at[before] = "1243545465"
optional, timestamp(UTC) in seconds filter

currency_code[<operator>]

The currency code (ISO 4217 format) of the plan.
Supported operators : is, is_not, starts_with, in, not_in

Example → currency_code[is] = "USD"
optional, string filter

plan

Resource object representing plan.
always returned

next_offset

This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000

Retrieve a specific plan using the id.

Sample Request

curl  https://{site}.chargebee.com/api/v2/plans/sub_free \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/plans/sub_free \
     -u {site_api_key}:

Sample Response [ JSON ]

{"plan": {
    "addon_applicability": "all",
    "charge_model": "per_unit",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "sub_free",
    "is_shippable": false,
    "name": "sub_Free",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 0,
    "pricing_model": "per_unit",
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true
}}

URL Format GET

https://{site}.chargebee.com/api/v2/plans/{plan_id}

plan

Resource object representing plan.
always returned

Sample admin console URL

https://{site}.chargebee.com/admin-console/plans/123x

When a plan that already has subscriptions/invoices linked to it is deleted, it does not get completely purged but is instead moved to "Archived" state. No other subscriptions can use this plan but subscriptions already on it will continue to renew. Once a plan has been archived, it cannot be edited or used again and the plan cannot be un-archived.

If no subscriptions or invoices are linked to a plan, the plan will be permanently deleted from your Chargebee site. This action cannot be undone.

If a plan that is an applicable item for a coupon is deleted, then the plan will be removed from that coupon's list of applicable items.

Archiving a plan will not affect coupons in anyway.

Sample Request

curl  https://{site}.chargebee.com/api/v2/plans/demo_plan/delete \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/plans/demo_plan/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"plan": {
    "addon_applicability": "all",
    "charge_model": "flat_fee",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "demo_plan",
    "invoice_name": "demo plan",
    "is_shippable": false,
    "name": "Demo plan",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 5000,
    "pricing_model": "flat_fee",
    "resource_version": 1600968201320,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "deleted",
    "taxable": true,
    "updated_at": 1600968201
}}

URL Format POST

https://{site}.chargebee.com/api/v2/plans/{plan_id}/delete

plan

Resource object representing plan.
always returned

Creates a plan in this site by copying its configurations from another site. Copying of archived plans is not supported.

Note: The attribute tax_profile_id is not copied. In effect, if the plan is taxable, it will be mapped to the Primary tax profile.

This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.

Sample Request

curl  https://{site}.chargebee.com/api/v2/plans/copy \
     -u {site_api_key}:\
     -d from_site="merchant-test" \
     -d id_at_from_site="silver-plan-new"

copy

curl  https://{site}.chargebee.com/api/v2/plans/copy \
     -u {site_api_key}:\
     -d from_site="merchant-test" \
     -d id_at_from_site="silver-plan-new"

Sample Response [ JSON ]

{"plan": {
    "addon_applicability": "all",
    "charge_model": "flat_fee",
    "currency_code": "USD",
    "description": "200 invoices per month included.",
    "enabled_in_hosted_pages": false,
    "enabled_in_portal": false,
    "free_quantity": 0,
    "giftable": false,
    "id": "silver-plan-new",
    "invoice_name": "Silver Plan",
    "is_shippable": false,
    "meta_data": {
        "allowed_invoices_count": 200,
        "feature_sets": [
            {
                "base_feature_set": "standard-plan-feb-2016",
                "id": "silver-plan-new"
            },
            {..}
        ],
        "invoices_count_threshold_rules": [
            {
                "action": "add_addon_for_overage_invoices",
                "addon_id": "additional_overage_invoices_one_time",
                "extra_value_from": 1,
                "extra_value_to": -1,
                "order": 1
            },
            {..}
        ]
    },
    "name": "Silver Plan New",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 7900,
    "pricing_model": "flat_fee",
    "resource_version": 1517505796000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "trial_period": 1,
    "trial_period_unit": "month",
    "updated_at": 1517505796
}}

URL Format POST

https://{site}.chargebee.com/api/v2/plans/copy

from_site

Your Chargebee site name having the plan to be copied.
Note: Unless you are copying from a twin site (acme & acme-test are twin sites), please contact support@chargebee.com to have this white-listed.
required, string, max chars=50

id_at_from_site

Id of the plan to be copied. The new plan created in this site will have the same Id.
required, string, max chars=100

id

Id of copied plan in this site.
optional, string, max chars=100

for_site_merging

If copy action is performed as part of Chargebee site merge action, pass the value as true.
optional, boolean, default=false

plan

Resource object representing plan.
always returned

Unarchives a specific plan using the id.

Sample Request

curl  https://{site}.chargebee.com/api/v2/plans/archieved_plan/unarchive \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/plans/archieved_plan/unarchive \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"plan": {
    "addon_applicability": "all",
    "charge_model": "flat_fee",
    "currency_code": "USD",
    "enabled_in_hosted_pages": true,
    "enabled_in_portal": true,
    "free_quantity": 0,
    "giftable": false,
    "id": "archieved_plan",
    "is_shippable": false,
    "name": "Archieved Plan",
    "object": "plan",
    "period": 1,
    "period_unit": "month",
    "price": 0,
    "pricing_model": "flat_fee",
    "resource_version": 1517505804000,
    "show_description_in_invoices": false,
    "show_description_in_quotes": false,
    "status": "active",
    "taxable": true,
    "updated_at": 1517505804
}}

URL Format POST

https://{site}.chargebee.com/api/v2/plans/{plan_id}/unarchive

plan

Resource object representing plan.
always returned

Sample plan [ JSON ]

API Index URL GET

Plan attributes

Create a plan¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update a plan¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List plans¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Retrieve a plan¶

Sample Response [ JSON ]

URL Format GET

Returns

Sample admin console URL

Delete a plan¶

Sample Response [ JSON ]

URL Format POST

Returns

Copy a plan¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Unarchive a plan¶

Sample Response [ JSON ]

URL Format POST

Returns