You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

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 ]

{ "id": "basic", "name": "Basic", "price": 900, "period": 1, "period_unit": "month", "trial_period": 1, "trial_period_unit": "month", "charge_model": "per_unit", "free_quantity": 0, "status": "active", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "object": "plan", "taxable": true }

API Index URL GET

https://{site}.chargebee.com/api/v1/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
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
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.
charge_model
Defines how the subscription recurring charge for this plan should be calculated.
enumerated string
Possible values are
flat_feeCharge a single price on recurring basis.per_unitCharge the price for each unit of the plan for the subscription on recurring basis.
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.deletedIndicates the plan has been deleted.
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
invoice_notes
Invoice Notes for this resource. Read More.
optional, string, max chars=1000
taxable
Specifies if the plan should be taxed or not.
optional, boolean, default=true
meta_data
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
Create a new plan.
Sample Request
curl  https://{site}.chargebee.com/api/v1/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/v1/plans \
     -u {site_api_key}: \
     -d id="silver" \
     -d name="Silver" \
     -d invoice_name="sample plan" \
     -d price="5000"

Sample Response [ JSON ]

{"plan": { "id": "silver", "name": "Silver", "invoice_name": "sample plan", "price": 5000, "period": 1, "period_unit": "month", "charge_model": "flat_fee", "free_quantity": 0, "status": "active", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "object": "plan", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v1/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
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
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
charge_model
Defines how the subscription recurring charge for this plan should be calculated.
optional, enumerated string
Possible values are
flat_feeCharge a single price on recurring basis.per_unitCharge the price for each unit of the plan for the subscription on recurring basis.
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
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
invoice_notes
Invoice Notes for this resource. Read More.
optional, string, max chars=1000
meta_data
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
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
Sample Request
curl  https://{site}.chargebee.com/api/v1/plans/basic \
     -u {site_api_key}: \
     -d invoice_name="sample plan"
copy
curl  https://{site}.chargebee.com/api/v1/plans/basic \
     -u {site_api_key}: \
     -d invoice_name="sample plan"

Sample Response [ JSON ]

{"plan": { "id": "basic", "name": "Basic", "invoice_name": "sample plan", "price": 900, "period": 1, "period_unit": "month", "trial_period": 1, "trial_period_unit": "month", "charge_model": "per_unit", "free_quantity": 0, "status": "active", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "object": "plan", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v1/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
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
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
charge_model
Defines how the subscription recurring charge for this plan should be calculated.
optional, enumerated string
Possible values are
flat_feeCharge a single price on recurring basis.per_unitCharge the price for each unit of the plan for the subscription on recurring basis.
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
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
invoice_notes
Invoice Notes for this resource. Read More.
optional, string, max chars=1000
meta_data
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
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/v1/plans \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v1/plans \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

Sample Response [ JSON ]

{ "list": [ {"plan": { "id": "basic", "name": "Basic", "invoice_name": "sample plan", "price": 900, "period": 1, "period_unit": "month", "trial_period": 1, "trial_period_unit": "month", "charge_model": "per_unit", "free_quantity": 0, "status": "active", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "object": "plan", "taxable": true }}, {..} ], "next_offset": "[\"900\",\"76000000157\"]" }

URL Format GET

https://{site}.chargebee.com/api/v1/plans
limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
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/v1/plans/basic \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/plans/basic \
     -u {site_api_key}:

Sample Response [ JSON ]

{"plan": { "id": "basic", "name": "Basic", "invoice_name": "sample plan", "price": 900, "period": 1, "period_unit": "month", "trial_period": 1, "trial_period_unit": "month", "charge_model": "per_unit", "free_quantity": 0, "status": "active", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "object": "plan", "taxable": true }}

URL Format GET

https://{site}.chargebee.com/api/v1/plans/{plan_id}
Resource object representing plan.
always returned

Sample admin console URL

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

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/v1/plans/silver/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/plans/silver/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"plan": { "id": "silver", "name": "Silver", "invoice_name": "sample plan", "price": 5000, "period": 1, "period_unit": "month", "charge_model": "flat_fee", "free_quantity": 0, "status": "deleted", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "object": "plan", "taxable": true }}

URL Format POST

https://{site}.chargebee.com/api/v1/plans/{plan_id}/delete
Resource object representing plan.
always returned