Subscriptions

API Version

Product Catalog

Library

A Chargebee subscription connects a customer record to products/services. It describes what the customer has signed up for and how often they're charged for it. The essential components of a subscription are:

A plan-item price.
Any addon- and charge-item prices applied to the subscription.
Any coupons applied.
Any discounts applied.

The charges in a subscription are billed via invoices.

Note: The maximum number of subscriptions for any given customer (active or not) is 900.

Subscription billing frequencies

Chargebee offers two billing frequency options for subscriptions:

Plan-based billing (default): Subscriptions are billed based on the billing period defined for the item price of the item_type plan. Learn more.
Multi-frequency billing: Subscriptions are billed according to the billing period of each recurring item price within the subscription. Learn more.

Important
Limitations of Multi-frequency billing.

Private Beta
Multi-frequency billing is in private beta. Please reach out to the Chargebee support to enable this feature.

The selection of the billing frequency preference is configured at the site level.

Item price compatibility in a subscription

When creating or updating a subscription, one of the item prices specified under subscription_items must be a plan-item price. The remaining must be compatible addon- or charge-item prices. An item price is compatible with a plan-item price if their currencies are the same. Additionally, an addon-item price is compatible with a plan-item price only if their billing frequencies meet the following conditions:

`period_unit` for plan-item price	Compatible `period_unit` for addon-item price	Compatible period for addon-item price
`day`	`day`	The `period` of the plan-item price should be divisible by the `period` of the addon-item price. Example If the `period` of the plan-item price is `10`, then the period of the addon-item price can be `10`, `5`, `2`, or `1`.
`week`	`week` or `day`	The `period` (in days) of the plan-item price should be divisible by the `period` of the addon-item price. Example If the `period` of the plan-item price is `2`, then the period of the addon-item price can be as follows depending on the value of `period_unit`: for `period_unit` as `week`, `period` can be `2` or `1`. for `period_unit` as `day`, `period` can be `14`, `7`, `2`, or `1`.
`month`	`month`	The `period` of the plan-item price should be divisible by the `period` of the addon-item price. Example If the `period` of the plan-item price is `6`, then the `period` of the addon-item price can be `6`, `3`, `2`, or `1`.
`year`	`year` or `month`	The `period` (in months) of the plan-item price should be divisible by the `period` of the addon-item price. Example If the `period` of the plan-item price is `2`, then the `period` of the addon-item price can be as follows depending on the value of `period_unit`: for `period_unit` as `year`, `period` can be `2` or `1`. for `period_unit` as `month`, `period` can be `24`, `12`, `8`, `6`, `4`, `3`, `2`, or `1`.

Tax provider fields

Anrok: Canadian customers can have multiple tax registration numbers. We currently support only sharing one tax registration number with Anrok. So we added a new field which can have comma separated multiple tax reg numbers for Anrok. Values configured in the field is passed as it is to Anrok for accurate tax calculation

Field ID	Field Value	APIs
`additionalTaxRegistrationNumber`	Canadian tax registration numbers in comma separated fashion.	APIs involving customer attributes. Also includes APIs where we are creating new customers. Eg: estimate, subscription, hosted pages.

Vertex: Chargebee shares field IDs and corresponding values with merchants, who then configure them on the Vertex Platform for seamless integration

Note: Field Id like customerCode , customerClass , andtaxExempted belong to the customer object.

Field Id like productCode , productClass , productTaxCode , and productClass belong to the product object.

Field ID	Field Value	APIs
`productCode`	Merchant to configure it on Vertex Platform	APIs having Plan(PC1), Addons(PC1) and Item Prices(PC2) attributes.
`productClass`
`customerCode`		APIs involving customer attributes. Also includes APIs where we are creating new customers. For example: estimate, subscription, hosted pages.
`customerClass`

Taxamo: Chargebee shares field IDs and corresponding values with merchants, who then configure them on the Taxamo Platform for seamless integration

Field Id	Field Value	APIs
`productTaxCode`	Merchant to configure it on Taxamo Platform	APIs having Plan(PC1), Addons(PC1) and Item Prices(PC2) attributes.
`productClass`
`taxExempted`		APIs involving customer attributes. Also includes APIs where we are creating new customers. For example: estimate, subscription, hosted pages.

cbtaxes: With CBTaxes, you can activate India IGST for customers located in Special Economic Zones (SEZ), implement zero-rated tax for SEZ customers, enable India IGST for customers outside of India, and set up zero-rated tax for customers outside of India.

Field ID	Field Value	APIs
`indiaSez`	`SEZ_IGST_TAX`	APIs involving customer attributes. Also includes APIs where we are creating new customers. For example: estimate, subscription, hosted pages.
`indiaSez`	`SEZ_ZERO_RATED_TAX`
`indiaExport`	`EXPORT_IGST_TAX`
`indiaExport`	`EXPORT_ZERO_RATED_TAX`

All: For tax inclusive tax calculation, For tax exclusive tax calculation. This is currently used for price type overriding at customer level

Field ID	Field Value	APIs
`priceType`	`TAX_INCLUSIVE`	APIs involving customer attributes. Also includes APIs where we are creating new customers. For example: estimate, subscription, hosted pages.
	`TAX_EXCLUSIVE`
	`SITE_DEFAULT` or blank	Removes price type override, and allows site level configuration to be used for tax calculation.

Sample subscription [ JSON ]

{
    "activated_at": 1612890916,
    "billing_period": 1,
    "billing_period_unit": "month",
    "created_at": 1612890916,
    "currency_code": "USD",
    "current_term_end": 1615310116,
    "current_term_start": 1612890916,
    "customer_id": "__test__8asukSOXdulGOV",
    "deleted": false,
    "due_invoices_count": 1,
    "due_since": 1612890916,
    "has_scheduled_changes": false,
    "id": "__test__8asukSOXduqmOY",
    "mrr": 0,
    "next_billing_at": 1615310116,
    "object": "subscription",
    "remaining_billing_cycles": 1,
    "resource_version": 1612890917000,
    "started_at": 1612890916,
    "status": "active",
    "subscription_items": [
        {
            "amount": 1000,
            "billing_cycles": 1,
            "free_quantity": 0,
            "item_price_id": "basic-USD",
            "item_type": "plan",
            "object": "subscription_item",
            "quantity": 1,
            "unit_price": 1000
        },
        {
            "amount": 100,
            "item_price_id": "day-pass-USD",
            "item_type": "addon",
            "object": "subscription_item",
            "quantity": 1,
            "unit_price": 100
        }
    ],
    "total_dues": 1100,
    "updated_at": 1612890917
}

API Index URL

https://{site}.chargebee.com/api/v2/subscriptions

id

string, max chars=50

The unique identifier of the subscription resource. You have the option to specify this value when creating a customer. If not specified, Chargebee automatically generates a unique identifier.

Note In the event that the subscription resource is transferred along with its associated customer resource to a different business entity, Chargebee assigns a new random value as the id for the subscription. The original identifier is preserved for the transferred copy of the subscription resource. (See also: Mechanics of business entity transfer.)

currency_code

string, max chars=3

The currency code (ISO 4217 format ) of the subscription

start_date

optional, timestamp(UTC) in seconds

Applicable only for 'future' subscriptions. The scheduled start time of the subscription.

trial_end

optional, timestamp(UTC) in seconds

End of the trial period for the subscription. Presence of this value for 'future' subscription implies the subscription will go into 'in_trial' state when it starts.

remaining_billing_cycles

optional, integer, min=0

When the subscription is not on a contract term: this value is the number of billing cycles remaining after the current cycle, at the end of which, the subscription cancels.
When the subscription is on a contract term: this value is the number of billing cycles remaining in the contract term after the current billing cycle.

po_number

optional, string, max chars=100

Purchase order number for this subscription.

plan_quantity_in_decimal

optional, string, max chars=33

The decimal representation of the quantity of the plan purchased. Returned for quantity-based plans when multi-decimal pricing is enabled.

plan_unit_price_in_decimal

optional, string, max chars=39

The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.

customer_id

string, max chars=50

Identifier of the customer with whom this subscription is associated.

status

enumerated string

Current state of the subscription

Possible values are

trial_start

optional, timestamp(UTC) in seconds

Start of the trial period for the subscription. Presence of this value for future subscription implies the subscription will go into in_trial state when it starts.

trial_end_action

optional, enumerated string

Applicable only when End-of-trial Action has been enabled for the site. Whenever the subscription has a trial period, this attribute (parameter) is returned (required) and specifies the operation to be carried out for the subscription once the trial ends.

Possible values are

current_term_start

optional, timestamp(UTC) in seconds

Start of the current billing period of the subscription.

current_term_end

optional, timestamp(UTC) in seconds

End of the current billing period of the subscription. Subscription is renewed immediately after this.

next_billing_at

optional, timestamp(UTC) in seconds

The date/time at which the next billing for the subscription happens. This is usually right after current_term_end unless multiple subscription terms were invoiced in advance using the terms_to_charge parameter.

created_at

optional, timestamp(UTC) in seconds

The time at which the subscription was created.

started_at

optional, timestamp(UTC) in seconds

Time at which the subscription was started. Is null for future subscriptions as it is yet to be started.

activated_at

optional, timestamp(UTC) in seconds

Time at which the subscription status last changed to active. For example, this value is updated when an in_trial or cancelled subscription activates.

contract_term_billing_cycle_on_renewal

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

override_relationship

optional, boolean

If true , ignores the hierarchy relationship and uses customer as payment and invoice owner.

pause_date

optional, timestamp(UTC) in seconds

When a pause has been scheduled, it is the date/time of scheduled pause. When the subscription is in the paused state, it is the date/time when the subscription was paused.

resume_date

optional, timestamp(UTC) in seconds

For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

cancelled_at

optional, timestamp(UTC) in seconds

Time at which subscription was cancelled or is set to be cancelled.

cancel_reason

optional, enumerated string

The reason for canceling the subscription. Set by Chargebee automatically.

Possible values are

created_from_ip

optional, string, max chars=50

The IP address of the user. Used primarly in Refersion integration. Refersion uses this field to track/log affiliate subscription.

resource_version

optional, long

Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

updated_at

optional, timestamp(UTC) in seconds

Timestamp indicating when the item was last updated.

has_scheduled_advance_invoices

boolean, default=false

The subscription has an advance invoicing schedule .

has_scheduled_changes

boolean, default=false

Indicates whether there are subscription changes scheduled for the next renewal.

Note This attribute does not consider changes scheduled through upcoming ramps on the subscription. If changes on the subscription are scheduled only via ramps and not through the Update Subscription API, the value of this attribute remains false.

payment_source_id

optional, string, max chars=40

Payment source attached to this subscription. If present, customer's payment sources won't be used to collect any payment for this subscripiton.

plan_free_quantity_in_decimal

optional, string, max chars=33

The free_quantity_in_decimal as set for the plan. Returned for quantity-based plans when multi-decimal pricing is enabled.

plan_amount_in_decimal

optional, string, max chars=39

The decimal representation of the total amount for the plan, in major units of the currency. Always returned when multi-decimal pricing is enabled.

cancel_schedule_created_at

optional, timestamp(UTC) in seconds

This is the date/time at which the most recent cancellation schedule for the subscription was created in Chargebee. Applicable only for cancelled subscriptions or subscriptions that are scheduled for cancellation.

offline_payment_method

optional, enumerated string
null

Possible values are

channel

optional, enumerated string

The subscription channel this object originated from and is maintained in.

Possible values are

net_term_days

optional, integer

The Net D value explicitly set for this subscription. Net D is the number of days within which any invoice raised for the subscription must be paid. When an invoice is raised, and this value is unavailable, the net_term_days defined at the customer level is considered.

active_id

optional, string, max chars=50

Note: Present only when the subscription has been transferred between business entities.

Represents the id of the active version of the subscription resource.

Tip If the id and active_id of a subscription resource are the same, this indicates that you are working with the active version of that subscription resource.

due_invoices_count

optional, integer

Total number of invoices that are due for payment against the subscription. Note: Not supported if consolidated invoicing is enabled, or when the subscription is for the customer who is in hierarchy , and the parent of this customer owns and pays for the invoices of the subscription. It is also worth noting that the consolidated invoice amount is not included in the calculation of due_invoices_count .

due_since

optional, timestamp(UTC) in seconds

Time since this subscription has unpaid invoices. Note: Not supported if consolidated invoicing is enabled, or when the subscription is for the customer who is in hierarchy , and the parent of this customer owns and pays for the invoices of the subscription.

total_dues

optional, in cents, min=0

Total invoice due amount for this subscription. The value depends on the type of currency . Note: Not supported if consolidated invoicing is enabled, or when the subscription is for the customer who is in hierarchy , and the parent of this customer owns and pays for the invoices of the subscription. It is also worth noting that the consolidated invoice amount is not included in the calculation of total_dues .

mrr

optional, in cents, min=1

Monthly recurring revenue for the subscription. Updated asynchronously, this value catches up with changes to the subscription in less than a minute. The value depends on the type of currency . Note: This may not return accurate values since updated asynchronously.

exchange_rate

optional, bigdecimal, min=1E-9, max=999999999.999999999

Exchange rate used for base currency conversion.This value is updated to the rate configured on your site each time any change is made to the subscription.

base_currency_code

optional, string, max chars=3

The currency code (ISO 4217 format ) of the site's base currency.

invoice_notes

optional, string, max chars=2000

A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

meta_data

optional, jsonobject

A collection of key-value pairs that provides extra information about the subscription.

Note: There's a character limit of 65,535.

Learn more .

deleted

boolean

Indicates that the subscription has been deleted when the value is true. You can retrieve a deleted subscription using the list operation .

changes_scheduled_at

optional, timestamp(UTC) in seconds

If a subscription change has been scheduled, this is the date/time when the change is set to take effect. Note: As a limitation, this attribute is not returned when the change is scheduled to happen at the end of the current term.

cancel_reason_code

optional, string, max chars=100

Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation. Must be passed if set as mandatory in the app. The codes are case-sensitive

free_period

optional, integer

The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit."

free_period_unit

optional, enumerated string

Defines additional free period in association with the billing period.

Possible values are

create_pending_invoices

optional, boolean

Indicates whether the invoices for this subscription are generated with a pending status. This attribute is set to true automatically when the subscription has item prices that belong to metered items. You can also set this to true explicitly using the create/update subscription operations. This is useful in the following scenarios:

When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
When you need to inspect all charges before closing invoices for this subscription. Applicable only when Metered Billing is enabled for the site

auto_close_invoices

optional, boolean

business_entity_id

optional, string, max chars=50

The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

subscription_items
Show attributes [+]

optional, list of subscription_item

Details of individual item prices that are part of this subscription.

Subscription item attributes

item_price_id

string, max chars=100

The unique identifier of the item price.

item_type

enumerated string

The type of item. There must be one and only one item of type plan in this list.

Possible values are

quantity

optional, integer, min=1

The quantity of the item purchased

quantity_in_decimal

optional, string, max chars=33

The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.

unit_price

optional, in cents, min=0

The price/per unit price of the item. When not provided, the value set for the item price is used. This is only applicable when the pricing_model of the item price is flat_fee or per_unit. Also, it is only allowed when price overriding is enabled for the site. The value depends on the type of currency. If changes_scheduled_at is in the past and a unit_price is not passed, then the item price's current unit price is considered even if the item price did not exist on the date as of when the change is scheduled.

unit_price_in_decimal

optional, string, max chars=39

The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.

amount

optional, in cents, min=0

The total amount for the item as determined from unit_price , free_quantity , quantity and item_tiers as applicable. The value depends on the type of currency .

current_term_start

optional, timestamp(UTC) in seconds

The beginning of the item's current billing period.

Note Applicable only when multi-frequency billing is enabled.

Private Beta Multi-frequency billing is in private beta. Please reach out to the Chargebee support to enable this feature.

current_term_end

optional, timestamp(UTC) in seconds

The end of the item's current billing period. Chargebee renews the item immediately following this date.

Note Applicable only when multi-frequency billing is enabled.

Private Beta Multi-frequency billing is in private beta. Please reach out to the Chargebee support to enable this feature.

next_billing_at

optional, timestamp(UTC) in seconds

The date or time at when the next billing for the item is scheduled to occur. This typically occurs immediately after current_term_end.

Note Applicable only when multi-frequency billing is enabled.

Private Beta Multi-frequency billing is in private beta. Please reach out to the Chargebee support to enable this feature.

amount_in_decimal

optional, string, max chars=39

The decimal representation of the total amount for the item, in major units of the currency. Always returned when multi-decimal pricing is enabled.

billing_period

optional, integer, min=1

The interval between consecutive billing cycles for the subscription item. The interval is measured in the units defined by billing_period_unit .

billing_period_unit

optional, enumerated string

The unit of measurement used to define the billing_period for the subscription item.

Possible values are

free_quantity

optional, integer, min=0

The free_quantity of the plan-item as specified for the item price.

free_quantity_in_decimal

optional, string, max chars=33

The free_quantity_in_decimal as set for the item price. Returned for quantity-based item prices when multi-decimal pricing is enabled.

