Plans

API Version

Product Catalog

Library

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

id

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

name

string, max chars=100
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=2000
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

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

charge_model

enumerated string
Defines how the subscription recurring charge for this plan should be calculated.

Possible values are

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

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 plan. Learn more.

id

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

name

string, max chars=100
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=2000
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

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

charge_model

enumerated string
Defines how the subscription recurring charge for this plan should be calculated.

Possible values are

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

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 plan. Learn more.

This endpoint creates a new plan based on the plan Id and plan name.

Sample Request

Only for Java

copy full code

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

copy

Click to Copy

Sample Response [ JSON ]

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

id[]

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

name[]

required, string, max chars=100
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=2000
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

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

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

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 plan. Learn more.

plan

always returned
Resource object representing 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

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

Sample Response [ JSON ]

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

name[]

optional, string, max chars=100
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=2000
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

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

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

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 plan. Learn more.

plan

always returned
Resource object representing plan

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

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/plans \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

copy

Click to Copy

Sample Response [ JSON ]

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

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.

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

This endpoint retrieves a specific plan using the plan id.

Sample Request

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

Sample Response [ JSON ]

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

plan

always returned
Resource object representing plan

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

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

Sample Response [ JSON ]

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

plan

always returned
Resource object representing plan

Sample plan [ JSON ]

API Index URL GET

Model Class

Plan attributes

Consent Fields for Plan

Custom Fields for Plan

Create a plan ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update a plan ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List plans ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a plan ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Delete a plan ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL