Settings
API Version
Product Catalog
Library

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

Model Class

 

      Plan attributes
      
 
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
 
 
dayCharge based on day(s)weekCharge based on week(s)monthCharge based on month(s)yearCharge based on year(s)
 
 Show all values[+]
 
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 daysmonthIn months
 
 Show all values[+]
 
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 basisper_unitCharge the price for each unit of the plan for the subscription on recurring basis.
 
 Show all values[+]
 
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.
 
 Show all values[+]
 
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. 
 
 
 
Event types
 

      This is a list of the event types we currently support. We will continue
      to add more events moving forward. All events follow a uniform pattern -
      <resource>_<event_name>. The resources that will be
      present in the event content are provided beneath each event type's
      description.
    
 
Note: If consolidated invoicing is enabled, the
      attributes invoice.subscription_id and
      credit_note.subscription_id should not be used
      (as it will not be present if the invoice / credit note has lines from
      multiple subscriptions). Instead to know the related subscriptions,
      their line_items' subscription_id attribute should be referred.
    
 
 
id id
 

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

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

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

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

          optional, in cents, min=0
 The price of the plan. The unit depends on the type of currency. 
 
period period
 

          integer, default=1, min=1
 Defines billing frequency. Example: to bill customer every 3 months, provide "3" here. 
 
period_unit 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)
 
 Show all values[+]
trial_period trial_period
 

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

          optional, enumerated string
 Time unit for the trial period. 
 
Possible values are
 
 
dayIn daysmonthIn months
 
 Show all values[+]
charge_model 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 basisper_unitCharge the price for each unit of the plan for the subscription on recurring basis.
 
 Show all values[+]
free_quantity 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 setup_cost
 

          optional, in cents, min=1
 One-time setup fee charged as part of the first invoice. 
 
status 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.
 
 Show all values[+]
archived_at archived_at
 

          optional, timestamp(UTC) in seconds
 Time at which the plan was moved to archived status. 
 
billing_cycles 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 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 enabled_in_hosted_pages
 

          boolean, default=true
 If true, allow checkout through plan specific hosted page URL for this plan. 
 
enabled_in_portal 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 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 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. 
 
 
 
Consent Fields for Plan
 
 
Custom Fields for Plan
 
  

      Create a plan
      
 
Idempotency Supported
 
 
This endpoint creates a new plan based on the plan Id and plan name.
  
Notes
 
 

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

    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
    
 
Method
 
 
Input Parameters
 
  
 
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
 
 
dayIn daysmonthIn months
 
 Show all values[+]
 
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)
 
 Show all values[+]
 
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 basisper_unitCharge the price for each unit of the plan for the subscription on recurring basis.
 
 Show all values[+]
 
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. 
 
 
    
 
Returns
 
plan  plan
 

      always returned 
 Resource object representing plan
 
Sample admin console URL
 

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

      Update a plan
      
 
Idempotency Supported
 
 
 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
    •  

  
Notes
 
 

        Sample Request
      
 
 
 
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 ]
 
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}
    
 
Method
 
 
Input Parameters
 
  
 
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
 
 
dayIn daysmonthIn months
 
 Show all values[+]
 
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)
 
 Show all values[+]
 
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 basisper_unitCharge the price for each unit of the plan for the subscription on recurring basis.
 
 Show all values[+]
 
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. 
 
 
    
 
Returns
 
plan  plan
 

      always returned 
 Resource object representing plan
 
Sample admin console URL
 

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

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

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

      copy
      
Click to Copy
 
 

    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
    
 
Method
 
 
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  plan
 

      always returned 
 Resource object representing plan
next_offset  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`.
 
Sample admin console URL
 

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

      Retrieve a plan
      
  
 
This endpoint retrieves a specific plan using the plan id.
  
Notes
 
 

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

      copy
      
Click to Copy
 
 

    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}
    
 
Method
 
  
   
 
    
 
Returns
 
plan  plan
 

      always returned 
 Resource object representing plan
 
Sample admin console URL
 

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

      Delete a plan
      
 
Idempotency Supported
 
 
 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. 
  
Notes
 
 

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

      copy
      
Click to Copy
 
 

    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
    
 
Method
 
  
   
 
    
 
Returns
 
plan  plan
 

      always returned 
 Resource object representing plan
 
Sample admin console URL
 

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