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

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 ]

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

API Index URL GET

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

Plan attributes

id
string, max chars=100
A unique ID for your system to identify the plan.
name
string, max chars=50
The display name used in web interface for identifying the plan.
invoice_name
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
description
optional, string, max chars=500
Description about the plan to show in the hosted pages & customer portal.
price
optional, in cents, min=0
The price of the plan. The unit depends on the type of currency.
period
integer, default=1, min=1
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
period_unit
enumerated string, default=month
Defines billing frequency in association with billing period.
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
optional, integer, min=1
The free time window for your customer to try your product.
trial_period_unit
optional, enumerated string
Time unit for the trial period.
Possible values are
dayIn days.monthIn months.
charge_model
enumerated string
Defines how the subscription recurring charge for this plan should be calculated.
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
integer, default=0, min=0
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
setup_cost
optional, in cents, min=1
One-time setup fee charged as part of the first invoice.
status
enumerated string, default=active
The plan state.
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
optional, timestamp(UTC) in seconds
Time at which the plan was moved to archived status.
billing_cycles
optional, integer, min=1
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
redirect_url
optional, string, max chars=500
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
enabled_in_hosted_pages
boolean, default=true
If true, allow checkout through plan specific hosted page URL for this plan.
enabled_in_portal
boolean, default=true
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
invoice_notes
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
taxable
optional, boolean, default=true
Specifies if the plan should be taxed or not.
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.

Create a plan

This endpoint creates a new plan based on the plan Id and plan name.
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 ]

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

URL Format POST

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

Input Parameters

id
required, string, max chars=100
A unique ID for your system to identify the plan.
name
required, string, max chars=50
The display name used in web interface for identifying the plan.
invoice_name
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
description
optional, string, max chars=500
Description about the plan to show in the hosted pages & customer portal.
trial_period
optional, integer, min=1
The free time window for your customer to try your product.
trial_period_unit
optional, enumerated string
Time unit for the trial period.
Possible values are
dayIn days.monthIn months.
period
optional, integer, default=1, min=1
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
period_unit
optional, enumerated string, default=month
Defines billing frequency in association with billing period.
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
optional, in cents, min=1
One-time setup fee charged as part of the first invoice.
price
optional, in cents, min=0
The price of the plan. The unit depends on the type of currency.
billing_cycles
optional, integer, min=1
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
charge_model
optional, enumerated string
Defines how the subscription recurring charge for this plan should be calculated.
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
optional, integer, default=0, min=0
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
redirect_url
optional, string, max chars=500
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
enabled_in_hosted_pages
optional, boolean, default=true
If true, allow checkout through plan specific hosted page URL for this plan.
enabled_in_portal
optional, boolean, default=true
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
taxable
optional, boolean, default=true
Specifies if the plan should be taxed or not.
invoice_notes
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.

Returns

plan
always returned
Resource object representing plan.

Update a plan

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/cb_trial \
     -u {site_api_key}:\
     -d invoice_name="sample plan"
copy
curl  https://{site}.chargebee.com/api/v1/plans/cb_trial \
     -u {site_api_key}:\
     -d invoice_name="sample plan"

Sample Response [ JSON ]

Show more...
{"plan": { "charge_model": "flat_fee", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "free_quantity": 0, "id": "cb_trial", "invoice_name": "sample plan", "name": "CB Trial", "object": "plan", "period": 1, "period_unit": "month", "price": 0, "status": "active", "taxable": true }}

URL Format POST

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

Input Parameters

name
optional, string, max chars=50
The display name used in web interface for identifying the plan.
invoice_name
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
description
optional, string, max chars=500
Description about the plan to show in the hosted pages & customer portal.
trial_period
optional, integer, min=0
The free time window for your customer to try your product. If zero is passed, the trial period will be removed.
trial_period_unit
optional, enumerated string
Time unit for the trial period.
Possible values are
dayIn days.monthIn months.
period
optional, integer, min=1
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
period_unit
optional, enumerated string
Defines billing frequency in association with billing period.
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
optional, in cents, min=1
One-time setup fee charged as part of the first invoice.
price
optional, in cents, min=0
The price of the plan. The unit depends on the type of currency.
billing_cycles
optional, integer, min=1
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
charge_model
optional, enumerated string
Defines how the subscription recurring charge for this plan should be calculated.
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
optional, integer, min=0
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
redirect_url
optional, string, max chars=500
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
enabled_in_hosted_pages
optional, boolean
If true, allow checkout through plan specific hosted page URL for this plan.
enabled_in_portal
optional, boolean
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
taxable
optional, boolean
Specifies if the plan should be taxed or not.
invoice_notes
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.

Returns

plan
always returned
Resource object representing plan.

List plans

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=3
copy
curl  https://{site}.chargebee.com/api/v1/plans \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

Sample Response [ JSON ]

Show more...
{ "list": [ {"plan": { "charge_model": "per_unit", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "free_quantity": 0, "id": "sub_free", "name": "sub_Free", "object": "plan", "period": 1, "period_unit": "month", "price": 0, "status": "active", "taxable": true }}, {..} ], "next_offset": "[\"1000\",\"132000000602\"]" }

URL Format GET

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

Input Parameters

limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
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.

Returns

plan
always returned
Resource object representing plan.
next_offset
optional, string, max chars=1000
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”.

Retrieve a plan

This endpoint retrieves a specific plan using the plan id.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/plans/sub_free \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/plans/sub_free \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"plan": { "charge_model": "per_unit", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "free_quantity": 0, "id": "sub_free", "name": "sub_Free", "object": "plan", "period": 1, "period_unit": "month", "price": 0, "status": "active", "taxable": true }}

URL Format GET

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

Returns

plan
always returned
Resource object representing plan.

Sample admin console URL

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

Delete a plan

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

Sample Response [ JSON ]

Show more...
{"plan": { "charge_model": "flat_fee", "enabled_in_hosted_pages": true, "enabled_in_portal": true, "free_quantity": 0, "id": "demo_plan", "invoice_name": "demo plan", "name": "Demo plan", "object": "plan", "period": 1, "period_unit": "month", "price": 5000, "status": "deleted", "taxable": true }}

URL Format POST

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

Returns

plan
always returned
Resource object representing plan.