Settings
API Version
Product Catalog
Library

Addons

Addons are additional charges applied to a subscription apart from the base plan charge. The addons can be recurring or non-recurring. A recurring addon included in a subscription is charged as per billing frequency of subscription. A non-recurring addon included in subscription will be charged immediately and only once. And a non-recurring addon is NOT pro-rated based on billing cycle, whereas a recurring addon is automatically pro-rated based on billing cycle.

Sample addon [ JSON ]

{ "charge_type": "recurring", "enabled_in_portal": true, "id": "sms_pack", "invoice_name": "sample data pack", "name": "Sms Pack", "object": "addon", "period": 1, "period_unit": "month", "price": 200, "status": "active", "taxable": true, "type": "on_off" }

API Index URL GET

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

Model Class

 

      Addon attributes
      
 
id
 

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

      string, max chars=100
 The display name used in web interface for identifying the addon. 
 
 
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 addon to show in the hosted pages & customer portal. This description will not be shown if multiple addons are added. 
 
 
type
 

      enumerated string
 Select "On-Off" to charge a flat fee or "Quantity" for unit based charges. 
 
Possible values are
 
 
on_offAddon that does not have any quantity associated  and can only be enabled or disabled. Example: On call support at $99 per month.quantityCharges this price for every unit of the addon. Example: 2 additional support agents at $10 each
 
 Show all values[+]
 
charge_type
 

      enumerated string, default=recurring
 Type of charge 
 
Possible values are
 
 
recurringCharges are automatically applied in sync with the billing frequency of subscription.non_recurringCharged immediately and only once every time it is applied.
 
 Show all values[+]
 
price
 

      optional, in cents, min=0
 Addon price is calculated based on the addon type and charge type. Learn more. The unit depends on the type of currency. 
 
 
period
 

      optional, integer, min=1
 Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon. 
 
 
period_unit
 

      enumerated string
 Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon 
 
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[+]
 
unit
 

      optional, string, max chars=30
 Specifies the type of quantity. For example, if the addon price is $10 and 'agent' is the unit of measure, the addon will be $10/agent. 
Applicable only for quantity type addons. 
 
 
status
 

      enumerated string, default=active
 Status of the addon 
 
Possible values are
 
 
activeOnly active addons can be applied to subscriptionsarchivedNo new associations with subscriptions are allowed. Existing associations for recurring addons remain as-is and can be removed if required.deletedIndicates the addon has been deleted.
 
 Show all values[+]
 
archived_at
 

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

      boolean, default=true
 If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal. 
 
 
proration_type
 

      optional, enumerated string, default=site_default
 null 
 
Possible values are
 
 
site_defaultpartial_termfull_term
 
 Show all values[+]
 
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 addon should be taxed or not 
 
 
meta_data
 

      optional, jsonobject
 A set of key-value pairs stored as additional information for the addon. 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 addon. 
 
name name
 

          string, max chars=100
 The display name used in web interface for identifying the addon. 
 
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 addon to show in the hosted pages & customer portal. This description will not be shown if multiple addons are added. 
 
type type
 

          enumerated string
 Select "On-Off" to charge a flat fee or "Quantity" for unit based charges. 
 
Possible values are
 
 
on_offAddon that does not have any quantity associated  and can only be enabled or disabled. Example: On call support at $99 per month.quantityCharges this price for every unit of the addon. Example: 2 additional support agents at $10 each
 
 Show all values[+]
charge_type charge_type
 

          enumerated string, default=recurring
 Type of charge 
 
Possible values are
 
 
recurringCharges are automatically applied in sync with the billing frequency of subscription.non_recurringCharged immediately and only once every time it is applied.
 
 Show all values[+]
price price
 

          optional, in cents, min=0
 Addon price is calculated based on the addon type and charge type. Learn more. The unit depends on the type of currency. 
 
period period
 

          optional, integer, min=1
 Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon. 
 
period_unit period_unit
 

          enumerated string
 Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon 
 
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[+]
unit unit
 

          optional, string, max chars=30
 Specifies the type of quantity. For example, if the addon price is $10 and 'agent' is the unit of measure, the addon will be $10/agent. 
Applicable only for quantity type addons. 
 
status status
 

          enumerated string, default=active
 Status of the addon 
 