trial_end

optional, timestamp(UTC) in seconds

The date/time when the trial period of the item ends. Applies to plan-items and--when enabled --addon-items as well.

billing_cycles

optional, integer, min=0

For the plan-item price: the value determines the number of billing cycles the subscription runs before canceling automatically. If not provided, then the value set for the plan-item price is used.

For addon-item prices: If addon billing cycles are enabled then this is the number of subscription billing cycles for which the addon is included. If not provided, then the value set under attached addons is used. Further, if that value is not provided, then the value set for the addon-item price is used.

service_period_days

optional, integer, min=1, max=730

The service period of the item in days from the day of charge.

charge_on_event

optional, enumerated string

When charge_on_option option is set to on_event , this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items.

Possible values are

charge_once

optional, boolean

Indicates if the charge-item is to be charged only once or each time the charge_on_event occurs. This parameter only applies to charge-items.

charge_on_option

optional, enumerated string

Indicates when the charge-item is to be charged. This parameter only applies to charge-items.

Possible values are

proration_type

optional, enumerated string

Specifies how to manage charges or credits for the addon during a subscription update.

You can't modify this parameter's value within the current term. Moreover, it is removed from the subscription attributes when the next term starts.

See also: subscription_items[proration_type] parameter for Update a subscription API .

Possible values are

usage_accumulation_reset_frequency

optional, enumerated string

Specifies the frequency at which the usage counter needs to be reset.

Possible values are

item_tiers
Show attributes [+]

optional, list of item_tier

The pricing details of subscription_items which have pricing_model as tiered , volume or stairstep .

Item tier attributes

item_price_id

string, max chars=100

The id of the item price to which this tier belongs.

starting_unit

integer, min=1

The lowest value in the quantity tier.

ending_unit

optional, integer

The highest value in the quantity tier.

price

in cents, default=0, min=0

The per-unit price for the tier when the pricing_model is tiered or volume. The total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.

starting_unit_in_decimal

optional, string, max chars=33

The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered , volume or stairstep and multi-decimal pricing is enabled.

ending_unit_in_decimal

optional, string, max chars=33

The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered , volume or stairstep and multi-decimal pricing is enabled.

price_in_decimal

optional, string, max chars=39

The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep , it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.

pricing_type

optional, enumerated string

Pricing type for the tier.

Possible values are

package_size

optional, integer, min=1

Package size for the tier when pricing type is package. Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.

index

integer, min=0

The index number of the subscription to which the item price is added. Provide a unique number between 0 and 4 (inclusive) for each subscription that is to be created.

charged_items
Show attributes [+]

optional, list of charged_item

List of event based charge items that have already been charged.

coupons
Show attributes [+]

optional, list of coupon

List of coupons for this subscription

shipping_address
Show attributes [+]

optional, shipping_address

Shipping address for the subscription.

Shipping address attributes

first_name

optional, string, max chars=150

The first name of the contact.

last_name

optional, string, max chars=150

The last name of the contact.

email

optional, string, max chars=70

The email address.

company

optional, string, max chars=250

The company name.

phone

optional, string, max chars=50

The phone number.

line1

optional, string, max chars=150

Address line 1

line2

optional, string, max chars=150

Address line 2

line3

optional, string, max chars=150

Address line 3

city

optional, string, max chars=50

The name of the city.

state_code

optional, string, max chars=50

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ ). For Tamil Nadu (India), set as TN (not IN-TN ). For British Columbia (Canada), set as BC (not CA-BC ).

state

optional, string, max chars=50

The state/province name.

country

optional, string, max chars=50

The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code .

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.

zip

optional, string, max chars=20

Zip or postal code. The number of characters is validated according to the rules specified here .

validation_status

optional, enumerated string, default=not_validated

The address verification status.

Possible values are

referral_info
Show attributes [+]

optional, referral_info

Referral details if exists for the subscription

Referral info attributes

referral_code

optional, string, max chars=50

Referral code if available for the subscription

coupon_code

optional, string, max chars=50

Referral coupon code if available for the subscription

referrer_id

optional, string, max chars=19

Referrer id if available for the subscription

external_reference_id

optional, string, max chars=50

External reference id in referral system for the subscription

reward_status

optional, enumerated string, default=pending

Reward status for the referral subscription

Possible values are

referral_system

optional, enumerated string

Source referral system for the referral subscription

Possible values are

account_id

string, max chars=50

Referral account id

campaign_id

string, max chars=50

Referral campaign id

external_campaign_id

optional, string, max chars=100

Referral external campaign id

friend_offer_type

optional, enumerated string

Friend offer type for the referral camapign

Possible values are

referrer_reward_type

optional, enumerated string

Referrer reward type for the referral campaign

Possible values are

notify_referral_system

optional, enumerated string

Whether or not to notify the referral purchases to the referral system

Possible values are

destination_url

optional, string, max chars=250

Destination url for the referral campaign

post_purchase_widget_enabled

boolean, default=true

Whether post purchase widget is enabled for this campaign

billing_override
Show attributes [+]

optional, billing_override

contract_term
Show attributes [+]

optional, contract_term

Contract terms for this subscription

Contract term attributes

id

string, max chars=50

Id that uniquely identifies the contract term in the site.

status

enumerated string

Current status of contract

Possible values are

contract_start

timestamp(UTC) in seconds

The start date of the contract term

contract_end

timestamp(UTC) in seconds

The end date of the contract term

billing_cycle

integer, min=0

The number of billing cycles of the subscription that the contract term is for.

action_at_term_end

enumerated string, default=renew

Action to be taken when the contract term completes.

Possible values are

total_contract_value

in cents, default=0, min=0

The sum of the totals of all the invoices raised as part of the contract term. For active contract terms, this is a predicted value. The value depends on the type of currency. If the subscription was imported with the contract term, then this value includes the value passed for total_amount_raised .

total_contract_value_before_tax

in cents, default=0, min=0

It refers to the total amount of revenue that is expected to be generated from a specific contract term, calculated as the sum of all invoices raised during the term, regardless of payment status. It is based on past performance and the specified currency in the contract. If the subscription was imported, the value for total_amount_raised_before_tax is included in the calculation of the total contract value before tax. It's important to note that this value excludes any applicable taxes.

cancellation_cutoff_period

optional, integer

The number of days before contract_end , during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.

created_at

timestamp(UTC) in seconds

The date when the contract term was created.

subscription_id

string, max chars=50

The Id of the subscription that this contract term is for.

remaining_billing_cycles

optional, integer, min=0

The number of subscription billing cycles remaining after the current one for the contract term. This attribute is only returned for active contract terms.

discounts
Show attributes [+]

optional, list of discount

List of discounts currently attached to the subscription.

Note

Discounts of duration_type one_time are removed from the list after a single application to the subscription.
Discounts of duration_type limited_period are removed from the list once the specified period expires since their attachment to the subscription.

Discount attributes

id

string, max chars=50

An immutable unique id for the discount. It is always auto-generated.

invoice_name

optional, string, max chars=100

The name of the discount as it should appear on customer-facing pages and documents such as invoices and hosted pages. This is auto-generated based on the type , amount , and currency_code of the discount. For example, it can be 10% off or 10$ off .

type

enumerated string, default=percentage

The type of discount. Possible value are:

Possible values are

percentage

optional, double, min=0.01, max=100.0

The percentage of the original amount that should be deducted from it.

amount

optional, in cents, min=0

The value of the discount. The format of this value depends on the kind of currency.

quantity

optional, integer, min=1

Specifies the number of free units provided for the item, without affecting the total quantity sold. This parameter is applicable only when discount.type is offer_quantity.

currency_code

optional, string, max chars=3

The currency code (ISO 4217 format ) of the discount. This is only applicable when discount.type is fixed_amount .

duration_type

enumerated string, default=forever

Specifies the time duration for which this discount is attached to the subscription.

Possible values are

period

optional, integer, min=1

The duration of time for which the discount is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.

period_unit

optional, enumerated string

The unit of time for period. Applicable only when duration_type is limited_period.

Possible values are

included_in_mrr

boolean

The discount is included in MRR calculations for your site. This attribute is only applicable when duration_type is one_time and when the feature is enabled in Chargebee. Also, If the site-level setting is to exclude one-time discounts from MRR calculations, this value is always returned false.

apply_on

enumerated string

The amount on the invoice to which the discount is applied.

Possible values are

item_price_id

optional, string, max chars=100

The id of the item price in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.

created_at

timestamp(UTC) in seconds

Timestamp indicating when this discount is created.

apply_till

optional, timestamp(UTC) in seconds

Specifies till when the limited period discount is applicable. This attribute will be sent in the response only for limited_period duration type discount.

applied_count

optional, integer

Specifies the number of times the discount has been applied.

coupon_id

string, max chars=100

Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.

Note:

When the coupon ID contains a special character; for example: #, the API returns an error. Make sure that you encode the coupon ID in the path parameter before making an API call.

index

integer, min=0

The index number of the subscription to which the item price is added. Provide a unique number between 0 and 4 (inclusive) for each subscription that is to be created.

id

string, max chars=50

The unique identifier of the subscription resource. You have the option to specify this value when creating a customer. If not specified, Chargebee automatically generates a unique identifier.

currency_code

string, max chars=3

The currency code (ISO 4217 format ) of the subscription

start_date

optional, timestamp(UTC) in seconds

Applicable only for 'future' subscriptions. The scheduled start time of the subscription.

trial_end

optional, timestamp(UTC) in seconds

End of the trial period for the subscription. Presence of this value for 'future' subscription implies the subscription will go into 'in_trial' state when it starts.

remaining_billing_cycles

optional, integer, min=0

When the subscription is not on a contract term: this value is the number of billing cycles remaining after the current cycle, at the end of which, the subscription cancels.
When the subscription is on a contract term: this value is the number of billing cycles remaining in the contract term after the current billing cycle.

po_number

optional, string, max chars=100

Purchase order number for this subscription.

plan_quantity_in_decimal

optional, string, max chars=33

The decimal representation of the quantity of the plan purchased. Returned for quantity-based plans when multi-decimal pricing is enabled.

plan_unit_price_in_decimal

optional, string, max chars=39

The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.

customer_id

string, max chars=50

Identifier of the customer with whom this subscription is associated.

status

enumerated string

Current state of the subscription

Possible values are

trial_start

optional, timestamp(UTC) in seconds

Start of the trial period for the subscription. Presence of this value for future subscription implies the subscription will go into in_trial state when it starts.

trial_end_action

optional, enumerated string

Possible values are

current_term_start

optional, timestamp(UTC) in seconds

Start of the current billing period of the subscription.

current_term_end

optional, timestamp(UTC) in seconds

End of the current billing period of the subscription. Subscription is renewed immediately after this.

next_billing_at

optional, timestamp(UTC) in seconds

created_at

optional, timestamp(UTC) in seconds

The time at which the subscription was created.

started_at

optional, timestamp(UTC) in seconds

Time at which the subscription was started. Is null for future subscriptions as it is yet to be started.

activated_at

optional, timestamp(UTC) in seconds

Time at which the subscription status last changed to active. For example, this value is updated when an in_trial or cancelled subscription activates.

contract_term_billing_cycle_on_renewal

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

override_relationship

optional, boolean

If true , ignores the hierarchy relationship and uses customer as payment and invoice owner.

pause_date

optional, timestamp(UTC) in seconds

When a pause has been scheduled, it is the date/time of scheduled pause. When the subscription is in the paused state, it is the date/time when the subscription was paused.

resume_date

optional, timestamp(UTC) in seconds

For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

cancelled_at

optional, timestamp(UTC) in seconds

Time at which subscription was cancelled or is set to be cancelled.

cancel_reason

optional, enumerated string

The reason for canceling the subscription. Set by Chargebee automatically.

Possible values are

created_from_ip

optional, string, max chars=50

The IP address of the user. Used primarly in Refersion integration. Refersion uses this field to track/log affiliate subscription.

resource_version

optional, long

updated_at

optional, timestamp(UTC) in seconds

Timestamp indicating when the item was last updated.

has_scheduled_advance_invoices

boolean, default=false

The subscription has an advance invoicing schedule .

has_scheduled_changes

boolean, default=false

Indicates whether there are subscription changes scheduled for the next renewal.

payment_source_id

optional, string, max chars=40

Payment source attached to this subscription. If present, customer's payment sources won't be used to collect any payment for this subscripiton.

plan_free_quantity_in_decimal

optional, string, max chars=33

The free_quantity_in_decimal as set for the plan. Returned for quantity-based plans when multi-decimal pricing is enabled.

plan_amount_in_decimal

optional, string, max chars=39

The decimal representation of the total amount for the plan, in major units of the currency. Always returned when multi-decimal pricing is enabled.

cancel_schedule_created_at

optional, timestamp(UTC) in seconds

offline_payment_method

optional, enumerated string
null

Possible values are

channel

optional, enumerated string

The subscription channel this object originated from and is maintained in.

Possible values are

net_term_days

optional, integer

active_id

optional, string, max chars=50

Note: Present only when the subscription has been transferred between business entities.

Represents the id of the active version of the subscription resource.

Tip If the id and active_id of a subscription resource are the same, this indicates that you are working with the active version of that subscription resource.

due_invoices_count

optional, integer

due_since

optional, timestamp(UTC) in seconds

total_dues

optional, in cents, min=0

mrr

optional, in cents, min=1

exchange_rate

optional, bigdecimal, min=1E-9, max=999999999.999999999

Exchange rate used for base currency conversion.This value is updated to the rate configured on your site each time any change is made to the subscription.

base_currency_code

optional, string, max chars=3

The currency code (ISO 4217 format ) of the site's base currency.

invoice_notes

optional, string, max chars=2000

A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

meta_data

optional, jsonobject

A collection of key-value pairs that provides extra information about the subscription.

Note: There's a character limit of 65,535.

Learn more .

deleted

boolean

Indicates that the subscription has been deleted when the value is true. You can retrieve a deleted subscription using the list operation .

changes_scheduled_at

optional, timestamp(UTC) in seconds

cancel_reason_code

optional, string, max chars=100

free_period

optional, integer

The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit."

free_period_unit

optional, enumerated string

Defines additional free period in association with the billing period.

Possible values are

create_pending_invoices

optional, boolean

When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
When you need to inspect all charges before closing invoices for this subscription. Applicable only when Metered Billing is enabled for the site

auto_close_invoices

optional, boolean

business_entity_id

optional, string, max chars=50

The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

subscription_items

optional, list of subscription_item

Details of individual item prices that are part of this subscription.

item_tiers

optional, list of item_tier

The pricing details of subscription_items which have pricing_model as tiered , volume or stairstep .

charged_items

optional, list of charged_item

List of event based charge items that have already been charged.

coupons

optional, list of coupon

List of coupons for this subscription

shipping_address

optional, shipping_address

Shipping address for the subscription.

referral_info

optional, referral_info

Referral details if exists for the subscription

billing_override

optional, billing_override

contract_term

optional, contract_term

Contract terms for this subscription

discounts

optional, list of discount

List of discounts currently attached to the subscription.

Note

Discounts of duration_type one_time are removed from the list after a single application to the subscription.
Discounts of duration_type limited_period are removed from the list once the specified period expires since their attachment to the subscription.

Try in API Explorer

Note: This endpoint optionally supports 3DS. To use it create a payment_intent and provide it via this endpoint.

Creates a new subscription for an existing customer in Chargebee. Any available credits and excess payments for the customer are automatically applied on the invoice.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/customers/__test__8asz8Ru9WhHOJO/subscription_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d "subscription_items[item_price_id][0]"="basic-USD" \
     -d "subscription_items[billing_cycles][0]"=2 \
     -d "subscription_items[quantity][0]"=1 \
     -d "subscription_items[item_price_id][1]"="day-pass-USD" \
     -d "subscription_items[unit_price][1]"=100

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890916,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdulGOV",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890916000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890916
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1100,
        "amount_paid": 0,
        "amount_to_collect": 1100,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asukSOXdulGOV",
        "date": 1612890916,
        "deleted": false,
        "due_date": 1612890916,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__10",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asukSOXdulGOV",
                "date_from": 1612890916,
                "date_to": 1615310116,
                "description": "basic USD",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asukSOXdutkOa",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asukSOXduqmOY",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "new_sales_amount": 1100,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612890917000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1100,
        "subscription_id": "__test__8asukSOXduqmOY",
        "tax": 0,
        "term_finalized": true,
        "total": 1100,
        "updated_at": 1612890917,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1612890916,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890916,
        "currency_code": "USD",
        "current_term_end": 1615310116,
        "current_term_start": 1612890916,
        "customer_id": "__test__8asukSOXdulGOV",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890916,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXduqmOY",
        "mrr": 0,
        "next_billing_at": 1615310116,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890917000,
        "started_at": 1612890916,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890917
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/subscription_for_items

id[]

optional, string, max chars=50

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.

business_entity_id[]

optional, string, max chars=50

The unique ID of the business entity this subscription should be linked to. Applicable only when multiple business entities have been created for the site. This must be the same as the business entity of the {customer_id} for the operation to be successful.

