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:

The charges in a subscription are billed via invoices.

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

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.

See also
  • Purchase: a resource that represents multiple subscriptions bought together by a customer.

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 GET

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

Model Class

id
string, max chars=50
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
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
futureThe subscription is scheduled to start at a future date.in_trialThe subscription is in trial.activeThe subscription is active and will be charged for automatically based on the items in it.non_renewingThe subscription will be canceled at the end of the current term.
Show all values[+]
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
site_defaultThe action configured for the site at the time when the trial ends, takes effect. This is the default value when trial_end_action is not defined for the plan.plan_defaultThe action configured for the site at the time when the trial ends, takes effect. This is the default value when trial_end_action is defined for the plan.activate_subscriptionThe subscription activates and charges are raised for non-metered items.cancel_subscriptionThe subscription cancels.
Show all values[+]
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 futuresubscriptions 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
not_paidNot Paidno_cardNo Cardfraud_review_failedFraud Review Failednon_compliant_eu_customerNon Compliant EU Customer
Show all values[+]
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
If true, there are subscription changes scheduled on 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
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.
channel
optional, enumerated string
The subscription channel this object originated from and is maintained in.
Possible values are
webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.play_storeThe object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.
Show all values[+]
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
This attribute represents the identifier of the most recent version of the subscriptions resource. When interacting with our API, the active_id ensures you are always referencing the current and most up-to-date version of the subscriptions resource. This mechanism is in place to maintain consistent external references and data integrity across business entity changes and updates. active_id is present on the resource after the resource is transferred to the destination business entity and it will refer to the most recent version of the resource. Learn more about the customer transfer feature and setup.

Note:

  • If active_id and id of the subscription are the same, then it is the most recent version of the resource.
  • If active_id and id of the subscription are different, then it is a transferred resource.
  • If active_id is not present, then the resource is not transferred and there are no business entity-related changes.

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.
metadata
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. 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
dayCharge based on day(s)weekCharge based on week(s)monthCharge based on month(s)yearCharge based on year(s)
Show all values[+]
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
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.
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.
optional, list of item_tier
The pricing details of subscription_items which have pricing_model as tiered, volume or stairstep.
charged_items
Show attributes [+]
optional, list of charged_item
List of event based charge items that have already been charged.
optional, list of coupon
List of coupons for this subscription
shipping_address
Show attributes [+]
optional, shipping_address
Shipping address for the subscription.
referral_info
Show attributes [+]
optional, referral_info
Referral details if exists for the subscription
contract_term
Show attributes [+]
optional, contract_term
Contract terms for this subscription
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.
id id
string, max chars=50
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
currency_code currency_code
string, max chars=3
The currency code (ISO 4217 format) of the subscription
start_date start_date
optional, timestamp(UTC) in seconds
Applicable only for 'future' subscriptions. The scheduled start time of the subscription.
trial_end 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 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 po_number
optional, string, max chars=100
Purchase order number for this subscription.
plan_quantity_in_decimal 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 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 customer_id
string, max chars=50
Identifier of the customer with whom this subscription is associated.
status status
enumerated string
Current state of the subscription
trial_start 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 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.
current_term_start current_term_start
optional, timestamp(UTC) in seconds
Start of the current billing period of the subscription.
current_term_end 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 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 created_at
optional, timestamp(UTC) in seconds
The time at which the subscription was created.
started_at started_at
optional, timestamp(UTC) in seconds
Time at which the subscription was started. Is null for futuresubscriptions as it is yet to be started.
activated_at 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 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 override_relationship
optional, boolean
If true, ignores the hierarchy relationship and uses customer as payment and invoice owner.
pause_date 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 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 cancelled_at
optional, timestamp(UTC) in seconds
Time at which subscription was cancelled or is set to be cancelled.
cancel_reason cancel_reason
optional, enumerated string
The reason for canceling the subscription. Set by Chargebee automatically.
created_from_ip 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 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 updated_at
optional, timestamp(UTC) in seconds
Timestamp indicating when the item was last updated.
has_scheduled_advance_invoices has_scheduled_advance_invoices
boolean, default=false
The subscription has an advance invoicing schedule.
has_scheduled_changes has_scheduled_changes
boolean, default=false
If true, there are subscription changes scheduled on next renewal.
payment_source_id 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 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 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 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.
channel channel
optional, enumerated string
The subscription channel this object originated from and is maintained in.
net_term_days 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 active_id
optional, string, max chars=50
This attribute represents the identifier of the most recent version of the subscriptions resource. When interacting with our API, the active_id ensures you are always referencing the current and most up-to-date version of the subscriptions resource. This mechanism is in place to maintain consistent external references and data integrity across business entity changes and updates. active_id is present on the resource after the resource is transferred to the destination business entity and it will refer to the most recent version of the resource. Learn more about the customer transfer feature and setup.