Possible values are
 
 
activeOnly active addons can be applied to subscriptionsarchivedNo new associations with subscriptions are allowed. Existing associations for recurring addons remain as-is and can be removed if required.deletedIndicates the addon 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. 
 
enabled_in_portal enabled_in_portal
 

          boolean, default=true
 If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal. 
 
proration_type proration_type
 

          optional, enumerated string, default=site_default
 null 
 
Possible values are
 
 
site_defaultpartial_termfull_term
 
 Show all values[+]
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 addon should be taxed or not 
 
meta_data 
 

          optional, jsonobject
 A set of key-value pairs stored as additional information for the addon. Learn more. 
 
 
 
Consent Fields for Addon
 
 
Custom Fields for Addon
 
  

      Create an addon
      
 
Idempotency Supported
 
 
Create a new addon.
  
Notes
 
 

        Sample Request
      
 
 
 
curl  https://{site}.chargebee.com/api/v1/addons \
     -u {site_api_key}:\
     -d id="sms_pack" \
     -d name="Sms Pack" \
     -d invoice_name="sample data pack" \
     -d charge_type="RECURRING" \
     -d price=200 \
     -d period=1 \
     -d period_unit="MONTH" \
     -d type="ON_OFF"
 

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "addon": {
        "charge_type": "recurring",
        "enabled_in_portal": true,
        "id": "sms_pack",
        "invoice_name": "sample data pack",
        "name": "Sms Pack",
        "object": "addon",
        "period": 1,
        "period_unit": "month",
        "price": 200,
        "status": "active",
        "taxable": true,
        "type": "on_off"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v1/addons
    
 
Method
 
 
Input Parameters
 
  
 
id[]
 

      required, string, max chars=100 
 A unique ID for your system to identify the addon. 
 
name[]
 

      required, string, max chars=100 
 The display name used in web interface for identifying the addon. 
 
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 addon to show in the hosted pages & customer portal. This description will not be shown if multiple addons are added. 
 
charge_type[]
 

      required, enumerated string, default=recurring 
 Type of charge. 
Possible values are
 
 
recurringCharges are automatically applied in sync with the billing frequency of subscription.non_recurringCharged immediately and only once every time it is applied.
 
 Show all values[+]
 
price[]
 

      optional, in cents, min=0 
 Addon price is calculated based on the addon type and charge type. Learn more. The unit depends on the type of currency. 
 
period[]
 

      optional, integer, min=1 
 Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon. 
 
period_unit[]
 

      optional, enumerated string 
 Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon. 
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[+]
 
type[]
 

      optional, enumerated string 
 Select "On-Off" to charge a flat fee or "Quantity" for unit based charges. 
Possible values are
 
 
on_offAddon that does not have any quantity associated  and can only be enabled or disabled. Example: On call support at $99 per month.quantityCharges this price for every unit of the addon. Example: 2 additional support agents at $10 each
 
 Show all values[+]
 
unit[]
 

      optional, string, max chars=30 
 Specifies the type of quantity. For example, if the addon price is $10 and 'agent' is the unit of measure, the addon will be $10/agent. 
Applicable only for quantity type addons. 
 
enabled_in_portal[]
 

      optional, boolean, default=true 
 If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal. 
 
taxable[]
 

      optional, boolean, default=true 
 Specifies if the addon 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 addon. Learn more. 
 
proration_type[]
 

      optional, enumerated string, default=site_default 
 null 
Possible values are
 
 
site_defaultpartial_termfull_term
 
 Show all values[+]
 
 
    
 
Returns
 
addon  addon
 

      always returned 
 Resource object representing addon
 
Sample admin console URL
 

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

      Update an addon
      
 
Idempotency Supported
 
 
 When updating addons that already have an invoice or a subscription linked to it, you can only update the following parameters: 
 

     
 
  • name
    •  
 
  • invoice_name
    •  
 
  • price
    •  

  
Notes
 
 

        Sample Request
      
 
 
 
curl  https://{site}.chargebee.com/api/v1/addons/sub_reports \
     -u {site_api_key}:\
     -d invoice_name="sample data pack" \
     -d price=100
 

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "addon": {
        "charge_type": "recurring",
        "enabled_in_portal": true,
        "id": "sub_reports",
        "invoice_name": "sample data pack",
        "name": "sub_Reports",
        "object": "addon",
        "period": 1,
        "period_unit": "month",
        "price": 100,
        "status": "active",
        "taxable": true,
        "type": "on_off"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v1/addons/{addon-id}
    
 
Method
 
 
Input Parameters
 
  
 
name[]
 

      optional, string, max chars=100 
 The display name used in web interface for identifying the addon. 
 
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 addon to show in the hosted pages & customer portal. This description will not be shown if multiple addons are added. 
 
charge_type[]
 

      optional, enumerated string, default=recurring 
 Type of charge. 
Possible values are
 
 
recurringCharges are automatically applied in sync with the billing frequency of subscription.non_recurringCharged immediately and only once every time it is applied.
 
 Show all values[+]
 
price[]
 

      optional, in cents, min=0 
 Addon price is calculated based on the addon type and charge type. Learn more. The unit depends on the type of currency. 
 
period[]
 

      optional, integer, min=1 
 Applicable only for recurring-addons. Along with 'period_unit' decides the term-price of this addon. 
 
period_unit[]
 

      optional, enumerated string 
 Applicable only for recurring-addons. Along with 'period' decides the term-price of this addon. 
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[+]
 
type[]
 

      optional, enumerated string 
 Select "On-Off" to charge a flat fee or "Quantity" for unit based charges. 
Possible values are
 
 
on_offAddon that does not have any quantity associated  and can only be enabled or disabled. Example: On call support at $99 per month.quantityCharges this price for every unit of the addon. Example: 2 additional support agents at $10 each
 
 Show all values[+]
 
unit[]
 

      optional, string, max chars=30 
 Specifies the type of quantity. For example, if the addon price is $10 and 'agent' is the unit of measure, the addon will be $10/agent. 
Applicable only for quantity type addons. 
 
enabled_in_portal[]
 

      optional, boolean, default=true 
 If enabled, customers can select this addon using the 'Change Subscription' option in the customer portal. 
 
taxable[]
 

      optional, boolean, default=true 
 Specifies if the addon 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 addon. Learn more. 
 
proration_type[]
 

      optional, enumerated string, default=site_default 
 null 
Possible values are
 
 
site_defaultpartial_termfull_term
 
 Show all values[+]
 
 
    
 
Returns
 
addon  addon
 

      always returned 
 Resource object representing addon
 
Sample admin console URL
 

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

      List addons
      
  
 
List the addons. This returns all your current active and archived addons.
  
Notes
 
 

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

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "list": [
        {
            "addon": {
                "charge_type": "recurring",
                "enabled_in_portal": true,
                "id": "sms_pack",
                "invoice_name": "sample data pack",
                "name": "Sms Pack",
                "object": "addon",
                "period": 1,
                "period_unit": "month",
                "price": 200,
                "status": "active",
                "taxable": true,
                "type": "on_off"
            }
        },
        {..}
    ],
    "next_offset": "[\"133000000155\"]"
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v1/addons
    
 
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
 
addon  addon
 

      always returned 
 Resource object representing addon
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/addons/123x
    

      Retrieve an addon
      
  
 
Retrieve a specific addon using the id.
  
Notes
 
 

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

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "addon": {
        "charge_type": "recurring",
        "enabled_in_portal": true,
        "id": "sub_reports",
        "name": "sub_Reports",
        "object": "addon",
        "period": 1,
        "period_unit": "month",
        "price": 750,
        "status": "active",
        "taxable": true,
        "type": "on_off"
    }
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v1/addons/{addon-id}
    
 
Method
 
  
   
 
    
 
Returns
 
addon  addon
 

      always returned 
 Resource object representing addon
 
Sample admin console URL
 

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

      Delete an addon
      
 
Idempotency Supported
 
 
 When an addon 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 addon but subscriptions already on it will continue to renew. Once an addon has been archived, it cannot be edited or used again and the addon cannot be un-archived. 
 

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

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

 Archiving an addon will not affect coupons in anyway. 
  
Notes
 
 

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

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "addon": {
        "charge_type": "recurring",
        "enabled_in_portal": true,
        "id": "test",
        "invoice_name": "sample data pack",
        "name": "Test",
        "object": "addon",
        "period": 1,
        "period_unit": "month",
        "price": 200,
        "status": "deleted",
        "taxable": true,
        "type": "on_off"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v1/addons/{addon-id}/delete
    
 
Method
 
  
   
 
    
 
Returns
 
addon  addon
 

      always returned 
 Resource object representing addon
 
Sample admin console URL
 

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