Note

An alternative way of passing this parameter is by means of a custom HTTP header.

trial_end[]

optional, timestamp(UTC) in seconds

End of the trial period for the subscription. This overrides the trial period set for the plan-item. The value must be later than start_date. Set it to 0 to have no trial period.

billing_cycles[]

optional, integer, min=0

Specifies the number of billing cycles for the subscription. The behavior of the subscription after the billing cycles have completed depends on whether the subscription is on a contract term or not.

When the subscription is not on a contract term: if billing_cycles is not provided, then the billing cycles set for the plan-item price is used. Moreover, once the billing_cycles have completed, the subscription cancels.
When the subscription is on a contract term: Providing billing_cycles is mandatory. Moreover, once the billing_cycles have completed, the behavior of the subscription is determined by the contract_term[action_at_term_end] parameter.

mandatory_items_to_remove[[0..n]][0..n]

optional, list of string

Item ids of mandatorily attached addons that are to be removed from the subscription.

net_term_days[]

optional, integer

Defines Net D for the subscription. Net D is the number of days within which any invoice raised for the subscription must be paid.

If a value is provided: Net D is set explicitly for the subscription to the value provided. The value must be one among those defined in the site configuration.
If not provided: The attribute is not set and therefore not returned by the API. In this case, when an invoice is raised - whether now or later - the net_term_days defined at the customer level is considered. .

start_date[]

optional, timestamp(UTC) in seconds

The date/time at which the subscription is to start. If not provided, the subscription starts immediately. You can provide a value in the past as well. This is called backdating the subscription creation and is done when the subscription has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:

Backdating is enabled for subscription creation operations.
The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is typically the day of the month by which the accounting for the previous month must be closed.
The date is not more than duration X into the past, where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, start_date cannot be earlier than 14th February. .

auto_collection[]

optional, enumerated string

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.

Possible values are

terms_to_charge[]

optional, integer, min=1

The number of subscription billing cycles (including the first one) to invoice in advance .

billing_alignment_mode[]

optional, enumerated string

Override the billing alignment mode for Calendar Billing. Only applicable when using Calendar Billing. The default value is that which has been configured for the site.

Possible values are

offline_payment_method[]

optional, enumerated string

The preferred offline payment method for the subscription.

Possible values are

po_number[]

optional, string, max chars=100

Purchase order number for this subscription.

coupon_ids[[0..n]][0..n]

optional, list of string

List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.

payment_source_id[]

optional, string, max chars=40

Id of the payment source to be attached to this subscription.

override_relationship[]

optional, boolean

If true , ignores the hierarchy relationship and uses customer as payment and invoice owner.

invoice_notes[]

optional, string, max chars=2000

A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

invoice_date[]

optional, timestamp(UTC) in seconds

The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices is set to true , and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

invoice_date must be in the past.
It is not earlier than start_date.
It is not more than one calendar month into the past. Eg. If today is 13th January, then you cannot pass a value that is earlier than 13th December.
invoice_immediately is true. .

meta_data[]

optional, jsonobject

A collection of key-value pairs that provides extra information about the subscription.

Note: There's a character limit of 65,535.

Learn more .

invoice_immediately[]

optional, boolean

If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to unbilled charges. The default value is as per the site settings .

Note: invoice_immediately only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.

replace_primary_payment_source[]

optional, boolean, default=true

Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.

free_period[]

optional, integer, min=1

The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit.

free_period_unit[]

optional, enumerated string

The unit of time in multiples of which the free_period parameter is expressed. The value must be equal to or lower than the period_unit attribute of the plan chosen.

Possible values are

contract_term_billing_cycle_on_renewal[]

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

create_pending_invoices[]

optional, boolean

When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
When you need to inspect all charges before closing invoices for this subscription. Applicable only when Metered Billing is enabled for the site .

auto_close_invoices[]

optional, boolean

first_invoice_pending[]

optional, boolean, default=false

If you want to bill the usages from the previous billing cycle, set this parameter to true. This is useful if the subscription has moved from another system into Chargebee and you haven't closed the previous cycle's invoice yet. This creates a pending invoice immediately on subscription creation, to which you can add usages for the previous cycle. If any non-metered items are present for the current term, they're also added to this pending invoice. As with all pending invoices, this invoice is also closed automatically or via an API call. This parameter can be passed only when the create_pending_invoices is true .

trial_end_action[]

optional, enumerated string

Possible values are

payment_initiator[]

optional, enumerated string

The type of initiator to be used for the payment request triggered by this operation.

Possible values are

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

shipping_address[first_name]

optional, string, max chars=150

shipping_address[last_name]

optional, string, max chars=150

shipping_address[email]

optional, string, max chars=70

shipping_address[company]

optional, string, max chars=250

shipping_address[phone]

optional, string, max chars=50

shipping_address[line1]

optional, string, max chars=150

shipping_address[line2]

optional, string, max chars=150

shipping_address[line3]

optional, string, max chars=150

shipping_address[city]

optional, string, max chars=50

shipping_address[state_code]

optional, string, max chars=50

shipping_address[state]

optional, string, max chars=50

shipping_address[zip]

optional, string, max chars=20

shipping_address[country]

optional, string, max chars=50

shipping_address[validation_status]

optional, enumerated string, default=not_validated

Possible values are

statement_descriptor

Parameters for statement_descriptor
pass parameters as statement_descriptor[<param name>]

statement_descriptor[descriptor]

optional, string, max chars=65k

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

optional, string, max chars=150

payment_intent[gateway_account_id]

required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

optional, string, max chars=65k

payment_intent[payment_method_type]

optional, enumerated string

Possible values are

payment_intent[reference_id]

optional, string, max chars=65k

payment_intent[additional_information]

optional, jsonobject

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

optional, enumerated string

Possible values are

contract_term[cancellation_cutoff_period]

optional, integer, default=0

billing_override

Parameters for billing_override
pass parameters as billing_override[<param name>]

billing_override[max_excess_payment_usage]

optional, long, min=-1

billing_override[max_refundable_credits_usage]

optional, long, min=-1

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

required, string, max chars=100

subscription_items[quantity][0..n]

optional, integer, min=1

subscription_items[quantity_in_decimal][0..n]

optional, string, max chars=33

subscription_items[unit_price][0..n]

optional, in cents, min=0

subscription_items[unit_price_in_decimal][0..n]

optional, string, max chars=39

subscription_items[billing_cycles][0..n]

optional, integer, min=0

subscription_items[trial_end][0..n]

optional, timestamp(UTC) in seconds

subscription_items[service_period_days][0..n]

optional, integer, min=1, max=730

subscription_items[charge_on_event][0..n]

optional, enumerated string

Possible values are

subscription_items[charge_once][0..n]

optional, boolean

subscription_items[charge_on_option][0..n]

optional, enumerated string

Possible values are

subscription_items[usage_accumulation_reset_frequency][0..n]

optional, enumerated string

Possible values are

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[apply_on][0..n]

optional, enumerated string

Possible values are

discounts[duration_type][0..n]

required, enumerated string, default=forever

Possible values are

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

discounts[amount][0..n]

optional, in cents, min=0

discounts[period][0..n]

optional, integer, min=1

discounts[period_unit][0..n]

optional, enumerated string

Possible values are

discounts[included_in_mrr][0..n]

optional, boolean

discounts[item_price_id][0..n]

optional, string, max chars=100

discounts[quantity][0..n]

optional, integer, min=1

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[item_price_id][0..n]

optional, string, max chars=100

item_tiers[starting_unit][0..n]

optional, integer, min=1

item_tiers[ending_unit][0..n]

optional, integer

item_tiers[price][0..n]

optional, in cents, default=0, min=0

item_tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[price_in_decimal][0..n]

optional, string, max chars=39

item_tiers[pricing_type][0..n]

optional, enumerated string

Possible values are

item_tiers[package_size][0..n]

optional, integer, min=1

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charges

Try in API Explorer

Returns a list of subscriptions meeting all the conditions specified in the filter parameters below.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     --data-urlencode "item_id[in]"=["basic"]

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "customer": {
                "allow_direct_debit": false,
                "auto_collection": "off",
                "card_status": "no_card",
                "created_at": 1612890919,
                "deleted": false,
                "excess_payments": 0,
                "first_name": "John",
                "id": "__test__8asukSOXdvg4PD",
                "last_name": "Doe",
                "net_term_days": 0,
                "object": "customer",
                "pii_cleared": "active",
                "preferred_currency_code": "USD",
                "promotional_credits": 0,
                "refundable_credits": 0,
                "resource_version": 1612890919000,
                "taxability": "taxable",
                "unbilled_charges": 0,
                "updated_at": 1612890919
            },
            "subscription": {
                "activated_at": 1612890920,
                "billing_period": 1,
                "billing_period_unit": "month",
                "created_at": 1612890920,
                "currency_code": "USD",
                "current_term_end": 1615310120,
                "current_term_start": 1612890920,
                "customer_id": "__test__8asukSOXdvg4PD",
                "deleted": false,
                "due_invoices_count": 1,
                "due_since": 1612890920,
                "has_scheduled_changes": false,
                "id": "__test__8asukSOXdvliPG",
                "mrr": 0,
                "next_billing_at": 1615310120,
                "object": "subscription",
                "remaining_billing_cycles": 1,
                "resource_version": 1612890920000,
                "started_at": 1612890920,
                "status": "active",
                "subscription_items": [
                    {
                        "amount": 1000,
                        "billing_cycles": 1,
                        "free_quantity": 0,
                        "item_price_id": "basic-USD",
                        "item_type": "plan",
                        "object": "subscription_item",
                        "quantity": 1,
                        "unit_price": 1000
                    },
                    {..}
                ],
                "total_dues": 1100,
                "updated_at": 1612890920
            }
        },
        {..}
    ],
    "next_offset": "[\"1612890918000\",\"230000000081\"]"
}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions

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.

include_deleted[]

optional, boolean, default=false

Indicates whether to include deleted objects in the list. The deleted objects have the attribute deleted as true .

sort_by[<sort-order>]

optional, string filter
Sorts based on the specified attribute.
Supported attributes : created_at, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

optional, string filter

A unique and immutable identifier for the subscription. If not provided, it is autogenerated. Supported operators : is, is_not, starts_with, in, not_in

Example → id[is_not] = "8gsnbYfsMLds"

Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "8gsnbYfsMLds"

customer_id[<operator>]

optional, string filter

Identifier of the customer with whom this subscription is associated. Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is] = "8gsnbYfsMLds"

Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is] = "8gsnbYfsMLds"

item_id[<operator>]

optional, string filter

The plan item code. Supported operators : is, is_not, starts_with, in, not_in

Example → item_id[is_not] = "silver"

Supported operators : is, is_not, starts_with, in, not_in

Example → item_id[is] = "silver"

item_price_id[<operator>]

optional, string filter

The plan item price code. Supported operators : is, is_not, starts_with, in, not_in

Example → item_price_id[is] = "silver-USD-monthly"

Supported operators : is, is_not, starts_with, in, not_in

Example → item_price_id[is] = "silver-USD-monthly"

status[<operator>]

optional, enumerated string filter

Current state of the subscription. Possible values are : future, in_trial, active, non_renewing, paused, cancelled, transferred
Supported operators : is, is_not, in, not_in

Example → status[is] = "active"

cancel_reason[<operator>]

optional, enumerated string filter

The reason for canceling the subscription. Set by Chargebee automatically. Possible values are : not_paid, no_card, fraud_review_failed, non_compliant_eu_customer, tax_calculation_failed, currency_incompatible_with_gateway, non_compliant_customer
Supported operators : is, is_not, in, not_in, is_present

Example → cancel_reason[is] = "not_paid"

cancel_reason_code[<operator>]

optional, string filter

Example → cancel_reason_code[is] = "Not Paid"

Supported operators : is, is_not, starts_with, in, not_in

Example → cancel_reason_code[is] = "Not Paid"

remaining_billing_cycles[<operator>]

optional, number filter

When the subscription is not on a contract term: this value is the number of billing cycles remaining after the current cycle, at the end of which, the subscription cancels.
When the subscription is on a contract term: this value is the number of billing cycles remaining in the contract term after the current billing cycle. . Supported operators : is, is_not, lt, lte, gt, gte, between, is_present

Example → remaining_billing_cycles[is_not] = "3"

Supported operators : is, is_not, lt, lte, gt, gte, between, is_present

Example → remaining_billing_cycles[is] = "3"

created_at[<operator>]

optional, timestamp(UTC) in seconds filter

The time at which the subscription was created. Supported operators : after, before, on, between

Example → created_at[before] = "1435054328"

Supported operators : after, before, on, between

Example → created_at[after] = "1435054328"

activated_at[<operator>]

optional, timestamp(UTC) in seconds filter

Time at which the subscription status last changed to active. For example, this value is updated when an in_trial or cancelled subscription activates. Supported operators : after, before, on, between, is_present

Example → activated_at[after] = "1435054328"

Supported operators : after, before, on, between, is_present

Example → activated_at[after] = "1435054328"

next_billing_at[<operator>]

optional, timestamp(UTC) in seconds filter

Example → next_billing_at[after] = "1435054328"

Supported operators : after, before, on, between

Example → next_billing_at[after] = "1435054328"

cancelled_at[<operator>]

optional, timestamp(UTC) in seconds filter

Time at which subscription was cancelled or is set to be cancelled. Supported operators : after, before, on, between

Example → cancelled_at[after] = "1435054328"

Supported operators : after, before, on, between

Example → cancelled_at[after] = "1435054328"

has_scheduled_changes[<operator>]

optional, enumerated string filter

If true , there are subscription changes scheduled on next renewal. Possible values are : true, false
Supported operators : is

Example → has_scheduled_changes[is] = "true"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter

To filter based on updated_at. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by input parameter as updated_at for a faster response. Supported operators : after, before, on, between

Example → updated_at[after] = "1243545465"

Supported operators : after, before, on, between

Example → updated_at[after] = "1243545465"

offline_payment_method[<operator>]

optional, enumerated string filter

The preferred offline payment method for the subscription. Possible values are : no_preference, cash, check, bank_transfer, ach_credit, sepa_credit, boleto, us_automated_bank_transfer, eu_automated_bank_transfer, uk_automated_bank_transfer, jp_automated_bank_transfer, mx_automated_bank_transfer, custom
Supported operators : is, is_not, in, not_in

Example → offline_payment_method[is] = "cash"

auto_close_invoices[<operator>]

optional, enumerated string filter

Set to false to override for this subscription, the site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute has a higher precedence than the same attribute at the customer level. Possible values are : true, false
Supported operators : is

Example → auto_close_invoices[is] = "true"

override_relationship[<operator>]

optional, enumerated string filter

If true , ignores the hierarchy relationship and uses customer as payment and invoice owner. Possible values are : true, false
Supported operators : is

Example → override_relationship[is] = "false"

business_entity_id[<operator>]

optional, string filter

The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

Supported operators : is, is_not, starts_with

Example → business_entity_id[is_not] = "business_entity_id"

Supported operators : is

Example → business_entity_id[is] = "business_entity_id"

channel[<operator>]

optional, enumerated string filter

The subscription channel this object originated from and is maintained in. Possible values are : web, app_store, play_store
Supported operators : is, is_not, in, not_in

Example → channel[is] = "APP STORE"

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

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

Try in API Explorer

Retrieves a list of contract term resources for the subscription specified in the path.