Note:

  • If active_id and id of the subscription are the same, then it is the most recent version of the resource.
  • If active_id and id of the subscription are different, then it is a transferred resource.
  • If active_id is not present, then the resource is not transferred and there are no business entity-related changes.

due_invoices_count 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 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 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 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 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 base_currency_code
optional, string, max chars=3
The currency code (ISO 4217 format) of the site’s base currency.
invoice_notes 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.
metadata
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 deleted
boolean
Indicates that the subscription has been deleted. You can retrieve a deleted subscription using the list operation.
changes_scheduled_at 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 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 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 free_period_unit
optional, enumerated string
Defines additional free period in association with the billing period.
create_pending_invoices 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 auto_close_invoices
optional, boolean
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.
business_entity_id 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
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.

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.

See also
  • Create a purchase: an operation that creates a purchase representing multiple subscriptions bought together by a customer.

Notes

Sample Request
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

Sample Response [ JSON ]

Show more...
{
    "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

Method

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
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
Show all values[+]
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
immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
Show all values[+]
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
dayCharge based on day(s)weekCharge based on week(s)monthCharge based on month(s)yearCharge based on year(s)
Show all values[+]
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

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
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.
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
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
site_defaultThe action configured for the site at the time when the trial ends, takes effect. This is the default value when trial_end_action is not defined for the plan.plan_defaultThe action configured for the site at the time when the trial ends, takes effect. This is the default value when trial_end_action is defined for the plan.activate_subscriptionThe subscription activates and charges are raised for non-metered items.cancel_subscriptionThe subscription cancels.
Show all values[+]
payment_initiator[]
optional, enumerated string
The type of initiator to be used for the payment request triggered by this operation.
Possible values are
customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant
Show all values[+]
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
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
Show all values[+]
statement_descriptor[descriptor]
optional, string, max chars=65k
statement_descriptor[additional_info]
optional, string, max chars=65k
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
cardcardidealidealsofortsofortbancontactbancontact
Show all values[+]
payment_intent[reference_id]
optional, string, max chars=65k
payment_intent[additional_information]
optional, jsonobject
contract_term[action_at_term_end]
optional, enumerated string
Possible values are
renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
  • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.
    Show all values[+]
    contract_term[cancellation_cutoff_period]
    optional, integer, default=0
    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_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active or non-renewing state. Also includes reactivations of canceled subscriptions.
    Show all values[+]
    subscription_items[charge_once][0..n]
    optional, boolean
    subscription_items[charge_on_option][0..n]
    optional, enumerated string
    Possible values are
    immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event.
    Show all values[+]
    discounts[apply_on][0..n]
    required, enumerated string
    Possible values are
    invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
    Show all values[+]
    discounts[duration_type][0..n]
    required, enumerated string, default=forever
    Possible values are
    one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit.
    Show all values[+]
    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
    dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
    Show all values[+]
    discounts[included_in_mrr][0..n]
    optional, boolean
    discounts[item_price_id][0..n]
    optional, string, max chars=100
    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
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice
    unbilled_charges unbilled_charges
    optional
    Resource object representing unbilled_charges

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    Returns a list of subscriptions meeting all the conditions specified in the filter parameters below.

    Notes

    Sample Request
    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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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. Possible values are :
    Supported operators : is, is_not, starts_with, in, not_in

    Example id[is] = "8gsnbYfsMLds"
    id[is][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    id[is_not][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    id[starts_with][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    id[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    id[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    customer_id[<operator>]
    optional, string filter
    Identifier of the customer with whom this subscription is associated. Possible values are :
    Supported operators : is, is_not, starts_with, in, not_in

    Example customer_id[is] = "8gsnbYfsMLds"
    customer_id[is][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    customer_id[is_not][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    customer_id[starts_with][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    customer_id[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    customer_id[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    item_id[<operator>]
    optional, string filter
    The plan item code. Possible values are :
    Supported operators : is, is_not, starts_with, in, not_in

    Example item_id[is] = "silver"
    item_id[is][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    item_id[is_not][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    item_id[starts_with][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    item_id[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    item_id[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    item_price_id[<operator>]
    optional, string filter
    The plan item price code. Possible values are :
    Supported operators : is, is_not, starts_with, in, not_in

    Example item_price_id[is] = "silver-USD-monthly"
    item_price_id[is][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    item_price_id[is_not][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    item_price_id[starts_with][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    item_price_id[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    item_price_id[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    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"
    status[is][operator]
    optional, enumerated string filter
    Possible values are : future, in_trial, active, non_renewing, paused, cancelled, transferred
    Supported operators :

    Example
    status[is_not][operator]
    optional, enumerated string filter
    Possible values are : future, in_trial, active, non_renewing, paused, cancelled, transferred
    Supported operators :

    Example
    status[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    status[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    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[is][operator]
    optional, enumerated string filter
    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 :

    Example
    cancel_reason[is_not][operator]
    optional, enumerated string filter
    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 :

    Example
    cancel_reason[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    cancel_reason[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    cancel_reason[is_present][operator]
    optional, enumerated string filter
    Possible values are : true, false
    Supported operators :

    Example
    cancel_reason_code[<operator>]
    optional, string filter
    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. Possible values are :
    Supported operators : is, is_not, starts_with, in, not_in

    Example cancel_reason_code[is] = "Not Paid"
    cancel_reason_code[is][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    cancel_reason_code[is_not][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    cancel_reason_code[starts_with][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    cancel_reason_code[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    cancel_reason_code[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    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.
    .
    Possible values are :
    Supported operators : is, is_not, lt, lte, gt, gte, between, is_present

    Example remaining_billing_cycles[is] = "3"
    remaining_billing_cycles[is][operator]
    optional, number filter
    Possible values are :
    Supported operators :

    Example
    remaining_billing_cycles[is_not][operator]
    optional, number filter
    Possible values are :
    Supported operators :

    Example
    remaining_billing_cycles[lt][operator]
    optional, number filter
    Possible values are :
    Supported operators :

    Example
    remaining_billing_cycles[lte][operator]
    optional, number filter
    Possible values are :
    Supported operators :

    Example
    remaining_billing_cycles[gt][operator]
    optional, number filter
    Possible values are :
    Supported operators :

    Example
    remaining_billing_cycles[gte][operator]
    optional, number filter
    Possible values are :
    Supported operators :

    Example
    remaining_billing_cycles[between][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    remaining_billing_cycles[is_present][operator]
    optional, enumerated string filter
    Possible values are : true, false
    Supported operators :

    Example
    created_at[<operator>]
    optional, timestamp(UTC) in seconds filter
    The time at which the subscription was created. Possible values are :
    Supported operators : after, before, on, between

    Example created_at[after] = "1435054328"
    created_at[after][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    created_at[before][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    created_at[on][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    created_at[between][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    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. Possible values are :
    Supported operators : after, before, on, between, is_present

    Example activated_at[after] = "1435054328"
    activated_at[after][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    activated_at[before][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    activated_at[on][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    activated_at[between][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    activated_at[is_present][operator]
    optional, enumerated string filter
    Possible values are : true, false
    Supported operators :

    Example
    next_billing_at[<operator>]
    optional, timestamp(UTC) in seconds filter
    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. Possible values are :
    Supported operators : after, before, on, between

    Example next_billing_at[after] = "1435054328"
    next_billing_at[after][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    next_billing_at[before][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    next_billing_at[on][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    next_billing_at[between][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    cancelled_at[<operator>]
    optional, timestamp(UTC) in seconds filter
    Time at which subscription was cancelled or is set to be cancelled. Possible values are :
    Supported operators : after, before, on, between

    Example cancelled_at[after] = "1435054328"
    cancelled_at[after][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    cancelled_at[before][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    cancelled_at[on][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    cancelled_at[between][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    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"
    has_scheduled_changes[is][operator]
    optional, enumerated string filter
    Possible values are : true, false
    Supported operators :

    Example
    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. Possible values are :
    Supported operators : after, before, on, between

    Example updated_at[after] = "1243545465"
    updated_at[after][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    updated_at[before][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    updated_at[on][operator]
    optional, timestamp(UTC) in seconds filter
    Possible values are :
    Supported operators :

    Example
    updated_at[between][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    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"
    offline_payment_method[is][operator]
    optional, enumerated string filter
    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 :

    Example
    offline_payment_method[is_not][operator]
    optional, enumerated string filter
    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 :

    Example
    offline_payment_method[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    offline_payment_method[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    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"
    auto_close_invoices[is][operator]
    optional, enumerated string filter
    Possible values are : true, false
    Supported operators :

    Example
    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"
    override_relationship[is][operator]
    optional, enumerated string filter
    Possible values are : true, false
    Supported operators :

    Example
    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. Possible values are :
    Supported operators : is, is_not, starts_with

    Example business_entity_id[is] = "business_entity_id"
    business_entity_id[is][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    business_entity_id[is_not][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    business_entity_id[starts_with][operator]
    optional, string, min chars=1 filter
    Possible values are :
    Supported operators :

    Example
    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"
    channel[is][operator]
    optional, enumerated string filter
    Possible values are : web, app_store, play_store
    Supported operators :

    Example
    channel[is_not][operator]
    optional, enumerated string filter
    Possible values are : web, app_store, play_store
    Supported operators :

    Example
    channel[in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    channel[not_in][operator]
    optional, string filter
    Possible values are :
    Supported operators :

    Example
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    next_offset next_offset
    optional, string, max chars=1000
    This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    Retrieves a list of contract term resources for the subscription specified in the path.

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdty0Mv/contract_terms \
         -G  \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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.
    contract_term contract_term
    always returned
    Resource object representing contract_term
    next_offset next_offset
    optional, string, max chars=1000
    This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    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.

    Notes

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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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.
    discount discount
    always returned
    Resource object representing discount
    next_offset next_offset
    optional, string, max chars=1000
    This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

    Sample admin console URL

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

    Retrieves a subscription.

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXe0W3SU \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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}

    Method

    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card

    Sample admin console URL

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

    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.

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXe0ksSf/retrieve_with_scheduled_changes \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    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.

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdyTgRH/remove_scheduled_changes \
         -X POST  \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    credit_notes credit_notes
    optional
    Resource object representing credit_notes

    Sample admin console URL

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

    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.

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdy9TR2/remove_scheduled_cancellation \
         -X POST  \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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.
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    Removes Coupons associated with the Subscription. If the param 'coupon_ids' is not specified, all the Coupons linked to the Subscription will be removed.

    Notes

    Sample Request
    # removes the listed coupons associated with the subscription.
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdxPSQY/remove_coupons \
         -u {site_api_key}:\
         -d coupon_ids="P10DISC"
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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.
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    Note: This endpoint optionally supports 3DS. To use it, create a payment_intent and provide it via this endpoint.

    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.

    Notes

    Sample Request
    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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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.
    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
    immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
    Show all values[+]
    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
    onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
    Show all values[+]
    offline_payment_method[]
    optional, enumerated string
    The preferred offline payment method for the subscription.
    Possible values are
    no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transfer
    Show all values[+]
    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
    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 parameter.
    token_id[]
    optional, string, max chars=40
    The Chargebee payment token generated by Chargebee JS.
    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
    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.
    .
    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
    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.
    .
    change_option[]
    optional, enumerated string
    When the quote is converted, this attribute determines the date/time as of when the subscription change is to be carried out.
    Possible values are
    immediatelyThe change is carried out immediately.end_of_termThe change is carried out at the end of the current billing cycle of the subscription.specific_dateThe change is carried out as of the date specified under changes_scheduled_at.
    Show all values[+]
    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
    dayCharge based on day(s)weekCharge based on week(s)monthCharge based on month(s)yearCharge based on year(s)
    Show all values[+]
    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
    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.
    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
    site_defaultThe action configured for the site at the time when the trial ends, takes effect. This is the default value when trial_end_action is not defined for the plan.plan_defaultThe action configured for the site at the time when the trial ends, takes effect. This is the default value when trial_end_action is defined for the plan.activate_subscriptionThe subscription activates and charges are raised for non-metered items.cancel_subscriptionThe subscription cancels.
    Show all values[+]
    payment_initiator[]
    optional, enumerated string
    The type of initiator to be used for the payment request triggered by this operation.
    Possible values are
    customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant
    Show all values[+]
    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[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[type]
    optional, enumerated string
    Possible values are
    cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
    Show all values[+]
    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[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
    cardcardidealidealsofortsofortbancontactbancontact
    Show all values[+]
    payment_intent[reference_id]
    optional, string, max chars=65k
    payment_intent[additional_information]
    optional, jsonobject
    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
    not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
    Show all values[+]
    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
    not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
    Show all values[+]
    statement_descriptor[descriptor]
    optional, string, max chars=65k
    statement_descriptor[additional_info]
    optional, string, max chars=65k
    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
    automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.
    Show all values[+]
    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[action_at_term_end]
    optional, enumerated string, default=renew
    Possible values are
    renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
  • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following:
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to cancel.
  • Show all values[+]
    contract_term[cancellation_cutoff_period]
    optional, integer
    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_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active or non-renewing state. Also includes reactivations of canceled subscriptions.
    Show all values[+]
    subscription_items[charge_once][0..n]
    optional, boolean
    subscription_items[charge_on_option][0..n]
    optional, enumerated string
    Possible values are
    immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event.
    Show all values[+]
    subscription_items[proration_type][0..n]
    optional, enumerated string
    Possible values are
    full_termCharge the full price of the addon or give the full credit. Don't apply any proration.partial_termProrate the charges or credits for the rest of the current term.noneDon't apply any charges or credits for the addon.
    Show all values[+]
    discounts[apply_on][0..n]
    required, enumerated string
    Possible values are
    invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
    Show all values[+]
    discounts[duration_type][0..n]
    required, enumerated string, default=forever
    Possible values are
    one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit.
    Show all values[+]
    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
    dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
    Show all values[+]
    discounts[included_in_mrr][0..n]
    optional, boolean
    discounts[item_price_id][0..n]
    optional, string, max chars=100
    discounts[operation_type][0..n]
    required, enumerated string
    Possible values are
    addThe discount is attached to the subscription.removeThe discount (given by discounts[id]) is removed from the subscription. Subsequent invoices will no longer have the discount applied. Tip: If you want to replace a discount, remove it and add another in the same API call.
    Show all values[+]
    discounts[id][0..n]
    optional, string, max chars=50
    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
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice
    unbilled_charges unbilled_charges
    optional
    Resource object representing unbilled_charges
    credit_notes credit_notes
    optional
    Resource object representing credit_notes

    Sample admin console URL

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

    Changes the subscription's current term end date. Depending on the "status" of the subscription, "term end date" has different effects.

    • If the Subscription is in trial, it affects trial end date.
    • If the Subscription is active, it affects the next billing date.
    • If the Subscription's status is non_renewing, this affects the upcoming cancellation date.

    Tip: To cycle through a couple of billing cycles and test webhooks, you may use this API.

    Notes

    • When changing the term_end for active / non_renewing subscriptions, by default no additional charges (when term gets extended) will be added or credits (when term gets reduced) will be issued. However you can specify prorate param as true for adding prorated charges / issuing prorated credits. Further for the charges that got added, you can specify invoice_immediately as false to add them to unbilled charges and invoice them later.
    • Advance charges, if any will be credited back during this operation.
    • Confirm the UTC (Coordinated Universal Time) time zone selected in your Chargebee site matches with your country region.
    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdtByMK/change_term_end \
         -u {site_api_key}:\
         -d term_ends_at=1613413800
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "customer": {
            "allow_direct_debit": false,
            "auto_collection": "off",
            "card_status": "no_card",
            "created_at": 1612890910,
            "deleted": false,
            "excess_payments": 0,
            "first_name": "John",
            "id": "__test__8asukSOXdt6gMH",
            "last_name": "Doe",
            "net_term_days": 0,
            "object": "customer",
            "pii_cleared": "active",
            "preferred_currency_code": "USD",
            "promotional_credits": 0,
            "refundable_credits": 0,
            "resource_version": 1612890910000,
            "taxability": "taxable",
            "unbilled_charges": 0,
            "updated_at": 1612890910
        },
        "subscription": {
            "activated_at": 1612890910,
            "billing_period": 1,
            "billing_period_unit": "month",
            "created_at": 1612890910,
            "currency_code": "USD",
            "current_term_end": 1613413800,
            "current_term_start": 1612890910,
            "customer_id": "__test__8asukSOXdt6gMH",
            "deleted": false,
            "due_invoices_count": 1,
            "due_since": 1612890910,
            "has_scheduled_changes": false,
            "id": "__test__8asukSOXdtByMK",
            "mrr": 0,
            "next_billing_at": 1613413800,
            "object": "subscription",
            "remaining_billing_cycles": 1,
            "resource_version": 1612890911000,
            "started_at": 1612890910,
            "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": 1612890911
        }
    }

    URL Format POST

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

    Method

    term_ends_at[]
    required, timestamp(UTC) in seconds
    The time at which the current term should end for this subscription.
    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
    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.
    .
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice
    unbilled_charges unbilled_charges
    optional
    Resource object representing unbilled_charges
    credit_notes credit_notes
    optional
    Resource object representing credit_notes

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    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.

    Notes

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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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
    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.
    .
    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
    immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
    Show all values[+]
    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.
    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
    customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant
    Show all values[+]
    contract_term[action_at_term_end]
    optional, enumerated string
    Possible values are
    renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
  • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.
    Show all values[+]
    contract_term[cancellation_cutoff_period]
    optional, integer, default=0
    statement_descriptor[descriptor]
    optional, string, max chars=65k
    statement_descriptor[additional_info]
    optional, string, max chars=65k
    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
    cardcardidealidealsofortsofortbancontactbancontact
    Show all values[+]
    payment_intent[reference_id]
    optional, string, max chars=65k
    payment_intent[additional_information]
    optional, jsonobject
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice
    unbilled_charges unbilled_charges
    optional
    Resource object representing unbilled_charges

    Sample admin console URL

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

    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.

    Notes

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

    Sample Request
    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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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
    wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
    Show all values[+]
    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 estimate
    always returned
    Resource object representing estimate

    Sample admin console URL

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

    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.

    Notes

    • 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.
    Sample Request
    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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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
    immediateCharge immediately for the number of billing cycles specified by terms_to_charge.specific_datesCharge on specific dates. For each date, specify the number of billing cycles to charge for. Up to 5 dates can be configured.fixed_intervalsCharge at fixed intervals of time. Specify the number of billing cycles that constitute an interval and the number of days before each interval that the invoice should be generated. Also specify when the schedule should end.
    Show all values[+]
    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
    after_number_of_intervalsAdvance invoices are generated a specified number of timesspecific_dateEnd the advance invoicing schedule on a specific date.subscription_endAdvance invoices are generated for as long as the subscription is active.
    Show all values[+]
    fixed_interval_schedule[end_date]
    optional, timestamp(UTC) in seconds
    specific_dates_schedule[terms_to_charge][0..n]
    optional, integer
    specific_dates_schedule[date][0..n]
    optional, timestamp(UTC) in seconds
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice
    advance_invoice_schedules advance_invoice_schedules
    optional
    Resource object representing advance_invoice_schedules

    Sample admin console URL

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

    Modifies the advance invoicing schedule for a subscription.

    Notes

    Sample Request
    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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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
    specific_datesCharge on specific dates. For each date, specify the number of billing cycles to charge for. Up to 5 dates can be configured.fixed_intervalsCharge at fixed intervals of time. Specify the number of billing cycles that constitute an interval and the number of days before each interval that the invoice should be generated. Also specify when the schedule should end.
    Show all values[+]
    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
    after_number_of_intervalsAdvance invoices are generated a specified number of timesspecific_dateEnd the advance invoicing schedule on a specific date.subscription_endAdvance invoices are generated for as long as the subscription is active.
    Show all values[+]
    fixed_interval_schedule[end_date]
    optional, timestamp(UTC) in seconds
    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 advance_invoice_schedules
    always returned
    Resource object representing advance_invoice_schedules

    Sample admin console URL

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

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

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2wPg43/retrieve_advance_invoice_schedule \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    advance_invoice_schedules advance_invoice_schedules
    always returned
    Resource object representing advance_invoice_schedules

    Sample admin console URL

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

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

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBsG2SYV7ZMB2K/remove_advance_invoice_schedule \
         -X POST  \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    specific_dates_schedule[id][0..n]
    optional, string, max chars=50
    subscription subscription
    always returned
    Resource object representing subscription
    advance_invoice_schedules advance_invoice_schedules
    optional
    Resource object representing advance_invoice_schedules

    Sample admin console URL

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

    Regenerates the current invoice for the subscription. The current invoice is that which includes non-metered items from the current term and metered items from the previous term of the subscription.

    prerequisites

    deleting an invoice

    Usages are also deleted when an invoice is deleted. Therefore, if the invoice was deleted, you may add or bulk import usages before regenerating an invoice.

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnOuSHufd0ih/regenerate_invoice \
         -u {site_api_key}:\
         -d invoice_immediately=true
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnOuSHufVfXT/regenerate_invoice \
         -u {site_api_key}:\
         -d invoice_immediately=false \
         -d date_from=1517826222 \
         -d date_to=1519208622 \
         -d prorate=true
    copy
    Click to Copy

    Sample Response [ JSON ]

    URL Format POST

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

    Method

    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 invoice
    optional
    Resource object representing invoice
    unbilled_charges unbilled_charges
    optional
    Resource object representing unbilled_charges

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    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.
    This API is not enabled for live sites by default. Please contact support to get this enabled.

    Notes

    Sample Request
    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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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[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
    activeAn actively running contract term.completedThe contract term has run its full duration.cancelledThe contract term was ended because: terminatedThe contract term was terminated ahead of completion.
    Show all values[+]
    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
    renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
  • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following:
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to cancel.
  • Show all values[+]
    contract_term[cancellation_cutoff_period]
    optional, integer
    contract_term contract_term
    always returned
    Resource object representing contract_term

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    Imports unbilled charges into Chargebee.
    This API is not enabled for live sites by default. Please contact support to get this enabled.

    Notes

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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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
    adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this caseplan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
    Show all values[+]
    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[unbilled_charge_id][0..n]
    optional, string, max chars=40
    discounts[entity_type][0..n]
    optional, enumerated string
    Possible values are
    item_level_couponThe deduction is due to a coupon applied to line item. The coupon id is passed as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is passed as entity_id.item_level_discountThe deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id. document_level_discountThe deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.
    Show all values[+]
    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[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 unbilled_charges
    always returned
    Resource object representing unbilled_charges

    Sample admin console URL

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

    Imports a subscription into Chargebee.

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

    Notes

    Sample Request
    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 
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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
    onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
    Show all values[+]
    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
    futureThe subscription is scheduled to start at a future date.in_trialThe subscription is in trial.activeThe subscription is active and will be charged for automatically based on the items in it.non_renewingThe subscription will be canceled at the end of the current term.
    Show all values[+]
    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 futuresubscriptions 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
    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.
    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
    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.
    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
    renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
  • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following:
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to cancel.
  • Show all values[+]
    contract_term[cancellation_cutoff_period]
    optional, integer, default=0
    transaction[amount]
    optional, in cents, min=1
    transaction[payment_method]
    optional, enumerated string
    Possible values are
    cashCashcheckCheckbank_transferBank TransferotherPayment Methods other than the above types
    Show all values[+]
    transaction[reference_number]
    optional, string, max chars=100
    transaction[date]
    optional, timestamp(UTC) in seconds
    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
    not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
    Show all values[+]
    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_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active or non-renewing state. Also includes reactivations of canceled subscriptions.
    Show all values[+]
    subscription_items[charge_once][0..n]
    optional, boolean
    discounts[apply_on][0..n]
    required, enumerated string
    Possible values are
    invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
    Show all values[+]
    discounts[duration_type][0..n]
    required, enumerated string, default=forever
    Possible values are
    one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit.
    Show all values[+]
    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
    dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
    Show all values[+]
    discounts[included_in_mrr][0..n]
    optional, boolean
    discounts[item_price_id][0..n]
    optional, string, max chars=100
    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[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
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice

    Sample admin console URL

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

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

    Notes

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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    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
    onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
    Show all values[+]
    subscription subscription
    always returned
    Resource object representing subscription
    payment_source payment_source
    optional
    Resource object representing payment_source

    Sample admin console URL

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

    Deletes the subscription resource.

    Notes

    This operation is irreversible - all data related to the subscription, such as invoices, transactions, and reports, will be deleted.

    Note: This operation schedules the subscription resource for deletion. It will be deleted in a few minutes.

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdv6kOj/delete \
         -X POST  \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card

    Sample admin console URL

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

    Pauses the subscription, changing its status to paused. This prevents the subscription from getting renewed. No new charges are created until the subscription is resumed.

    Note:

    • Applicable only for active/non-renewing subscriptions.
    • If paused indefinitely, the subscription is cancelled on the cancelled_at date.
    • Advance charges, if any, are refunded as credits.

    Notes

    Sample Request
    # pauses the subscription on end of term.
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdwKMPo/pause \
         -u {site_api_key}:\
         -d pause_option="END_OF_TERM"
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    pause_option[]
    optional, enumerated string
    List of options to pause the subscription.
    Possible values are
    immediatelyPause immediatelyend_of_termPause at the end of current termspecific_datePause on a specific datebilling_cycles

    Pause at the end of the current term, and resume automatically after the set number of billing cycles (in skip_billing_cycles) have been skipped

    Show all values[+]
    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
    no_action

    Retain as unbilled

    If no_action is chosen, charges are added to the resumption invoice.

    invoice

    Invoice charges

    If invoice is chosen, an automatic charge is attempted on the payment method available if the customer has enabled auto-collection. If a payment collection fails or when auto-collection is not enabled, the invoice is closed as unpaid.

    Show all values[+]
    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
    continueContinue dunningstopStop dunning
    Show all values[+]
    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 subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice
    unbilled_charges unbilled_charges
    optional
    Resource object representing unbilled_charges
    credit_notes credit_notes
    optional
    Resource object representing credit_notes

    Sample admin console URL

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

    Cancels the subscription.

    Canceling contract terms

    • Subscriptions with contract terms can only be canceled by  terminating the contract term.
    • When canceling a contract term, the default value for the following parameters is taken from the site settings for contract terms instead of the site settings for subscription cancellation.
      • credit_option_for_current_term_charges
      • unbilled_charges_option
      • account_receivables_handling
      • refundable_credits_handling
    • From among the parameters for this request, end_of_term or cancel_at should not be passed when using contract terms; use contract_term_cancel_option instead.
    • The subscription_items parameter is used to override price or quantity for the termination fee. To use this parameter, the following two conditions must be met:
      • contract_term_cancel_option must be set to terminate_now.
      • the subscription must have a subscription_items attribute with charge_on_event set to contract_term_termination.

    Notes

    Sample Request
    # cancels the subscription after the term ends.
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y28bL9/cancel_for_items \
         -u {site_api_key}:\
         -d end_of_term=true
    # cancels the subscription immediately with proration credits issued.
    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
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    end_of_term[]
    optional, boolean, default=false
    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
    Specify the date/time at which you want to cancel the subscription. This parameter should not be provided when end_of_term is passed as true. cancel_at can be set to a value in the past. This is called backdating. Use backdating when the subscription has been canceled already but its billing has been delayed. The following prerequisites must be met to allow backdating:
    • Backdating must be enabled for subscription cancellation.
    • The current day of the month does not exceed the limit set in Chargebee for backdating subscription cancellation. 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 subscription’s plan is 2 months and today is 14th April, changes_scheduled_at cannot be earlier than 14th February.
    .
    credit_option_for_current_term_charges[]
    optional, enumerated string
    For immediate cancellation (end_of_term = false), specify how to provide credits for current term charges. When not provided, the site default is considered.
    Possible values are
    noneNo credits notes are created.prorateProrated credits are issued.fullCredits are issues for the full value of the current term charges.
    Show all values[+]
    unbilled_charges_option[]
    optional, enumerated string
    For immediate cancellation (end_of_term = false), specify how to handle any unbilled charges. When not provided, the site default is considered.
    Possible values are
    invoiceAn invoice is generated immediately with the unbilled charges.deleteThe unbilled charges are deleted.
    Show all values[+]
    account_receivables_handling[]
    optional, enumerated string
    Applicable when the subscription has past due invoices. Specify this if you want to close the due invoices of the subscription. If specified as schedule_payment_collection/write_off, the due invoices of the subscription will be qualified for the selected operation after the remaining refundable credits and excess payments are applied. Note: The payment collection attempt will be asynchronous. Not applicable when 'end_of_term' is true.
    Possible values are
    no_actionNo action is taken.schedule_payment_collectionAn automatic charge for the due amount of the past invoices will be attempted on the payment method available, if customer's auto-collection property is ‘ON’.write_offThe amount due in the invoices will be written-off. Credit notes created due to write-off will not be sent in the response.
    Show all values[+]
    refundable_credits_handling[]
    optional, enumerated string
    Applicable when the customer has remaining refundable credits(issued against online payments). If specified as schedule_refund, the refund will be initiated for these credits after they are applied against the subscription’s past due invoices if any. Note: The refunds initiated will be asynchronous. Not applicable when 'end_of_term' is true.
    Possible values are
    no_actionNo action is taken.schedule_refundInitiates refund of the remaining credits.
    Show all values[+]
    contract_term_cancel_option[]
    optional, enumerated string
    Cancels the current contract term.
    • terminate_immediately immediately does the following:
    • end_of_contract_term Sets the contract_term[action_at_term_end] to cancel. In other words, the contract term is not renewed and the subscription is canceled at the end of the contract term.
    .
    Possible values are
    terminate_immediatelyTerminate immediatelyend_of_contract_termEnd of contract term
    Show all values[+]
    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
    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.
    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 subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice
    unbilled_charges unbilled_charges
    optional
    Resource object representing unbilled_charges
    credit_notes credit_notes
    optional
    Resource object representing credit_notes

    Sample admin console URL

    https://{site}.chargebee.com/admin-console/subscriptions/123x
    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 specified as schedule_payment_collection, payment collection for the amount due of past invoices will be attempted. The payment method available will be charged if auto-collection is enabled for the customer, and appropriate payment collection(payment succeeded or payment failed) events will be triggered. If the payment collection fails, no further retries will be made 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.

    Notes

    Sample Request
    # resumes a subscription immediately by scheduling payment collection for unpaid invoices.
    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

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    resume_option[]
    optional, enumerated string
    List of options to resume the subscription.
    Possible values are
    immediatelyResume immediatelyspecific_dateResume on a specific date
    Show all values[+]
    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
    invoice_immediatelyInvoice immediatelyadd_to_unbilled_chargesAdd to unbilled charges
    Show all values[+]
    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
    no_actionRetain as unpaidschedule_payment_collectionCollect payment
    Show all values[+]
    payment_initiator[]
    optional, enumerated string
    The type of initiator to be used for the payment request triggered by this operation.
    Possible values are
    customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant
    Show all values[+]
    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
    cardcardidealidealsofortsofortbancontactbancontact
    Show all values[+]
    payment_intent[reference_id]
    optional, string, max chars=65k
    payment_intent[additional_information]
    optional, jsonobject
    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card
    invoice invoice
    optional
    Resource object representing invoice
    unbilled_charges unbilled_charges
    optional
    Resource object representing unbilled_charges

    Sample admin console URL

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

    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.

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdz1ERW/remove_scheduled_pause \
         -X POST  \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card

    Sample admin console URL

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

    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.

    Notes

    Sample Request
    curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdzOFRl/remove_scheduled_resumption \
         -X POST  \
         -u {site_api_key}:
    copy
    Click to Copy

    Sample Response [ JSON ]

    Show more...
    {
        "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

    Method

    subscription subscription
    always returned
    Resource object representing subscription
    customer customer
    always returned
    Resource object representing customer
    card card
    optional
    Resource object representing card

    Sample admin console URL

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