Warning This API will return an error when multi-frequency billing is enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdty0Mv/contract_terms \
     -G  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "contract_term": {
                "action_at_term_end": "renew",
                "billing_cycle": 6,
                "cancellation_cutoff_period": 0,
                "contract_end": 1628529313,
                "contract_start": 1612890913,
                "created_at": 1612890913,
                "id": "__test__8asukSOXdty7Mw",
                "object": "contract_term",
                "remaining_billing_cycles": 5,
                "status": "active",
                "total_contract_value": 6600
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/contract_terms

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

sort_by[<sort-order>]

optional, string filter
Sorts based on the specified attribute.
Supported attributes : created_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.

contract_term

always returned
Resource object representing contract_term

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

Try in API Explorer

Retrieves a list of discount resources currently attached to a specific subscription. The list is sorted in descending order based on the created_at timestamp.

Note This endpoint does not return coupon or coupon_code resources.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8at0iSK6IPu41q/discounts \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "discount": {
                "amount": 100,
                "applied_count": 1,
                "apply_on": "invoice_amount",
                "created_at": 1608822300,
                "currency_code": "USD",
                "duration_type": "forever",
                "id": "__test__8at0iSK6IPuW1r",
                "invoice_name": "__test__8at0iSK6IPuW1r",
                "object": "discount",
                "type": "fixed_amount"
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/discounts

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

discount

always returned
Resource object representing discount

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

Try in API Explorer

Retrieves a subscription.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXe0W3SU \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890938,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXe0QYSR",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890938000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890938
    },
    "subscription": {
        "activated_at": 1612890938,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890938,
        "currency_code": "USD",
        "current_term_end": 1615310138,
        "current_term_start": 1612890938,
        "customer_id": "__test__8asukSOXe0QYSR",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890938,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXe0W3SU",
        "mrr": 0,
        "next_billing_at": 1615310138,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890938000,
        "started_at": 1612890938,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890938
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Sample admin console URL

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

Try in API Explorer

Caution This API cannot be used for subscriptions that have ramps.

Retrieves a subscription with the scheduled changes applied.
Note: Only the following attributes are changed

item_id
item_price_id
billing_period
billing_period_unit
remaining_billing_cycles
coupons Other attributes such as status ,next_billing_at are not changed and will reflect the current subscription values.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXe0ksSf/retrieve_with_scheduled_changes \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890939,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXe0g2Sc",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890939000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890939
    },
    "subscription": {
        "activated_at": 1612890939,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890939,
        "currency_code": "USD",
        "current_term_end": 1615310139,
        "current_term_start": 1612890939,
        "customer_id": "__test__8asukSOXe0g2Sc",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890939,
        "has_scheduled_changes": true,
        "id": "__test__8asukSOXe0ksSf",
        "item_tiers": [],
        "mrr": 0,
        "next_billing_at": 1615310139,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890940000,
        "started_at": 1612890939,
        "status": "active",
        "subscription_items": [
            {
                "amount": 8000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 4,
                "unit_price": 2000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890940
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/retrieve_with_scheduled_changes

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Try in API Explorer

Caution This API cannot be used for subscriptions that have ramps.

Removes the subscription changes scheduled on next renewal. Advance charges, if any, will be refunded as credits and a new invoice will be generated on renewal.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdyTgRH/remove_scheduled_changes \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890930,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdyOjRE",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890930000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890930
    },
    "subscription": {
        "activated_at": 1612890930,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890930,
        "currency_code": "USD",
        "current_term_end": 1615310130,
        "current_term_start": 1612890930,
        "customer_id": "__test__8asukSOXdyOjRE",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890930,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdyTgRH",
        "mrr": 0,
        "next_billing_at": 1615310130,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890932000,
        "started_at": 1612890930,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890932
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/remove_scheduled_changes

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

credit_notes

optional
Resource object representing credit_notes

Try in API Explorer

Note: Cannot be called when the subscription is on a contract term. (That is, when the contract_term.status attribute is active.)

If the subscription is in Non Renewing or In Trial state and is also scheduled to cancel at the end of current term, then this API can be used to remove the scheduled cancellation. When a scheduled cancellation is removed, the subscription will revert to Active or In Trial state, whichever is the state before cancellation was scheduled.

While removing the scheduled cancellation, you may specify the number of billing cycles. If the billing cycle is not specified, the default billing cycle from the plan will be applied on the subscription.

Sample Request

Try in API Explorer

Only for Java

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdy9TR2/remove_scheduled_cancellation \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/subscriptions/6o0O5Uxv3FyNWH/remove_scheduled_cancellation \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/subscriptions/6o0O5Uxv48TCWh/remove_scheduled_cancellation \
     -u {site_api_key}:\
     -d billing_cycles=3

copy

Click to Copy

Remove scheduled cancellation for a non-renewing subscription.

Remove a scheduled subscription cancellation and set the number of billing cycles.

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505329,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdy5GQz",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505329175,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505329
    },
    "subscription": {
        "activated_at": 1517505329,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505329,
        "currency_code": "USD",
        "current_term_end": 1519924529,
        "current_term_start": 1517505329,
        "customer_id": "__test__8asukSOXdy5GQz",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505329,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdy9TR2",
        "mrr": 0,
        "next_billing_at": 1519924529,
        "object": "subscription",
        "resource_version": 1517505330230,
        "started_at": 1517505329,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1517505330
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/remove_scheduled_cancellation

billing_cycles[]

optional, integer, min=0

Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.

contract_term_billing_cycle_on_renewal[]

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

optional, enumerated string

Possible values are

contract_term[cancellation_cutoff_period]

optional, integer, default=0

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Try in API Explorer

Caution If there are scheduled ramps for the subscription, this operation can move the ramps to the draft status when it conflicts with any upcoming ramps.

Removes coupons associated with the subscription. If the param coupon_ids is not specified, all the coupons linked to the subscription are be removed.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdxPSQY/remove_coupons \
     -u {site_api_key}:\
     -d "coupon_ids[0]"="P10DISC"

copy

Click to Copy

Removes the listed coupons associated with the subscription.

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890926,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdxKsQV",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890926000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890926
    },
    "subscription": {
        "activated_at": 1612890926,
        "billing_period": 1,
        "billing_period_unit": "month",
        "coupon": "A5USD",
        "coupons": [
            {
                "applied_count": 1,
                "apply_till": 1644340526,
                "coupon_id": "A5USD",
                "object": "coupon"
            },
            {..}
        ],
        "created_at": 1612890926,
        "currency_code": "USD",
        "current_term_end": 1615310126,
        "current_term_start": 1612890926,
        "customer_id": "__test__8asukSOXdxKsQV",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890926,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdxPSQY",
        "mrr": 0,
        "next_billing_at": 1615310126,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890927000,
        "started_at": 1612890926,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 540,
        "updated_at": 1612890927
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/remove_coupons

coupon_ids[[0..n]][0..n]

optional, list of string

List of coupons to be removed from the subscription. You can provide only coupon_id and not coupon_code .

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Try in API Explorer

Note:

This endpoint optionally supports 3DS. To use it, create a payment_intent and provide it via this endpoint.
When the Remove mandatory add-ons from old plan during subscription plan update setting is enabled on your Chargebee site, all mandatory addons with the old plan will be automatically removed during the subscription update to a new plan.

Caution If the subscription currently includes ramps, it's important to note that any ramps scheduled may move to the draft status due to changes in plan billing frequency, line item, or term end. Carefully review your ramp configurations and the details of the subscription update to prevent any unintended disruptions to the subscription.

Updates the specified subscription by setting the parameters passed. Any parameters not provided are left unmodified. If an invoice is generated for this operation, any available credits and excess payments for the customer are automatically applied.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asrKRrLKtirr/update_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d invoice_immediately=true \
     -d "subscription_items[item_price_id][0]"="basic-USD" \
     -d "subscription_items[quantity][0]"=4 \
     -d "subscription_items[unit_price][0]"=1000

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_notes": [],
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890941,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXe1B5Sp",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890941000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890941
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 3000,
        "amount_paid": 0,
        "amount_to_collect": 3000,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asukSOXe1B5Sp",
        "date": 1612890942,
        "deleted": false,
        "due_date": 1612890942,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__30",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 3000,
                "customer_id": "__test__8asukSOXe1B5Sp",
                "date_from": 1612890942,
                "date_to": 1615310141,
                "description": "basic USD - Prorated Charges",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asukSOXe1VTT0",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 3,
                "subscription_id": "__test__8asukSOXe1FHSs",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612890942000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 3000,
        "subscription_id": "__test__8asukSOXe1FHSs",
        "tax": 0,
        "term_finalized": true,
        "total": 3000,
        "updated_at": 1612890942,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1612890941,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890941,
        "currency_code": "USD",
        "current_term_end": 1615310141,
        "current_term_start": 1612890941,
        "customer_id": "__test__8asukSOXe1B5Sp",
        "deleted": false,
        "due_invoices_count": 2,
        "due_since": 1612890941,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXe1FHSs",
        "mrr": 0,
        "next_billing_at": 1615310141,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890942000,
        "started_at": 1612890941,
        "status": "active",
        "subscription_items": [
            {
                "amount": 4000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 4,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 4100,
        "updated_at": 1612890942
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/update_for_items

mandatory_items_to_remove[[0..n]][0..n]

optional, list of string

A list of item IDs representing the mandatorily attached addons associated with the plan to which the subscription is being updated. These addons will be removed from the subscription during the subscription update process.

replace_items_list[]

optional, boolean, default=false

If true then the existing subscription_items list for the subscription is replaced by the one provided. If false then the provided subscription_items list gets added to the existing list.

net_term_days[]

optional, integer

Updates Net D for the subscription. Net D is the number of days within which any invoice raised for the subscription must be paid.

If the value is 0 or a positive integer: Net D is set explicitly for the subscription to the value provided. The value must be one of those defined in the site configuration.
If the value is -1: The attribute is reset and therefore not returned by the API. In this case, when an invoice is raised - whether now or later - the net_term_days defined at the customer level is considered.
If the value is not provided: The attribute is left unaltered. .

invoice_date[]

optional, timestamp(UTC) in seconds

The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices is set to true , and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

invoice_date must be in the past.
invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
It is not earlier than changes_scheduled_at, reactivate_from, or trial_end.
invoice_immediately is true. .

start_date[]

optional, timestamp(UTC) in seconds

The new start date of a future subscription. Applicable only for future subscriptions.

trial_end[]

optional, timestamp(UTC) in seconds

The time at which the trial has ended or will end for the subscription. Set it to 0 to have no trial period.

Note

This is only allowed when the subscription status is future, in_trial, or cancelled.
The value must not be earlier than changes_scheduled_at or start_date.
This parameter can be backdated (set to a value in the past) only when the subscription is in cancelled or in_trial status. Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end is backdated, the subscription immediately goes into active or non_renewing status.

billing_cycles[]

optional, integer, min=0

Billing cycles set for plan-item price is used by default.

terms_to_charge[]

optional, integer, min=1

The number of subscription billing cycles to invoice in advance. If a new term is started for the subscription due to this API call, then terms_to_charge is inclusive of this new term. See description for the force_term_reset parameter to learn more about when a subscription term is reset.

reactivate_from[]

optional, timestamp(UTC) in seconds

If the subscription status is cancelled and it is being reactivated via this operation, this is the date/time at which the subscription should be reactivated. Note: It is recommended not to pass this parameter along with changed_scheduled_at. reactivate_from can be backdated (set to a value in the past). Use backdating when the subscription has been reactivated already but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:

Backdating must be enabled for subscription reactivation operations.
The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is the day of the month by which the accounting for the previous month must be closed.
The date is on or after the last date/time any of the product catalog items of the subscription were changed.
The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, changes_scheduled_at cannot be earlier than 14th February. .

billing_alignment_mode[]

optional, enumerated string

Override the billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing.

Possible values are

auto_collection[]

optional, enumerated string

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.

Possible values are

offline_payment_method[]

optional, enumerated string

The preferred offline payment method for the subscription.

Possible values are

po_number[]

optional, string, max chars=100

Purchase order number for this subscription.

coupon_ids[[0..n]][0..n]

optional, list of string

List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes. If changes_scheduled_at is in the past, then the currently available coupons can be used even if they were not available as of the date for when the change is scheduled.

replace_coupon_list[]

optional, boolean, default=false

If true then the existing coupon_ids list for the subscription is replaced by the one provided. If false then the provided list gets added to the existing coupon_ids .

prorate[]

optional, boolean

When true: Prorated credits or charges are created as applicable for this change.
When false: The subscription is changed without creating any credits or charges.
When not provided, the value configured in the site settings is considered.

Caveat

For further changes within the same billing term, when prorate is set to true, credits are not created when all the conditions below hold true:

An immediate previous change was made

with prorate set to false and
no changes were made to the subscription's billing term and
a change was made to either the subscription's items or their prices.

end_of_term[]

optional, boolean, default=false

Caution This parameter is unavailable when the Subscription Ramps feature is enabled; use Create a ramp API instead.

Set this to true if you want the update to be applied at the end of the current subscription billing cycle.

force_term_reset[]

optional, boolean, default=false

Say the subscription has the renewal date as 28th of every month. When the plan-item price of the subscription is set to one that has the same billing period as the current plan-item price, the subscription change does not change the term. In other words, the subscription still renews on the 28th. Passing this parameter as true will have the subscription reset its term to the current date (provided end_of_term is false). Note: When the new plan-item price has a billing period different from the current plan-item price of the subscription, the term is always reset, regardless of the value passed for this parameter.

reactivate[]

optional, boolean

When the status of the subscription is cancelled , this parameter determines whether the subscription is reactivated upon making this API request. Unless passed explicitly as false , this parameter is implied as true when you provide the subscription_items and coupons parameters.

token_id[]

optional, string, max chars=40

The Chargebee payment token generated by Chargebee JS.

Note: The payment token created via Chargebee JS uses the gateway selected through Smart Routing. Explicitly passing a gateway_id in this API call will not override the gateway associated with the token.

invoice_notes[]

optional, string, max chars=2000

A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

meta_data[]

optional, jsonobject

A collection of key-value pairs that provides extra information about the subscription.

Note: There's a character limit of 65,535.

Learn more .

invoice_immediately[]

optional, boolean

Note: invoice_immediately only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.

override_relationship[]

optional, boolean

If true , ignores the hierarchy relationship and uses customer as payment and invoice owner.

changes_scheduled_at[]

optional, timestamp(UTC) in seconds

Caution This parameter cannot be set to a future date when the Subscription Ramps feature is enabled; use Create a ramp API instead.

When change_option is set to specific_date , then set the date/time at which the subscription change is to happen or has happened. Note: It is recommended not to pass this parameter along with reactivate_from. changes_scheduled_at can be set to a value in the past. This is called backdating the subscription change and is performed when the subscription change has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:

Backdating must be enabled for subscription change operations.
Only the following changes can be backdated:
Changes in the recurring items or their prices.
Addition of non-recurring items.
Subscription status is active, cancelled, or non_renewing.
The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is typically the day of the month by which the accounting for the previous month must be closed.
The date is on or after current_term_start.
The date is on or after the last date/time any of the following changes were made:
Changes in the recurring items or their prices.
Addition of non-recurring items.
The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, changes_scheduled_at cannot be earlier than 14th February..

Note: The changes_scheduled_at parameter does not apply to auto_collection , shipping_address , and po_number ; these parameters take effect immediately when scheduling a subscription update.

change_option[]

optional, enumerated string

Specifies the effective date for the subscription change.

Possible values are

contract_term_billing_cycle_on_renewal[]

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

free_period[]

optional, integer, min=1

The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit.

free_period_unit[]

optional, enumerated string

The unit of time in multiples of which the free_period parameter is expressed. The value must be equal to or lower than the period_unit attribute of the plan chosen.

Possible values are

create_pending_invoices[]

optional, boolean

When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
When you need to inspect all charges before closing invoices for this subscription. Applicable only when Metered Billing is enabled for the site .

auto_close_invoices[]

optional, boolean

trial_end_action[]

optional, enumerated string

Possible values are

payment_initiator[]

optional, enumerated string

The type of initiator to be used for the payment request triggered by this operation.

Possible values are

invoice_usages[]

optional, boolean, default=false

Setting this attribute to true will invoice the overages for the metered item during subscription changes .

card

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

optional, string, max chars=50

card[first_name]

optional, string, max chars=50

card[last_name]

optional, string, max chars=50

card[number]

required if card provided, string, max chars=1500

card[expiry_month]

required if card provided, integer, min=1, max=12

card[expiry_year]

required if card provided, integer

card[cvv]

optional, string, max chars=520

card[preferred_scheme]

optional, enumerated string

Possible values are

card[billing_addr1]

optional, string, max chars=150

card[billing_addr2]

optional, string, max chars=150

card[billing_city]

optional, string, max chars=50

card[billing_state_code]

optional, string, max chars=50

card[billing_state]

optional, string, max chars=50

card[billing_zip]

optional, string, max chars=20

card[billing_country]

optional, string, max chars=50

card[additional_information]

optional, jsonobject

payment_method

Parameters for payment_method
pass parameters as payment_method[<param name>]

payment_method[type]

optional, enumerated string

Possible values are

payment_method[gateway_account_id]

optional, string, max chars=50

payment_method[reference_id]

optional, string, max chars=200

payment_method[tmp_token]

required if reference_id not provided, string, max chars=65k

payment_method[issuing_country]

optional, string, max chars=50

payment_method[additional_information]

optional, jsonobject

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

optional, string, max chars=150

payment_intent[gateway_account_id]

required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

optional, string, max chars=65k

payment_intent[payment_method_type]

optional, enumerated string

Possible values are

payment_intent[reference_id]

optional, string, max chars=65k

payment_intent[additional_information]

optional, jsonobject

billing_address

Parameters for billing_address
pass parameters as billing_address[<param name>]

billing_address[first_name]

optional, string, max chars=150

billing_address[last_name]

optional, string, max chars=150

billing_address[email]

optional, string, max chars=70

billing_address[company]

optional, string, max chars=250

billing_address[phone]

optional, string, max chars=50

billing_address[line1]

optional, string, max chars=150

billing_address[line2]

optional, string, max chars=150

billing_address[line3]

optional, string, max chars=150

billing_address[city]

optional, string, max chars=50

billing_address[state_code]

optional, string, max chars=50

billing_address[state]

optional, string, max chars=50

billing_address[zip]

optional, string, max chars=20

billing_address[country]

optional, string, max chars=50

billing_address[validation_status]

optional, enumerated string, default=not_validated

Possible values are

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

shipping_address[first_name]

optional, string, max chars=150

shipping_address[last_name]

optional, string, max chars=150

shipping_address[email]

optional, string, max chars=70

shipping_address[company]

optional, string, max chars=250

shipping_address[phone]

optional, string, max chars=50

shipping_address[line1]

optional, string, max chars=150

shipping_address[line2]

optional, string, max chars=150

shipping_address[line3]

optional, string, max chars=150

shipping_address[city]

optional, string, max chars=50

shipping_address[state_code]

optional, string, max chars=50

shipping_address[state]

optional, string, max chars=50

shipping_address[zip]

optional, string, max chars=20

shipping_address[country]

optional, string, max chars=50

shipping_address[validation_status]

optional, enumerated string, default=not_validated

Possible values are

statement_descriptor

Parameters for statement_descriptor
pass parameters as statement_descriptor[<param name>]

statement_descriptor[descriptor]

optional, string, max chars=65k

customer

Parameters for customer
pass parameters as customer[<param name>]

customer[vat_number]

optional, string, max chars=20

customer[vat_number_prefix]

optional, string, max chars=10

customer[entity_identifier_scheme]

optional, string, max chars=50

customer[is_einvoice_enabled]

optional, boolean

customer[einvoicing_method]

optional, enumerated string

Possible values are

customer[entity_identifier_standard]

optional, string, default=iso6523-actorid-upis, max chars=50

customer[business_customer_without_vat_number]

optional, boolean

customer[registered_for_gst]

optional, boolean

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

optional, enumerated string, default=renew

Possible values are

contract_term[cancellation_cutoff_period]

optional, integer

billing_override

Parameters for billing_override
pass parameters as billing_override[<param name>]

billing_override[max_excess_payment_usage]

optional, long, min=-1

billing_override[max_refundable_credits_usage]

optional, long, min=-1

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

required, string, max chars=100

subscription_items[quantity][0..n]

optional, integer, min=1

subscription_items[quantity_in_decimal][0..n]

optional, string, max chars=33

subscription_items[unit_price][0..n]

optional, in cents, min=0

subscription_items[unit_price_in_decimal][0..n]

optional, string, max chars=39

subscription_items[billing_cycles][0..n]

optional, integer, min=0

subscription_items[trial_end][0..n]

optional, timestamp(UTC) in seconds

subscription_items[service_period_days][0..n]

optional, integer, min=1, max=730

subscription_items[charge_on_event][0..n]

optional, enumerated string

Possible values are

subscription_items[charge_once][0..n]

optional, boolean

subscription_items[charge_on_option][0..n]

optional, enumerated string

Possible values are

subscription_items[proration_type][0..n]

optional, enumerated string

Possible values are

subscription_items[usage_accumulation_reset_frequency][0..n]

optional, enumerated string

Possible values are

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[apply_on][0..n]

optional, enumerated string

Possible values are

discounts[duration_type][0..n]

required, enumerated string, default=forever

Possible values are

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

discounts[amount][0..n]

optional, in cents, min=0

discounts[period][0..n]

optional, integer, min=1

discounts[period_unit][0..n]

optional, enumerated string

Possible values are

discounts[included_in_mrr][0..n]

optional, boolean

discounts[item_price_id][0..n]

optional, string, max chars=100

discounts[quantity][0..n]

optional, integer, min=1

discounts[operation_type][0..n]

required, enumerated string

Possible values are

discounts[id][0..n]

optional, string, max chars=50

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[item_price_id][0..n]

optional, string, max chars=100

item_tiers[starting_unit][0..n]

optional, integer, min=1

item_tiers[ending_unit][0..n]

optional, integer

item_tiers[price][0..n]

optional, in cents, default=0, min=0

item_tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[price_in_decimal][0..n]

optional, string, max chars=39

item_tiers[pricing_type][0..n]

optional, enumerated string

Possible values are

item_tiers[package_size][0..n]

optional, integer, min=1

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charges

credit_notes

optional
Resource object representing credit_notes

Try in API Explorer

Use this endpoint to adjust when a subscription's current term or trial ends without altering the plan or billing frequency. It is helpful when you need to align renewals to a specific calendar date or extend a trial. Future renewals will follow the new date, keeping the subscription cadence intact.

Prerequisites & Constraints

Subscriptions must be in one of the following status values: in_trial, active, non_renewing.

Impacts

Subscription

Based on the subscription's status, the following updates are made:

If the status is in_trial, the trial_end is set to the new date.
If the status is active, the current_term_end is set to the new date.
If the status is non_renewing, the upcoming cancellation date is set to the new date.

Invoices and Credit Notes

The API can generate unbilled charges, invoice, or credit notes. You can control the behaviour using prorate and invoice_immediately parameters. To preview invoices, credits, and dates, use the Change term end estimate endpoint.

Advance Charges

If there are advance charges, then credit notes are issued for the unused portion of the service period.

Scheduled Pause

If the subscription is scheduled to pause at the end of the current term, the pause date is updated to match the new term end date.

Ramps

If subscription ramps are present, this operation moves them to the draft state. Update and reschedule the ramps as needed to keep them in sync.

Implementation Notes

The request fails with invalid_state if the subscription is not in one of the trial, active, or non_renewing states. Validate the status before invoking this API.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdtByMK/change_term_end \
     -u {site_api_key}:\
     -d term_ends_at=1745951400

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "subscription": {
        "id": "16BPffUgMfxc58aJ",
        "billing_period": 1,
        "billing_period_unit": "month",
        "customer_id": "Azq8jIUfp36JT91T",
        "status": "active",
        "current_term_start": 1742754600,
        "current_term_end": 1745951399,
        "next_billing_at": 1745951400,
        "created_at": 1742819726,
        "started_at": 1742754600,
        "activated_at": 1742754600,
        "updated_at": 1742819811,
        "has_scheduled_changes": false,
        "channel": "web",
        "resource_version": 1742819811819,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "subscription_items": [
            {
                "item_price_id": "elle-826",
                "item_type": "plan",
                "quantity": 1,
                "quantity_in_decimal": "1.0000",
                "unit_price": 2300,
                "unit_price_in_decimal": "23.00000",
                "amount": 2300,
                "amount_in_decimal": "23.00000",
                "free_quantity": 0,
                "free_quantity_in_decimal": "0.0000",
                "object": "subscription_item"
            },
            {..}
        ],
        "due_invoices_count": 1,
        "due_since": 1742754600,
        "total_dues": 2300,
        "mrr": 2300,
        "exchange_rate": 1,
        "base_currency_code": "USD",
        "has_scheduled_advance_invoices": false,
        "override_relationship": false,
        "create_pending_invoices": false,
        "auto_close_invoices": true
    },
    "customer": {
        "id": "Azq8jIUfp36JT91T",
        "first_name": "Erika",
        "last_name": "Mustermann",
        "auto_collection": "off",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1742322846,
        "taxability": "taxable",
        "updated_at": 1742819695,
        "pii_cleared": "active",
        "channel": "web",
        "resource_version": 1742819695354,
        "deleted": false,
        "object": "customer",
        "card_status": "no_card",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "unbilled_charges": 0,
        "preferred_currency_code": "USD",
        "mrr": 4800,
        "auto_close_invoices": true
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/change_term_end

term_ends_at[]

required, timestamp(UTC) in seconds

The time at which the current term should end for this subscription. The value must be a date in the future, i.e. later than current time. The value must not be the same as next_billing_at .

prorate[]

optional, boolean

Applicable for active / non_renewing subscriptions. If specified as true prorated charges / credits will be added during this operation.

invoice_immediately[]

optional, boolean

Note: invoice_immediately only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charges

credit_notes

optional
Resource object representing credit_notes

Try in API Explorer

Note: This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.

This API is used to reactivate a cancelled subscription. You may also optionally specify a trial end date, to move the subscription to In Trial state. If trial end is not specified, the subscription will be activated and any applicable charges will be initiated.

Unless the billing cycle is specified, it will be set to plan's default billing cycle.

During an in-term reactivation++, unless the billing cycle is specified, the subscription's remaining billing cycles will be restored. If a trial end date is specified, then the plan's default billing cycle is used.

What is an "in-term reactivation"?
An "in-term reactivation" happens when the billing term of the subscription is retained upon cancellation and reactivation is initiated within that term.

When is the 'billing term' retained for a cancelled subscription?
When dunning (payment failure retry settings) is configured with the last retry configured as

cancel subscription and mark invoice as 'Not Paid', or
cancel subscription and mark the invoice as 'Voided' and the case if any of the current term invoices is partially or fully paid, the invoice is not voided but instead Chargebee marks the invoices as 'Not Paid'.

Note : In both cases, the billing term is retained and upon reactivation the subscription will be moved to active state (if the plan does not have a trial period) and no invoice will be generated. Ensure that you collect any unpaid invoices.

Example : A Subscription was billed from 1st to 31st of a month and it was cancelled on the 20th due to one of the above cases (billing term is not reset). If the reactivation happens on 25th then it is considered an in-term reactivation.

Reactivation of a subscription in non_renewing state has been deprecated. To remove a scheduled cancellation of a non_renewing Subscription, use Remove Scheduled Cancellation API. However, if you use reactivate API to remove scheduled cancellation for a non_renewing Subscription, then the status will be set to active and the billing cycle will be set to forever. If any value is passed for trial_end or billing cycle, an error will be thrown. If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied. Additional Error Scenarios: If there is a need to create an immediate charge and the collection fails, an error will be thrown.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdwxyQE/reactivate \
     -u {site_api_key}:\
     -d invoice_immediately=true \
     -d billing_cycles=4

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890924,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdwsNQB",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890924000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890924
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1100,
        "amount_paid": 0,
        "amount_to_collect": 1100,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asukSOXdwsNQB",
        "date": 1612890925,
        "deleted": false,
        "due_date": 1612890925,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__18",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asukSOXdwsNQB",
                "date_from": 1612890925,
                "date_to": 1615310125,
                "description": "basic USD",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asukSOXdxDQQP",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asukSOXdwxyQE",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612890926000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1100,
        "subscription_id": "__test__8asukSOXdwxyQE",
        "tax": 0,
        "term_finalized": true,
        "total": 1100,
        "updated_at": 1612890926,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1612890925,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890924,
        "currency_code": "USD",
        "current_term_end": 1615310125,
        "current_term_start": 1612890925,
        "customer_id": "__test__8asukSOXdwsNQB",
        "deleted": false,
        "due_invoices_count": 2,
        "due_since": 1612890924,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdwxyQE",
        "mrr": 0,
        "next_billing_at": 1615310125,
        "object": "subscription",
        "remaining_billing_cycles": 3,
        "resource_version": 1612890926000,
        "started_at": 1612890924,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 3,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 2200,
        "updated_at": 1612890926
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/reactivate

trial_end[]

optional, timestamp(UTC) in seconds

Providing this parameter indicates that the subscription reactivates with an in_trial status and the trial period ends at the date provided. The value must not be earlier than reactivate_from. Note: This parameter can be backdated (set to a value in the past) only when reactivate_from has been backdated. Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end is backdated, the subscription immediately goes into active or non_renewing status.

billing_cycles[]

optional, integer, min=0

Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.

reactivate_from[]

optional, timestamp(UTC) in seconds

The date/time at which the subscription was reactivated. When not provided, the subscription is reactivated immediately on calling this API. The value of this parameter must always be in the past (backdating). Do this when the subscription has already been reactivated and the billing has been delayed. The following prerequisites must be met for this parameter to be passed:

The backdating feature has been enabled for subscription reactivation operations.
The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is the day of the month by which the accounting for the previous month must be closed.
The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, reactivate_from cannot be earlier than 14th February. .

invoice_immediately[]

optional, boolean

Note: invoice_immediately only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.

billing_alignment_mode[]

optional, enumerated string

Applicable when calendar billing is enabled and a new active term gets started during this operation. Unless specified the configured default value will be used.

Possible values are

terms_to_charge[]

optional, integer, min=1

invoice_date[]

optional, timestamp(UTC) in seconds

The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices is true , and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

invoice_date must be in the past.
invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
It is not earlier than reactivate_from or trial_end.
invoice_immediately is true. .

contract_term_billing_cycle_on_renewal[]

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

payment_initiator[]

optional, enumerated string

The type of initiator to be used for the payment request triggered by this operation.

Possible values are

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

optional, enumerated string

Possible values are

contract_term[cancellation_cutoff_period]

optional, integer, default=0

statement_descriptor

Parameters for statement_descriptor
pass parameters as statement_descriptor[<param name>]

statement_descriptor[descriptor]

optional, string, max chars=65k

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

optional, string, max chars=150

payment_intent[gateway_account_id]

required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

optional, string, max chars=65k

payment_intent[payment_method_type]

optional, enumerated string

Possible values are

payment_intent[reference_id]

optional, string, max chars=65k

payment_intent[additional_information]

optional, jsonobject

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charges

Try in API Explorer

Adds a one time charge to the subscription which will be added to the invoice generated at the end of the current term. If there are any applicable coupons in the subscription, an appropriate discount will be applied.

To collect a charge immediately, use this API.

If any subscription changes happen before the end of the current term, these charges will be collected along with it.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXds3JLW/add_charge_at_term_end \
     -u {site_api_key}:\
     -d amount=300 \
     -d description="Service Charge"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "estimate": {
        "created_at": 1612890907,
        "invoice_estimate": {
            "amount_due": 1400,
            "amount_paid": 0,
            "credits_applied": 0,
            "currency_code": "USD",
            "customer_id": "__test__8asukSOXdrvyLT",
            "line_item_discounts": [],
            "line_item_taxes": [],
            "line_items": [
                {
                    "amount": 300,
                    "customer_id": "__test__8asukSOXdrvyLT",
                    "date_from": 1612890906,
                    "date_to": 1612890906,
                    "description": "Service Charge",
                    "discount_amount": 0,
                    "entity_type": "adhoc",
                    "id": "li___test__8asukSOXdsHoLe",
                    "is_taxed": false,
                    "item_level_discount_amount": 0,
                    "object": "line_item",
                    "pricing_model": "flat_fee",
                    "quantity": 1,
                    "subscription_id": "__test__8asukSOXds3JLW",
                    "tax_amount": 0,
                    "unit_amount": 300
                },
                {..}
            ],
            "object": "invoice_estimate",
            "price_type": "tax_exclusive",
            "recurring": true,
            "round_off_amount": 0,
            "sub_total": 1400,
            "taxes": [],
            "total": 1400
        },
        "object": "estimate",
        "subscription_estimate": {
            "currency_code": "USD",
            "id": "__test__8asukSOXds3JLW",
            "next_billing_at": 1615310105,
            "object": "subscription_estimate",
            "status": "active"
        }
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/add_charge_at_term_end

amount[]

optional, in cents, min=1

The amount to be charged. The unit depends on the type of currency .

description[]

required, string, max chars=250

Description for this charge.

amount_in_decimal[]

optional, string, max chars=39

The decimal representation of the amount for the one-time charge. Provide the value in major units of the currency. Can be provided only when multi-decimal pricing is enabled.

avalara_sale_type[]

optional, enumerated string

Indicates the type of sale carried out. This is applicable only if you use Chargebee's AvaTax for Communications integration.

Possible values are

avalara_transaction_type[]

optional, integer

Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee's AvaTax for Communications integration.

avalara_service_type[]

optional, integer

Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee's AvaTax for Communications integration.

date_from[]

optional, timestamp(UTC) in seconds

The time when the service period for the charge starts.

date_to[]

optional, timestamp(UTC) in seconds

The time when the service period for the charge ends.

estimate

always returned
Resource object representing estimate

Try in API Explorer

Creates an advance invoice or an advance invoicing schedule. When an advance invoice is generated, and auto_collection is on for the subscription, the payment_source associated with the subscription is charged. Any changes scheduled for the subscription are taken into account automatically while generating an advance invoice. Advance invoices are not generated for a subscription when it is in the paused status. Advance invoices are generated only for non-metered items in a subscription.

This operation is supported only on select plans. To know more, take a look at our plans and pricing page.
This operation is not supported for non_renewing and cancelled subscriptions.
This operation is not supported if an advance invoice is already present. You could void/delete that invoice and try creating another advance invoice.
For subscription with ramps, this API will return error for the following scenarios
- If the subscription has more than 12 ramps for the terms being invoiced.
- If schedule_type is specific_dates or fixed_intervals
- If subscription contains ramps scheduled for middle of the subscription term.
This API will return an error when multi-frequency billing is enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdtV2MX/charge_future_renewals \
     -u {site_api_key}:\
     -d terms_to_charge=5

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890911,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdtPJMU",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890911000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890911
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 5500,
        "amount_paid": 0,
        "amount_to_collect": 5500,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asukSOXdtPJMU",
        "date": 1612890912,
        "deleted": false,
        "due_date": 1612890912,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": true,
        "id": "__demo_inv__6",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asukSOXdtPJMU",
                "date_from": 1615310111,
                "date_to": 1617988511,
                "description": "basic USD",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asukSOXdthZMf",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asukSOXdtV2MX",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612890912000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 5500,
        "subscription_id": "__test__8asukSOXdtV2MX",
        "tax": 0,
        "term_finalized": true,
        "total": 5500,
        "updated_at": 1612890912,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1612890911,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890911,
        "currency_code": "USD",
        "current_term_end": 1615310111,
        "current_term_start": 1612890911,
        "customer_id": "__test__8asukSOXdtPJMU",
        "deleted": false,
        "due_invoices_count": 2,
        "due_since": 1612890911,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdtV2MX",
        "mrr": 0,
        "next_billing_at": 1628529311,
        "object": "subscription",
        "resource_version": 1612890911000,
        "started_at": 1612890911,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 6600,
        "updated_at": 1612890911
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/charge_future_renewals

terms_to_charge[]

optional, integer, default=1, min=1

For schedule_type = immediate: the number of future billing cycles to be invoiced in advance. The invoicing is done for the remaining_billing_cycles of the subscription if that is less than terms_to_charge.
For schedule_type = fixed_intervals: The number of future billing cycles in one interval. The schedule is created such that the total number of billing cycles in the schedule does not exceed the remaining_billing_cycles of the subscription. .

invoice_immediately[]

optional, boolean

Whether the charge should be invoiced immediately or added to unbilled_charges. Applicable only when schedule_type is immediate .

schedule_type[]

optional, enumerated string

The type of advance invoice or advance invoicing schedule.

Possible values are

fixed_interval_schedule

Parameters for fixed_interval_schedule
pass parameters as fixed_interval_schedule[<param name>]

fixed_interval_schedule[number_of_occurrences]

optional, integer, min=1

fixed_interval_schedule[days_before_renewal]

optional, integer, min=1

fixed_interval_schedule[end_schedule_on]

optional, enumerated string

Possible values are

fixed_interval_schedule[end_date]

optional, timestamp(UTC) in seconds

specific_dates_schedule

Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]

specific_dates_schedule[terms_to_charge][0..n]

optional, integer

specific_dates_schedule[date][0..n]

optional, timestamp(UTC) in seconds

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

advance_invoice_schedules

optional
Resource object representing advance_invoice_schedules

Try in API Explorer

Caution This API cannot be used for subscriptions that have ramps.- This API will return an error when multi-frequency billing is enabled.

Modifies the advance invoicing schedule for a subscription.

Sample Request

Try in API Explorer

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2vpB3C/edit_advance_invoice_schedule \
     -X POST  \
     -u {site_api_key}:\
     -d schedule_type="SPECIFIC_DATES" \
     -d "specific_dates_schedule[id][0]"="__test__KyVkmQSCX2vwe3Q" \
     -d "specific_dates_schedule[terms_to_charge][0]"=1

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2w3g3U/edit_advance_invoice_schedule \
     -u {site_api_key}:\
     -d schedule_type="FIXED_INTERVALS" \
     -d "fixed_interval_schedule[days_before_renewal]"=3

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "advance_invoice_schedules": [
        {
            "id": "__test__KyVkmQSCX2vwe3Q",
            "object": "advance_invoice_schedule",
            "schedule_type": "specific_dates",
            "specific_dates_schedule": {
                "date": 1518339708,
                "object": "specific_dates_schedule",
                "terms_to_charge": 1
            }
        },
        {..}
    ]
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/edit_advance_invoice_schedule

terms_to_charge[]

optional, integer, min=1

The number of billing cycles in one interval.

schedule_type[]

optional, enumerated string

The type of advance invoice or advance invoicing schedule.

Possible values are

fixed_interval_schedule

Parameters for fixed_interval_schedule
pass parameters as fixed_interval_schedule[<param name>]

fixed_interval_schedule[number_of_occurrences]

optional, integer, min=1

fixed_interval_schedule[days_before_renewal]

optional, integer, min=1

fixed_interval_schedule[end_schedule_on]

optional, enumerated string

Possible values are

fixed_interval_schedule[end_date]

optional, timestamp(UTC) in seconds

specific_dates_schedule

Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]

specific_dates_schedule[id][0..n]

optional, string, max chars=50

specific_dates_schedule[terms_to_charge][0..n]

optional, integer

specific_dates_schedule[date][0..n]

optional, timestamp(UTC) in seconds

advance_invoice_schedules

always returned
Resource object representing advance_invoice_schedules

Try in API Explorer

Caution

This API cannot be used for subscriptions that have ramps.
This API will return an error when multi-frequency billing is enabled.

Retrieves the advance_invoice_schedule for a subscription. Note that this endpoint is only applicable for schedule_type = specific_dates or fixed_intervals.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2wPg43/retrieve_advance_invoice_schedule \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "advance_invoice_schedules": [
        {
            "id": "__test__KyVkmQSCX2wUp4H",
            "object": "advance_invoice_schedule",
            "schedule_type": "specific_dates",
            "specific_dates_schedule": {
                "date": 1518339710,
                "object": "specific_dates_schedule",
                "terms_to_charge": 2
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/retrieve_advance_invoice_schedule

advance_invoice_schedules

always returned
Resource object representing advance_invoice_schedules

Try in API Explorer

Caution

This API cannot be used for subscriptions that have ramps.
This API will return an error when multi-frequency billing is enabled.

Deletes an advance invoicing schedule. When schedule_type = specific_dates, you also have the option of deleting a part of the schedule.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBsG2SYV7ZMB2K/remove_advance_invoice_schedule \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "advance_invoice_schedules": [],
    "subscription": {
        "customer": {
            "allow_direct_debit": false,
            "auto_collection": "off",
            "card_status": "no_card",
            "created_at": 1622014982,
            "deleted": false,
            "excess_payments": 0,
            "first_name": "John",
            "id": "__test__XpbBsG2SYV7ZFJ2H",
            "last_name": "Doe",
            "net_term_days": 0,
            "object": "customer",
            "pii_cleared": "active",
            "preferred_currency_code": "USD",
            "promotional_credits": 0,
            "refundable_credits": 0,
            "resource_version": 1622014982000,
            "taxability": "taxable",
            "unbilled_charges": 0,
            "updated_at": 1622014982
        },
        "subscription": {
            "activated_at": 1622014983,
            "billing_period": 1,
            "billing_period_unit": "month",
            "created_at": 1622014983,
            "currency_code": "USD",
            "current_term_end": 1624693383,
            "current_term_start": 1622014983,
            "customer_id": "__test__XpbBsG2SYV7ZFJ2H",
            "deleted": false,
            "due_invoices_count": 1,
            "due_since": 1622014983,
            "has_scheduled_advance_invoices": false,
            "has_scheduled_changes": false,
            "id": "__test__XpbBsG2SYV7ZMB2K",
            "mrr": 0,
            "next_billing_at": 1624693383,
            "object": "subscription",
            "resource_version": 1622014983000,
            "started_at": 1622014983,
            "status": "active",
            "subscription_items": [
                {
                    "amount": 1000,
                    "free_quantity": 0,
                    "item_price_id": "basic-USD",
                    "item_type": "plan",
                    "object": "subscription_item",
                    "quantity": 1,
                    "unit_price": 1000
                },
                {..}
            ],
            "total_dues": 1100,
            "updated_at": 1622014983
        }
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/remove_advance_invoice_schedule

specific_dates_schedule

Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]

specific_dates_schedule[id][0..n]

optional, string, max chars=50

subscription

always returned
Resource object representing subscription

advance_invoice_schedules

optional
Resource object representing advance_invoice_schedules

Try in API Explorer

Use this API to regenerate the current-term invoice for a subscription. The new invoice will contain non-metered charges from the current term and metered charges from the previous term. If a customer was billed incorrectly, because of a wrong plan, price, or tax configuration, you can first void or delete the erroneous invoice, update the subscription or usage records, and then run this operation to issue the corrected invoice.

Prerequisites & Constraints

Before regenerating an invoice, ensure the following conditions are met:

The subscription's current-term invoice must be voided or deleted.
The subscription status must be active or non_renewing.
There should be no unbilled charges for non-metered subscribed items for the current term.
There should be no unbilled charges for metered items for the previous term.
The subscription must not have any advance invoices

Impacts

Current-Term Invoice

Chargebee does not modify the voided or deleted invoice for the current term. Instead, it creates a new invoice.

The new invoice includes:

Subscription-item charges for the current term.
Usage charges from the previous term.

The new invoice does not include:

One-time addon charges, including mandatory addons.
Ad hoc or other one-time charges from the voided or deleted invoice.
Unbilled charges.
Usage charges for the current term.

If every charge for the current-term has a value of zero, and your site is configured to hide zero-value line items, the invoice is not generated.

If you delete the original invoice, the associated usage data is also deleted. To ensure accurate billing for metered items, add or bulk import usage records before regenerating the invoice.

Payment Collection

If auto-collection is on, Chargebee attempts to collect payment for the regenerated invoice. If the payment collection fails, the invoice regeneration also fails.

Note: Chargebee applies any customer balances, such as unapplied payment from the voided invoice, before attempting to collect the remaining amount.

Order

Any orders associated with the invoice are regenerated automatically when the invoice is regenerated.

Implementation Notes

Before calling this API, perform the following checks:

Confirm that the subscription status is active or non_renewing.
The invoice regeneration is supported for the current term only. If you're using the date_from and date_to parameters, ensure that their values fall within the range defined by subscription.current_term_start and subscription.current_term_end.

200:

STATUS

{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "amount_to_collect": 895,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnOuSHufd0ih",
        "date": 1517480651,
        "deleted": false,
        "due_date": 1517480651,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__2",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVnOuSHufd0ih",
                "date_from": 1517480650,
                "date_to": 1519899850,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnOuSHufd80s",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnOuSHufd0ih",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "new_sales_amount": 895,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517480651257,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 895,
        "subscription_id": "__test__KyVnOuSHufd0ih",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517480651,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/regenerate_invoice

date_from[]

optional, timestamp(UTC) in seconds

The start date of the period being invoiced. The default value is current_term_start .

date_to[]

optional, timestamp(UTC) in seconds

The end date of the period being invoiced. The default value is current_term_end .

prorate[]

optional, boolean

Whether the charges should be prorated according to the term specified by date_from and date_to. Should not be passed without date_from and date_to .

invoice_immediately[]

optional, boolean

Only applicable when Consolidated Invoicing is enabled for the customer. Set to false to leave the current term charge for the subscription as unbilled. Once you have done this for all suitable subscriptions of the customer, call Create an invoice for unbilled charges to invoice them.

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charges

Try in API Explorer

Import previous and active contract terms .

For contract terms in active state, import is allowed only if the associated subscription is active , in_trial , future or non-renewing .

Warning This API will return an error when multi-frequency billing is enabled.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdvMNOv/import_contract_term \
     -u {site_api_key}:\
     -d "contract_term[action_at_term_end]"="CANCEL" \
     -d "contract_term[billing_cycle]"=5 \
     -d "contract_term[contract_start]"=1483245610 \
     -d "contract_term[contract_end]"=1493613610 \
     -d "contract_term[status]"="TERMINATED" \
     -d "contract_term[total_contract_value]"=1000

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "contract_term": {
        "action_at_term_end": "cancel",
        "billing_cycle": 5,
        "cancellation_cutoff_period": 0,
        "contract_end": 1493613610,
        "contract_start": 1483245610,
        "created_at": 1483245610,
        "id": "__test__8asukSOXdvULP3",
        "object": "contract_term",
        "status": "terminated",
        "total_contract_value": 1000
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/import_contract_term

contract_term_billing_cycle_on_renewal[]

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[id]

optional, string, max chars=50

contract_term[created_at]

optional, timestamp(UTC) in seconds

contract_term[contract_start]

optional, timestamp(UTC) in seconds

contract_term[contract_end]

optional, timestamp(UTC) in seconds

contract_term[status]

optional, enumerated string

Possible values are

contract_term[total_amount_raised]

optional, in cents, default=0, min=0

contract_term[total_amount_raised_before_tax]

optional, in cents, default=0, min=0

contract_term[total_contract_value]

optional, in cents, default=0, min=0

contract_term[total_contract_value_before_tax]

optional, in cents, default=0, min=0

contract_term[billing_cycle]

optional, integer, min=0

contract_term[action_at_term_end]

optional, enumerated string, default=renew

Possible values are

contract_term[cancellation_cutoff_period]

optional, integer

contract_term

always returned
Resource object representing contract_term

Try in API Explorer

Imports one or more unbilled charges into an existing subscription. Use this operation to add usage-based or other unbilled charges recorded in external systems to the subscription.

Prerequisites & Constraints

If you are trying to use this operation on your live site, ensure you have requested Support to enable it, otherwise the API will return an "API not enabled" error.

Impacts

Invoicing

Unbilled charges on the subscription are automatically invoiced on the next renewal.
You can also invoice unbilled charges on-demand using the Create an invoice for unbilled charges API.

Accounting Integrations

Imported unbilled charges will not sync with your accounting integration until they are invoiced.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdvHJGn/import_unbilled_charges \
     -X POST  \
     -u {site_api_key}:\
     -d "unbilled_charges[date_from][0]"=1517490271 \
     -d "unbilled_charges[date_to][0]"=1519909471 \
     -d "unbilled_charges[description][0]"="No Trial" \
     -d "unbilled_charges[unit_amount][0]"=4900 \
     -d "unbilled_charges[quantity][0]"=1 \
     -d "unbilled_charges[entity_id][0]"="no-trial" \
     -d "unbilled_charges[entity_type][0]"="PLAN_ITEM_PRICE"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "unbilled_charges": [
        {
            "id": "li___dev__8asq9TI2eBrV1",
            "customer_id": "active",
            "subscription_id": "active",
            "date_from": 1517490271,
            "date_to": 1519909471,
            "unit_amount": 4900,
            "pricing_model": "per_unit",
            "quantity": 1,
            "amount": 4900,
            "discount_amount": 0,
            "description": "No Trial",
            "entity_id": "no-trial",
            "is_voided": false,
            "updated_at": 1663736354,
            "deleted": false,
            "object": "unbilled_charge",
            "entity_type": "plan",
            "currency_code": "USD"
        },
        {..}
    ]
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/import_unbilled_charges

unbilled_charges

Parameters for unbilled_charges. Multiple unbilled_charges can be passed by specifying unique indices.
pass parameters as unbilled_charges[<param name>][<idx:0..n>]

unbilled_charges[id][0..n]

optional, string, max chars=40

unbilled_charges[date_from][0..n]

required, timestamp(UTC) in seconds

unbilled_charges[date_to][0..n]

required, timestamp(UTC) in seconds

unbilled_charges[entity_type][0..n]

required, enumerated string

Possible values are

unbilled_charges[entity_id][0..n]

optional, string, max chars=100

unbilled_charges[description][0..n]

optional, string, max chars=250

unbilled_charges[unit_amount][0..n]

optional, in cents, min=0

unbilled_charges[quantity][0..n]

optional, integer, min=0

unbilled_charges[amount][0..n]

optional, in cents, min=0

unbilled_charges[unit_amount_in_decimal][0..n]

optional, string, max chars=39

unbilled_charges[quantity_in_decimal][0..n]

optional, string, max chars=33

unbilled_charges[amount_in_decimal][0..n]

optional, string, max chars=39

unbilled_charges[discount_amount][0..n]

optional, in cents, min=0

unbilled_charges[use_for_proration][0..n]

optional, boolean, default=false

unbilled_charges[is_advance_charge][0..n]

optional, boolean, default=false

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[unbilled_charge_id][0..n]

optional, string, max chars=40

discounts[entity_type][0..n]

optional, enumerated string

Possible values are

discounts[entity_id][0..n]

optional, string, max chars=100

discounts[description][0..n]

optional, string, max chars=250

discounts[amount][0..n]

required, in cents, min=0

tiers

Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]

tiers[unbilled_charge_id][0..n]

required, string, max chars=40

tiers[starting_unit][0..n]

optional, integer, min=0

tiers[ending_unit][0..n]

optional, integer

tiers[quantity_used][0..n]

optional, integer, min=0

tiers[unit_amount][0..n]

optional, in cents, min=0

tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

tiers[quantity_used_in_decimal][0..n]

optional, string, max chars=33

tiers[unit_amount_in_decimal][0..n]

optional, string, max chars=40

unbilled_charges

always returned
Resource object representing unbilled_charges

Try in API Explorer

Imports a subscription into Chargebee.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Sample Request

Try in API Explorer

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/customers/__test__8at19S2Bx82rKy/import_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d status="ACTIVE" \
     -d current_term_end=1593541800 \
     -d "subscription_items[item_price_id][0]"="basic-USD" \
     -d "subscription_items[quantity][0]"=1 \
     -d "charged_items[item_price_id][0]"="ssl-charge-USD" \
     -d "charged_items[last_charged_at][0]"=1516297094

curl  https://{site}.chargebee.com/api/v2/customers/__test__8at19S2Bx82rKy/import_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d status="ACTIVE" \
     -d current_term_end=1593541800 \
     -d "exhausted_coupon_ids[0]"=FESTIVE100 \
     -d "subscription_items[item_price_id][0]"="basic-USD" \
     -d "subscription_items[quantity][0]"=1 \
     -d "charged_items[item_price_id][0]"="ssl-charge-USD" \
     -d "charged_items[last_charged_at][0]"=1516297094

copy

Click to Copy

Import a subscription specifying an exhausted coupon.

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505319,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdvWPP6",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505319325,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505319
    },
    "subscription": {
        "activated_at": 1517505319,
        "billing_period": 1,
        "billing_period_unit": "month",
        "charged_items": [
            {
                "item_price_id": "ssl-charge-USD",
                "last_charged_at": 1516295719,
                "object": "charged_item"
            },
            {..}
        ],
        "created_at": 1517505319,
        "currency_code": "USD",
        "current_term_end": 1614018600,
        "current_term_start": 1517505319,
        "customer_id": "__test__8asukSOXdvWPP6",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdvbfP9",
        "mrr": 0,
        "next_billing_at": 1614018600,
        "object": "subscription",
        "resource_version": 1517505319739,
        "started_at": 1517505319,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "updated_at": 1517505319
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer-id}/import_for_items

exhausted_coupon_ids[[0..n]][0..n]

optional, list of string

Specifies the IDs of coupons to be marked as exhausted. This parameter accepts a list of IDs, which must correspond to coupons with a duration_type of one_time. Ensure that the IDs included in this parameter do not match any IDs provided in the coupon_ids parameter.

id[]

optional, string, max chars=50

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.

trial_end[]

optional, timestamp(UTC) in seconds

End of the trial period for the subscription. This overrides the trial period set for the plan-item. The value must be later than start_date. Set it to 0 to have no trial period.

billing_cycles[]

optional, integer, min=0

The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan-item price is used.

net_term_days[]

optional, integer

Defines Net D for the subscription. Net D is the number of days within which any invoice raised for the subscription must be paid.

If a value is provided: Net D is set explicitly for the subscription to the value provided. The value must be one among those defined in the site configuration.
If not provided: The attribute is not set and therefore not returned by the API. In this case, when an invoice is raised - whether now or later - the net_term_days defined at the customer level is considered. .

start_date[]

optional, timestamp(UTC) in seconds

The date/time at which the subscription is to start or has started. If not provided, the subscription starts immediately.

auto_collection[]

optional, enumerated string

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.

Possible values are

po_number[]

optional, string, max chars=100

Purchase order number for this subscription.

coupon_ids[[0..n]][0..n]

optional, list of string

List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes .

payment_source_id[]

optional, string, max chars=40

Id of the payment source to be attached to this subscription.

status[]

required, enumerated string

Current state of the subscription.

Possible values are

current_term_end[]

optional, timestamp(UTC) in seconds

End of the current billing term. Subscription is renewed immediately after this. If not given, this will be calculated based on plan billing cycle.

Note:

For subscription status: non_renewing, active, and paused, current_term_end is required.

current_term_start[]

optional, timestamp(UTC) in seconds

Start of the current billing period of the subscription. This is required when the subscription status is paused. When the status is active or non_renewing , it defaults to the current time.

trial_start[]

optional, timestamp(UTC) in seconds

Start of the trial period for the subscription. When not passed, it is assumed to be current time. When passed for a future subscription, it implies that the subscription goes into in_trial when it starts.

cancelled_at[]

optional, timestamp(UTC) in seconds

Time at which subscription was cancelled or is set to be cancelled.

started_at[]

optional, timestamp(UTC) in seconds

Time at which the subscription was started. Is null for future subscriptions as it is yet to be started.

activated_at[]

optional, timestamp(UTC) in seconds

The time at which the subscription was activated. A subscription is "activated" when its status changes from any other, to either active or non_renewing.

The following conditions must be satisfied when passing this parameter:

When status is active, non_renewing, or paused, activated_at must be on or after trial_end or started_at. Additionally, activated_at must be on or before current_term_start.
When status is in_trial, activated_at must precede trial_start

Note:

This parameter should not be provided when passing status as future or cancelled.

pause_date[]

optional, timestamp(UTC) in seconds

When a pause has been scheduled, it is the date/time of scheduled pause. When the subscription is in the paused state, it is the date/time when the subscription was paused.

resume_date[]

optional, timestamp(UTC) in seconds

For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

contract_term_billing_cycle_on_renewal[]

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

create_current_term_invoice[]

optional, boolean, default=false

Set as true if you want an invoice to be created for the subscription.

The invoice will be created for the subscription only if it has an active or non_renewing status.
The period of the invoice is from current_term_start to current_term_end.
The invoice will not be generated if the subscription amount is zero dollars (for that period) and 'Hide Zero Value Line Items' option is enabled in site settings.

invoice_notes[]

optional, string, max chars=2000

A customer-facing note added to all invoices associated with this subscription. This note is 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 .

cancel_reason_code[]

optional, string, max chars=100

create_pending_invoices[]

optional, boolean

When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
When you need to inspect all charges before closing invoices for this subscription. Applicable only when Metered Billing is enabled for the site .

auto_close_invoices[]

optional, boolean

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[id]

optional, string, max chars=50

contract_term[created_at]

optional, timestamp(UTC) in seconds

contract_term[contract_start]

optional, timestamp(UTC) in seconds

contract_term[billing_cycle]

optional, integer, min=0

contract_term[total_amount_raised]

optional, in cents, default=0, min=0

contract_term[total_amount_raised_before_tax]

optional, in cents, default=0, min=0

contract_term[action_at_term_end]

optional, enumerated string, default=renew

Possible values are

contract_term[cancellation_cutoff_period]

optional, integer, default=0

transaction

Parameters for transaction
pass parameters as transaction[<param name>]

transaction[amount]

optional, in cents, min=0

transaction[payment_method]

optional, enumerated string

Possible values are

transaction[reference_number]

optional, string, max chars=100

transaction[date]

optional, timestamp(UTC) in seconds

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

shipping_address[first_name]

optional, string, max chars=150

shipping_address[last_name]

optional, string, max chars=150

shipping_address[email]

optional, string, max chars=70

shipping_address[company]

optional, string, max chars=250

shipping_address[phone]

optional, string, max chars=50

shipping_address[line1]

optional, string, max chars=150

shipping_address[line2]

optional, string, max chars=150

shipping_address[line3]

optional, string, max chars=150

shipping_address[city]

optional, string, max chars=50

shipping_address[state_code]

optional, string, max chars=50

shipping_address[state]

optional, string, max chars=50

shipping_address[zip]

optional, string, max chars=20

shipping_address[country]

optional, string, max chars=50

shipping_address[validation_status]

optional, enumerated string, default=not_validated

Possible values are

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

required, string, max chars=100

subscription_items[quantity][0..n]

optional, integer, min=1

subscription_items[quantity_in_decimal][0..n]

optional, string, max chars=33

subscription_items[unit_price][0..n]

optional, in cents, min=0

subscription_items[unit_price_in_decimal][0..n]

optional, string, max chars=39

subscription_items[billing_cycles][0..n]

optional, integer, min=0

subscription_items[trial_end][0..n]

optional, timestamp(UTC) in seconds

subscription_items[service_period_days][0..n]

optional, integer, min=1, max=730

subscription_items[charge_on_event][0..n]

optional, enumerated string

Possible values are

subscription_items[charge_once][0..n]

optional, boolean

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[apply_on][0..n]

optional, enumerated string

Possible values are

discounts[duration_type][0..n]

required, enumerated string, default=forever

Possible values are

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0

discounts[amount][0..n]

optional, in cents, min=0

discounts[period][0..n]

optional, integer, min=1

discounts[period_unit][0..n]

optional, enumerated string

Possible values are

discounts[included_in_mrr][0..n]

optional, boolean

discounts[item_price_id][0..n]

optional, string, max chars=100

discounts[quantity][0..n]

optional, integer, min=1

charged_items

Parameters for charged_items. Multiple charged_items can be passed by specifying unique indices.
pass parameters as charged_items[<param name>][<idx:0..n>]

charged_items[item_price_id][0..n]

optional, string, max chars=100

charged_items[last_charged_at][0..n]

optional, timestamp(UTC) in seconds

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[item_price_id][0..n]

optional, string, max chars=100

item_tiers[starting_unit][0..n]

optional, integer, min=1

item_tiers[ending_unit][0..n]

optional, integer

item_tiers[price][0..n]

optional, in cents, default=0, min=0

item_tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[price_in_decimal][0..n]

optional, string, max chars=39

item_tiers[pricing_type][0..n]

optional, enumerated string

Possible values are

item_tiers[package_size][0..n]

optional, integer, min=1

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

Try in API Explorer

Assigns the payment source and sets auto collection state for the subscription.

When you don't pass any input param for this API, payment source and auto collection for the subscription will be the same as the customer's default settings.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdw1vPR/override_billing_profile \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__8asukSOXdwAuPa" \
     -d auto_collection="ON"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "payment_source": {
        "card": {
            "brand": "american_express",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "not_known",
            "iin": "378282",
            "last4": "0005",
            "masked_number": "***********0005",
            "object": "card"
        },
        "created_at": 1612890921,
        "customer_id": "__test__8asukSOXdvwzPO",
        "deleted": false,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__8astDSOXdqwz1y",
        "id": "pm___test__8asukSOXdwAuPa",
        "object": "payment_source",
        "reference_id": "tok___test__8asukSOXdwAqPZ",
        "resource_version": 1612890921000,
        "status": "valid",
        "type": "card",
        "updated_at": 1612890921
    },
    "subscription": {
        "activated_at": 1612890921,
        "auto_collection": "on",
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890921,
        "currency_code": "USD",
        "current_term_end": 1615310121,
        "current_term_start": 1612890921,
        "customer_id": "__test__8asukSOXdvwzPO",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdw1vPR",
        "mrr": 0,
        "next_billing_at": 1615310121,
        "object": "subscription",
        "payment_source_id": "pm___test__8asukSOXdwAuPa",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890921000,
        "started_at": 1612890921,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "updated_at": 1612890921
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/override_billing_profile

payment_source_id[]

optional, string, max chars=40

Unique identifier of the payment source to be attached to this subscription.

auto_collection[]

optional, enumerated string

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.

Possible values are

subscription

always returned
Resource object representing subscription

payment_source

optional
Resource object representing payment_source

Try in API Explorer

Deletes a specified subscription.

This operation schedules the subscription resource for deletion, and it is permanently deleted after a few minutes. If you wish to retain the subscription data but stop further renewals, consider canceling or pausing the subscription instead.

Prerequisites & Constraints

There must not be any invoices belonging to this subscription that have allocations from credit notes not belonging to this subscription.
There must not be any credit notes belonging to this subscription that have been allocated to invoices not belonging to this subscription.
There should not be any consolidated invoices for the customer with lines belonging to this subscription.

Impacts

Invoices

All the invoices belonging to this subscription are deleted.

Credit notes

All the credit notes belonging to this subscription are deleted.

Transactions

All the transactions belonging to this subscription are deleted.

Usages

All usages belonging to this subscription are deleted.

Usage events

Deleting a subscription does not delete the associated usage events.

Reporting

The numbers in the following reports are modified when a subscription is deleted: Payments, New Revenue, Signups, Activations, Cancellations, and Refunds.

Integrations

Deleting a subscription may affect any third-party integrations you may have with Chargebee Billing. Review all integrations to assess the impact before proceeding.

Implementation Notes

Before deleting a subscription, ensure the following:

Retrieve all the invoices for this subscription using the List invoices API. For each invoice, look up all the applied credit notes (credit_note.applied_credits.cn_id). For all such credit notes, check if the associated subscription (credit_note.subscription_id) is this subscription. If not, use the Remove credit note from an invoice API to remove the credit note allocation.
Retrieve all the credit notes for this subscription using the List credit notes API. For each credit note, look up all the invoice allocations (credit_note.allocations.invoice_id). For all such invoices, check if the associated subscription (invoice.subscription_id) is this subscription. If not, use the Remove credit note from an invoice API to remove the allocation.
Delete any consolidated invoices containing lines belonging to this subscription.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdv6kOj/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890917,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdv0dOg",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890917000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890917
    },
    "subscription": {
        "activated_at": 1612890917,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890917,
        "currency_code": "USD",
        "current_term_end": 1615310117,
        "current_term_start": 1612890917,
        "customer_id": "__test__8asukSOXdv0dOg",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890917,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdv6kOj",
        "mrr": 0,
        "next_billing_at": 1615310117,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890918000,
        "started_at": 1612890917,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890918
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/delete

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Try in API Explorer

Use this API to pause an active or non-renewing subscription. When a subscription is paused, it does not renew, and Chargebee does not generate renewal invoices for it. This allows you to temporarily suspend a customer's service without canceling the subscription.

Prerequisites & Constraints

The Pause Subscription feature must be enabled for the site.
Only subscriptions in the active or non_renewing state can be paused.
Subscriptions with active contract_terms cannot be paused.

Impacts

Subscription

If the pause_option parameter is set to immediately, the subscription's status changes to paused. The next_billing_at, pause_date, and resume_date values are updated based on the input parameters.

Unbilled Charges

If the subscription has unbilled charges and is paused immediately, you can choose to leave the charges unbilled or invoice them. If invoiced, Chargebee attempts payment collection based on the customer's auto-collection settings. If payment fails or auto-collection is not enabled, the invoice is marked as unpaid.

Use the unbilled_charges_handling parameter to set your preference.

Dunning

If the subscription has unpaid invoices in dunning and is paused immediately, you can choose to either stop or continue the dunning process.

Use the invoice_dunning_handling parameter to set your preference.

Scheduled Ramps

Any future subscription ramps (such as price or quantity changes) effective on or after the pause date are automatically deleted.

Advanced Invoices

If the subscription has an advance invoice, Chargebee creates an adjustment credit note if the invoice is unpaid or in a payment-due state. If the invoice is already paid, a refundable credit note is created.

Implementation Notes

Before calling this API, perform the following checks:

Confirm that the subscription status is active or non_renewing. If it isn't, the API returns an invalid_state_for_pause error.
Check the has_scheduled_changes attribute. If true, either remove the scheduled changes before calling the API or avoid the operation. Otherwise, the API returns an operation_failed error.
Ensure that the contract_term attribute is not present, or if it is present, that contract_term.status is not active. Otherwise, the API returns an invalid_request error.
If a subscription is in the non_renewing state and you want to set the pause date to a future date, the pause date must be earlier than the cancellation date. If you specify a resume date, it must also be earlier than the cancellation date.

Sample Request

Try in API Explorer

Only for Java

Only for Java

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdwKMPo/pause \
     -u {site_api_key}:\
     -d pause_option="END_OF_TERM"

curl  https://{site}.chargebee.com/api/v2/subscriptions/6o0iPUoHhcNGcI/pause \
     -u {site_api_key}:\
     -d pause_option="BILLING_CYCLES" \
     -d skip_billing_cycles=1

curl  https://{site}.chargebee.com/api/v2/subscriptions/6o0iPUoHhcNGcI/pause \
     -u {site_api_key}:\
     -d pause_option="SPECIFIC_DATE" \
     -d pause_date=1751241600

curl  https://{site}.chargebee.com/api/v2/subscriptions/6o0iPUoHhcNGcI/pause \
     -u {site_api_key}:\
     -d pause_option="IMMEDIATELY" \
     -d resume_date=1751328000

copy

Click to Copy

Pauses the subscription on end of term.

Pause subscription at the end of the term and resume after one billing cycle.

Pause subscription on a specific date.

Pause subscription immediately and resume on a specific date.

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890922,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdwFjPl",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890922000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890922
    },
    "subscription": {
        "activated_at": 1612890922,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890922,
        "currency_code": "USD",
        "current_term_end": 1615310122,
        "current_term_start": 1612890922,
        "customer_id": "__test__8asukSOXdwFjPl",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890922,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdwKMPo",
        "mrr": 0,
        "object": "subscription",
        "pause_date": 1615310122,
        "remaining_billing_cycles": 1,
        "resource_version": 1612890923000,
        "started_at": 1612890922,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890923
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/pause

pause_option[]

optional, enumerated string

List of options to pause the subscription.

Possible values are

pause_date[]

optional, timestamp(UTC) in seconds

Date on which the subscription will be paused. Applicable when specific_date option is chosen in the pause_option field. For non-renewing subscriptions, pause_date should be before the cancellation date.

unbilled_charges_handling[]

optional, enumerated string

Applicable when unbilled charges are present for the subscription and pause_option is set as immediately. Note: On the invoice raised, an automatic charge is attempted on the payment method available, if customer's auto-collection property is set to on.

Possible values are

invoice_dunning_handling[]

optional, enumerated string

Handles dunning for invoices already in the dunning cycle when a subscription is paused. Applicable when pause_option is set as immediately. If invoice is in the dunning cycle, invoice_dunning_handing allows you to stop or continue dunning.

Possible values are

skip_billing_cycles[]

optional, integer, min=1

The number of subscription billing cycles that will be skipped. The subscription resumes after the set number of billing cycles have been skipped. This is applicable only when the value of of pause_option is billing_cycles .

resume_date[]

optional, timestamp(UTC) in seconds

For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned. For non-renewing subscriptions,resume_date should be before the cancellation date.

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charges

credit_notes

optional
Resource object representing credit_notes

Try in API Explorer

Cancels the specified subscription.

Prerequisites & Constraints

The subscription status must not be cancelled or transferred.
If the subscription has a contract term, specify contract_term_cancel_option instead of cancel_option.

Impacts

Subscription

The cancellation date-time depends on the provided parameters:
- When the subscription does not have a contract term, use cancel_option.
- When the subscription has a contract term, use contract_term_cancel_option.
The subscription status changes to cancelled when canceled.
If cancel_option is specified as end_of_term, or if contract_term_cancel_option is specified as end_of_subscription_billing_term, the subscription status changes to non_renewing and the subscription billing_cycles becomes 0.

Contract Terms

The contract term and subscription are canceled together based on the provided contract_term_cancel_option.

Ramps

If ramps are scheduled for the subscription, this operation deletes any ramps that are set to become effective on or after the subscription's cancellation date-time.

Implementation Notes

Before calling this API, perform the following checks:

Confirm that the subscription status is not cancelled or transferred.
If the subscription has a contract term, pass contract_term_cancel_option instead of cancel_option.

Use Cases

Cancel a subscription with a contract term

If the subscription has a contract term, you can use the following parameters with this API:

contract_term_cancel_option
cancel_at
credit_option_for_current_term_charges
unbilled_charges_option
account_receivables_handling
refundable_credits_handling

Sample Request

Try in API Explorer

Only for Java

Only for Java

Only for Java

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y28bL9/cancel_for_items \
     -u {site_api_key}:\
     -d end_of_term=true

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y29FDJ/cancel_for_items \
     -u {site_api_key}:\
     -d credit_option_for_current_term_charges="PRORATE" \
     -d end_of_term=false

curl  https://{site}.chargebee.com/api/v2/subscriptions/6o2M5UhE6aJp17C/cancel_for_items \
     -u {site_api_key}:\
     -d cancel_option="IMMEDIATELY" \
     -d unbilled_charges_option="INVOICE" \
     -d cancel_reason_code="Product Unsatisfactory"

curl  https://{site}.chargebee.com/api/v2/subscriptions/6ohkiUdK5kM410A/cancel_for_items \
     -u {site_api_key}:\
     -d cancel_option="SPECIFIC_DATE" \
     -d cancel_at=1758931200 \
     -d credit_option_for_current_term_charges="PRORATE" \
     -d unbilled_charges_option="INVOICE"

curl  https://{site}.chargebee.com/api/v2/subscriptions/6ohkiUdGUwfmK2/cancel_for_items \
     -u {site_api_key}:\
     -d contract_term_cancel_option="END_OF_CONTRACT_TERM" \
     -d cancel_reason_code="Other"

copy

Click to Copy

Cancels the subscription after the term ends.

Cancels the subscription immediately with proration credits issued.

Cancel the subscription immediately and invoice all unbilled charges for it.

Cancel a subscription on a specific date, create credits for the unused period, and invoice any unbilled charges.

Schedule the subscription to cancel at the end of the contract term.

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890907,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdsPqLk",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890907000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890907
    },
    "subscription": {
        "activated_at": 1612890907,
        "billing_period": 1,
        "billing_period_unit": "month",
        "cancelled_at": 1615310107,
        "created_at": 1612890907,
        "currency_code": "USD",
        "current_term_end": 1615310107,
        "current_term_start": 1612890907,
        "customer_id": "__test__8asukSOXdsPqLk",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890907,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdsV6Ln",
        "mrr": 0,
        "object": "subscription",
        "remaining_billing_cycles": 0,
        "resource_version": 1612890908000,
        "started_at": 1612890907,
        "status": "non_renewing",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 0,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890908
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/cancel_for_items

cancel_option[]

optional, enumerated string

If the subscription does not have a contract term:

Determines when to cancel the subscription.

If the subscription has a contract term:

This parameter is not applicable.

Possible values are

end_of_term[]

optional, boolean, default=false

(Deprecated) Use cancel_option instead. Applicable only when the subscription does not have contract terms. Set this to true if you want to cancel the subscription at the end of the current subscription billing cycle. The subscription status changes to non_renewing.

cancel_at[]

optional, timestamp(UTC) in seconds

If the subscription does not have a contract term:

Specifies the date and time when the subscription should be canceled. Do not use this parameter when end_of_term is set to true.

If the subscription has a contract term:

Applicable only when contract_term_cancel_option is specific_date. Specifies the date and time to cancel the subscription and contract term.

Backdating

You can set a past date to backdate the cancellation. Backdating is allowed only if the following conditions are met:

Backdating is enabled for subscription cancellation.
The current date does not exceed the backdating limit configured in Chargebee Billing.
The date is on or after the current_term_start.
The date is on or after the most recent change involving:
- Addition/change/removal of plan or addon item prices.
- Addition of charge item prices.
The date is not more than one billing period into the past. For example, if the plan's billing period is two months and today is April 14, cancel_at cannot be earlier than February 14.

credit_option_for_current_term_charges[]

optional, enumerated string

If the subscription does not have a contract term:

Specifies how to handle credits for current term charges when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.

If the subscription has a contract term:

Specifies how to handle credits for current term charges when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.

Possible values are

unbilled_charges_option[]

optional, enumerated string

If the subscription does not have a contract term:

Specifies how to handle unbilled charges when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.

If the subscription has a contract term:

Specifies how to handle unbilled charges when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.

Possible values are

account_receivables_handling[]

optional, enumerated string

If the subscription does not have a contract term:

Specifies how to handle past due invoices when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.

If the subscription has a contract term:

Specifies how to handle past due invoices when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.

Possible values are

refundable_credits_handling[]

optional, enumerated string

If the subscription does not have a contract term:

Specifies how to handle refundable credits when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.

If the subscription has a contract term:

Specifies how to handle refundable credits when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.

Possible values are

contract_term_cancel_option[]

optional, enumerated string

Required when the subscription has a contract term. Determines when to cancel the subscription along with the contract term.

Possible values are

invoice_date[]

optional, timestamp(UTC) in seconds

The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices is true , and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

invoice_date must be in the past.
invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
It is not earlier than cancel_at. .

cancel_reason_code[]

optional, string, max chars=100

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

optional, string, max chars=100

subscription_items[quantity][0..n]

optional, integer, min=1

subscription_items[quantity_in_decimal][0..n]

optional, string, max chars=33

subscription_items[unit_price][0..n]

optional, in cents, min=0

subscription_items[unit_price_in_decimal][0..n]

optional, string, max chars=39

subscription_items[service_period_days][0..n]

optional, integer, min=1, max=730

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charges

credit_notes

optional
Resource object representing credit_notes

Try in API Explorer

Note: This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.

This API is used to resume a paused subscription. On resumption the subscription will be activated and any applicable charges will be initiated.

You could schedule the resumption by passing specific_date parameter in resume_option. If scheduled, the subscription will be resumed on the specific_date and moved to Active state.

For in-term resumption, unless there are scheduled changes, unbilled charges will not be charged.

What is an "in-term resumption"? An "in-term resumption" is when the pause and resumption happens within the billing term of the subscription.

Example : A subscription was billed from 1st to 31st of a month. It was paused on the 20th and resumed before 31st. This is an in-term resumption.

UNPAID INVOICES

Specifying unpaid_invoices allows you to close invoices of the subscription which have amounts due. The invoices are chosen for payment collection after applying the available credits and excess payments.

If you specify schedule_payment_collection, Chargebee will try to collect payments for overdue invoices, provided that auto_collection is enabled for the subscription. The available payment method is charged. Upon successful payment, the payment_succeeded event is triggered. If the payment collection fails, no further attempts will be made to collect payment on the invoices.

Note: If the invoices of the subscription are consolidated, and any of the subscriptions in the consolidated invoice are cancelled, these invoices will not be selected for collection.

Warning

This API will return an error when multi-frequency billing is enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdznTS0/resume \
     -u {site_api_key}:\
     -d resume_option="IMMEDIATELY" \
     -d unpaid_invoices_handling="SCHEDULE_PAYMENT_COLLECTION"

copy

Click to Copy

Resumes a subscription immediately by scheduling payment collection for unpaid invoices.

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890935,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdziiRx",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890935000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890935
    },
    "subscription": {
        "activated_at": 1612890935,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890935,
        "currency_code": "USD",
        "current_term_end": 1615310135,
        "current_term_start": 1612890935,
        "customer_id": "__test__8asukSOXdziiRx",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890935,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdznTS0",
        "mrr": 0,
        "next_billing_at": 1615310135,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890936000,
        "started_at": 1612890935,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890936
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/resume

resume_option[]

optional, enumerated string

List of options to resume the subscription.

Possible values are

resume_date[]

optional, timestamp(UTC) in seconds

Date on which the subscription will be resumed. Applicable when resume_option is set as 'specific_date'.

charges_handling[]

optional, enumerated string

Applicable when charges get added during this operation and resume_option is set as 'immediately'. Allows to raise invoice immediately or add them to unbilled charges.

Possible values are

unpaid_invoices_handling[]

optional, enumerated string

Applicable when the subscription has past due invoices and resume_option is set as 'immediately'. Allows to collect past due invoices or retain them as unpaid. If 'schedule_payment_collection' option is chosen in this field, remaining refundable credits and excess payments are applied. Note: The payment collection attempt will be asynchronous.

Possible values are

payment_initiator[]

optional, enumerated string

The type of initiator to be used for the payment request triggered by this operation.

Possible values are

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

optional, string, max chars=150

payment_intent[gateway_account_id]

required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

optional, string, max chars=65k

payment_intent[payment_method_type]

optional, enumerated string

Possible values are

payment_intent[reference_id]

optional, string, max chars=65k

payment_intent[additional_information]

optional, jsonobject

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charges

Try in API Explorer

If the subscription is in Active or Non Renewing state and is also scheduled to pause at the end_of_term/specific_date, this API can be used to remove the scheduled pause.

Warning This API will return an error when multi-frequency billing is enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdz1ERW/remove_scheduled_pause \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890932,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdywZRT",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890932000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890932
    },
    "subscription": {
        "activated_at": 1612890932,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890932,
        "currency_code": "USD",
        "current_term_end": 1615310132,
        "current_term_start": 1612890932,
        "customer_id": "__test__8asukSOXdywZRT",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890932,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdz1ERW",
        "mrr": 0,
        "next_billing_at": 1615310132,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890933000,
        "started_at": 1612890932,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890933
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/remove_scheduled_pause

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Try in API Explorer

If the subscription is in Paused state and is scheduled to resume on a specific_date, this API can be used to remove the scheduled resumption. When the scheduled resumption is removed, the subscription will remain Paused.

Warning This API will return an error when multi-frequency billing is enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdzOFRl/remove_scheduled_resumption \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890933,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdzJFRi",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890933000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890933
    },
    "subscription": {
        "activated_at": 1612890934,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890934,
        "currency_code": "USD",
        "current_term_end": 1615310134,
        "current_term_start": 1612890934,
        "customer_id": "__test__8asukSOXdzJFRi",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890934,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdzOFRl",
        "mrr": 0,
        "object": "subscription",
        "pause_date": 1612890934,
        "remaining_billing_cycles": 1,
        "resource_version": 1612890935000,
        "started_at": 1612890934,
        "status": "paused",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890935
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/remove_scheduled_resumption

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Try in API Explorer

Moves a subscription from one customer to another asynchronously. All related resources such as unbilled_charge, invoice, credit_note, and transaction are also moved to the new customer.

After moving, Chargebee adds a comment to the original customer resource to document the move, including the to_customer_id and the ids of all the resources transferred to the destination customer.

Warning

If auto_collection is on, it might fail after this operation. Refer to the warning in copy_payment_source for details.
During the time that it takes for the operation to complete, no modifications are allowed on the source customer, the destination customer, and the subscription.
After moving a subscription, the change does not reflect in Chargebee Billing's accounting integrations or in Chargebee RevRec.
This API will return an error when multi-frequency billing is enabled.

Prerequisites

The subscription should not be part of a customer resource that is within an account hierarchy relationship.
There must be no invoices with the statuses payment_due, pending, or posted associated with the subscription.
The site must have consolidated invoicing disabled.
There should be no consolidated invoices linked to the subscription.
No credit_note resources with the statuses adjusted or refund_due should be associated with the subscription.
With muti business entity (MBE) enabled on your site, moving a subscription to a customer belonging to another business entity is not allowed.

Asynchronous operation

If the above prerequisites are met, the API call returns a 200 OK response containing the subscription resource as is. However, the actual move operation can take up to five minutes to complete.

To know whether the operation was successful, we recommend that you watch for the subscription_changed event and see if subscription.customer_id has changed.

Limitations

Subscriptions cannot be moved on the same calendar day as their renewal. For instance, if a renewal is scheduled for 2 PM on April 10, 2024, the endpoint is restricted from 12 AM on April 10, 2024, until the renewal is completed.
After moving a subscription, the change does not reflect in Chargebee Billing's accounting integrations or in Chargebee RevRec.

Note: Resources linked to the original customer such as unbilled_charge , invoice , credit_note , and transaction but not linked to the subscription being moved, are not moved to the destination customer by this operation.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdwKMPo/move \
     -u {site_api_key}:\
     -d to_customer_id="__test__KyVnHhSBWlCdz2cv" \
     -d copy_payment_source=true

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "subscription": {
        "id": "__test__8asukSOXdwKMPo",
        "billing_period": 1,
        "billing_period_unit": "month",
        "customer_id": "fromcustomer",
        "status": "active",
        "current_term_start": 1710867589,
        "current_term_end": 1713545989,
        "next_billing_at": 1713545989,
        "created_at": 1710867589,
        "started_at": 1710867589,
        "activated_at": 1710867589,
        "created_from_ip": "44.196.151.224",
        "updated_at": 1710867590,
        "has_scheduled_changes": false,
        "channel": "web",
        "resource_version": 1710867590342,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "subscription_items": [
            {
                "item_price_id": "Basic-USD-Monthly",
                "item_type": "plan",
                "quantity": 1,
                "quantity_in_decimal": "1",
                "unit_price": 1000,
                "unit_price_in_decimal": "10.00",
                "amount": 1000,
                "amount_in_decimal": "10.00",
                "free_quantity": 0,
                "free_quantity_in_decimal": "0",
                "object": "subscription_item"
            },
            {..}
        ],
        "due_invoices_count": 0,
        "mrr": 0,
        "has_scheduled_advance_invoices": false
    },
    "customer": {
        "id": "fromcustomer",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1709740187,
        "created_from_ip": "44.196.151.224",
        "taxability": "taxable",
        "updated_at": 1710867570,
        "pii_cleared": "active",
        "channel": "web",
        "resource_version": 1710867570674,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "unbilled_charges": 0,
        "preferred_currency_code": "USD",
        "mrr": 0,
        "primary_payment_source_id": "pm_15rQxzU7UHyFl3Z",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_15rQxzU7UHyFB3Y",
            "gateway": "chargebee",
            "gateway_account_id": "gw_15olFFT46Yzjv61q",
            "status": "valid"
        }
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_15olFFT46Yzjv61q",
        "iin": "510510",
        "last4": "5100",
        "card_type": "mastercard",
        "funding_type": "prepaid",
        "expiry_month": 12,
        "expiry_year": 2025,
        "created_at": 1710867570,
        "updated_at": 1710867570,
        "ip_address": "44.196.151.224",
        "resource_version": 1710867570665,
        "object": "card",
        "masked_number": "************5100",
        "customer_id": "fromcustomer",
        "payment_source_id": "pm_15rQxzU7UHyFl3Z"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/move

to_customer_id[]

required, string, max chars=50

Specifies the unique ID of the customer resource to which the subscription will be moved.

Note: If there are multiple business entities , the customer.business_entity_id of the destination customer must match the subscription.business_entity_id.

copy_payment_source[]

optional, boolean, default=false

When true: If the subscription has an associated payment_source:

A new duplicate copy of the payment_source resource is created.
This new copy of the payment source is linked to the subscription and the destination customer.

Note: Deleting any copy of the payment_source also deletes the other copies and the details stored at the payment gateway.

When false: No new payment source is created for the subscription. Moreover, if a payment_source is already linked to the subscription, it gets removed, meaning the subscription.payment_source_id is cleared.

Warning: When copy_payment_source is false and if subscription.auto_collection is enabled, auto-collection will fail, in turn preventing subscription renewal. To prevent auto-collection failure, link a payment source to the subscription after this operation.

subscription

always returned
Resource object representing subscription

Subscription billing frequencies

Item price compatibility in a subscription

Tax provider fields

Sample subscription [ JSON ]

API Index URL

Model Class

Subscription attributes

Consent Fields for Subscription

Custom Fields for Subscription

Create subscription for Items ¶

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 subscriptions ¶

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

List contract terms for a subscription ¶

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

List discounts for a subscription ¶

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 subscription ¶

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 with scheduled changes ¶

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

Remove scheduled changes ¶

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

Remove scheduled cancellation ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.