Subscriptions

Subscription represents the recurring items a customer has subscribed to. The recurring items can be - plan, addons. It may also contain the discount items like coupons.

Subscriptions are invoiced at the start of every term based on the recurring items and charged immediately against the customer's credit card if 'auto_collection' is turned 'on', otherwise the resulting invoice will be created as 'Payment Due'.

Sample subscription [ JSON ]

{
    "activated_at": 1517505643,
    "auto_collection": "off",
    "billing_period": 1,
    "billing_period_unit": "month",
    "created_at": 1517505643,
    "currency_code": "USD",
    "current_term_end": 1519924843,
    "current_term_start": 1517505643,
    "customer_id": "__test__KyVnHhSBWkkwI2Tn",
    "deleted": false,
    "due_invoices_count": 1,
    "due_since": 1517505643,
    "has_scheduled_changes": false,
    "id": "__test__KyVnHhSBWkkwI2Tn",
    "mrr": 0,
    "next_billing_at": 1519924843,
    "object": "subscription",
    "plan_amount": 895,
    "plan_free_quantity": 0,
    "plan_id": "no_trial",
    "plan_quantity": 1,
    "plan_unit_price": 895,
    "resource_version": 1517505643000,
    "started_at": 1517505643,
    "status": "active",
    "total_dues": 895,
    "updated_at": 1517505643
}

API Index URL GET

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

id

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
string, max chars=50

currency_code

The currency code (ISO 4217 format) of the subscription.
string, max chars=3

plan_id

Identifier of the plan for this subscription.
string, max chars=100

plan_quantity

Represents the plan quantity for this subscription.
integer, default=1, min=1

plan_unit_price

Amount that will override the Plan's default price.
optional, in cents, min=0

setup_fee

Amount that will override the default setup fee.
optional, in cents, min=0

billing_period

Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
optional, integer, min=1

billing_period_unit

Defines billing frequency in association with the billing period.
optional, enumerated string

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

start_date

Applicable only for 'future' subscriptions. The scheduled start time of the subscription.
optional, timestamp(UTC) in seconds

trial_end

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.
optional, timestamp(UTC) in seconds

remaining_billing_cycles

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.

.
optional, integer, min=0

po_number

Purchase order number for this subscription.
optional, string, max chars=100

auto_collection

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

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.

customer_id

Identifier of the customer with whom this subscription is associated.
string, max chars=50

plan_amount

optional, in cents, min=0

plan_free_quantity

The units of the item that will be free with this Plan.
optional, integer, min=0

status

Current state of the subscription.
enumerated string

Possible values are

futureThe Subscription is scheduled to start in a future date.in_trialThe subscription is in trial.activeThe subscription is in active state and will be charged at start of each term based on the recurring items(plan & addons etc.,).non_renewingThe subscription will be cancelled at end of the current term.pausedThe subscription is paused. No new recurring actions will be allowed, but any pending payments will be collected.cancelledThe subscription has been cancelled. No new recurring actions will take place, but any pending payments will be collected.

trial_start

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.
optional, timestamp(UTC) in seconds

current_term_start

Start of the current billing period of the subscription.
optional, timestamp(UTC) in seconds

current_term_end

End of the current billing period of the subscription. Subscription is renewed immediately after this.
optional, timestamp(UTC) in seconds

next_billing_at

created_at

The time at which the subscription was created.
optional, timestamp(UTC) in seconds

started_at

Time at which the subscription was started. Is null for futuresubscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds

activated_at

Time at which the subscription moved from in_trial state to active. Same as started_at for subscriptions that had no trial.
optional, timestamp(UTC) in seconds

gift_id

References the gift if it is a gifted subscription.
optional, string, max chars=150

contract_term_billing_cycle_on_renewal

Number of billing cycles the new contract term should run for, on contract renewal. The default value is as specified in the site settings.
optional, integer, min=1, max=100

override_relationship

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

pause_date

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.
optional, timestamp(UTC) in seconds

resume_date

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.
optional, timestamp(UTC) in seconds

cancelled_at

Time at which subscription was cancelled or is set to be cancelled.
optional, timestamp(UTC) in seconds

cancel_reason

The reason for canceling the subscription. Set by Chargebee automatically.
optional, enumerated string

Possible values are

not_paidNot Paid.no_cardNo Card.fraud_review_failedFraud Review Failed.non_compliant_eu_customerNon Compliant EU Customer.tax_calculation_failedTax Calculation Failed.currency_incompatible_with_gatewayCurrency incompatible with Gateway.non_compliant_customerNon Compliant Customer.

affiliate_token

A unique tracking token.
optional, string, max chars=250

created_from_ip

The IP address of the user. Used primarly in Refersion integration. Refersion uses this field to track/log affiliate subscription.
optional, string, max chars=50

resource_version

Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long

updated_at

Timestamp indicating when the item was last updated.
optional, timestamp(UTC) in seconds

has_scheduled_advance_invoices

The subscription has an advance invoicing schedule.
boolean, default=false

has_scheduled_changes

If true, there are subscription changes scheduled on next renewal.
boolean, default=false

payment_source_id

Payment source attached to this subscription. If present, customer's payment sources won't be used to collect any payment for this subscripiton.
optional, string, max chars=40

plan_free_quantity_in_decimal

The free_quantity_in_decimal as set for the plan. Returned for quantity-based plans when multi-decimal pricing is enabled.
optional, string, max chars=33

plan_quantity_in_decimal

The decimal representation of the quantity of the plan purchased. Returned for quantity-based plans when multi-decimal pricing is enabled.
optional, string, max chars=33

plan_unit_price_in_decimal

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.
optional, string, max chars=33

plan_amount_in_decimal

The decimal representation of the total amount for the plan, in major units of the currency. Always returned when multi-decimal pricing is enabled.
optional, string, max chars=33

offline_payment_method

The preferred offline payment method for the subscription.
optional, enumerated string

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

due_invoices_count

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.
optional, integer

due_since

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.
optional, timestamp(UTC) in seconds

total_dues

Total invoice due amount for this subscription. The value is in the smallest unit of the 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.
optional, in cents, min=0

mrr

Monthly recurring revenue for the subscription. Updated asynchronously, this value catches up with changes to the subscription in less than a minute. The value is in the smallest unit of the currency.
Note: This may not return accurate values since updated asynchronously.
optional, in cents, min=1

exchange_rate

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.
optional, bigdecimal, min=1E-9, max=999999999.999999999

base_currency_code

The currency code (ISO 4217 format) of the site’s base currency.
optional, string, max chars=3

invoice_notes

Notes to be added to any invoice for this subscription.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

deleted

Indicates that the subscription has been deleted. You can retrieve a deleted subscription using the list operation.
boolean

cancel_reason_code

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

free_period

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.".
optional, integer

free_period_unit

Defines additional free period in association with the billing period.
optional, enumerated string

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

addons
Show attributes[+]

List of addons for this subscription with quantity(if applicable).
optional, list of addon

Addon attributes

id

Identifier of the addon. Multiple addons can be passed.
string, max chars=100

quantity

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1

unit_price

Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0

amount

optional, in cents, min=0

trial_end

The time at which the trial ends for the addon. This value can only be set for subscriptions that start with an active or non-renewing status. Once set, the value can't be changed. (Addon trial periods must be enabled by Chargebee Support.).
optional, timestamp(UTC) in seconds

remaining_billing_cycles

The number of billing cycles this addon will be attached to subscription.
optional, integer, min=0

quantity_in_decimal

The decimal representation of the quantity of the addon. Returned for quantity-based plans when multi-decimal pricing is enabled.
optional, string, max chars=33

unit_price_in_decimal

The decimal representation of the price or per-unit price of the addon. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.
optional, string, max chars=33

amount_in_decimal

The decimal representation of the total amount for the addon, in major units of the currency. Always returned when multi-decimal pricing is enabled.
optional, string, max chars=33

event_based_addons
Show attributes[+]

List of non-recurring addons that will be charged on the occurrence of specified event.
optional, list of event_based_addon

Event based addon attributes

id

A unique 'id' used to identify the addon.
string, max chars=100

quantity

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
integer, min=1

unit_price

Amount that will override the Addon's default price.
in cents, min=0

on_event

Event on which this addon will be charged.
enumerated string

Possible values are

subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.contract_terminationAddon will be charged on contract termination.

charge_once

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
boolean, default=true

quantity_in_decimal

The decimal representation of the quantity of the addon. Returned for quantity-based addons when multi-decimal pricing is enabled.
optional, string, max chars=33

unit_price_in_decimal

charged_event_based_addons
Show attributes[+]

List of event_based_addons that have already been charged.
optional, list of charged_event_based_addon

Charged event based addon attributes

id

Addon id.
string, max chars=100

last_charged_at

Timestamp indicating when this add-on was last charged for this subscription.
timestamp(UTC) in seconds

coupons
Show attributes[+]

List of coupons for this subscription.
optional, list of coupon

Coupon attributes

coupon_id

Used to uniquely identify the coupon.
string, max chars=50

apply_till

The date till the coupon is to be applied. Applicable for "limited months" coupons.
optional, timestamp(UTC) in seconds

applied_count

Number of times this coupon has been applied for this subscription.
integer, default=0

coupon_code

The coupon code used to redeem the coupon. Will be present only when associated code for a coupon is used.
optional, string, max chars=50

shipping_address
Show attributes[+]

Shipping address for the subscription.
optional, shipping_address

Shipping addres attributes

first_name

The first name of the contact.
optional, string, max chars=150

last_name

The last name of the contact.
optional, string, max chars=150

email

The email address.
optional, string, max chars=70

company

The company name.
optional, string, max chars=250

phone

The phone number.
optional, string, max chars=50

line1

Address line 1.
optional, string, max chars=180

line2

Address line 2.
optional, string, max chars=150

line3

Address line 3.
optional, string, max chars=150

city

The name of the city.
optional, string, max chars=50

state_code

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50

state

The state/province name.
optional, string, max chars=50

country

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

zip

Zip or Postal code.
optional, string, max chars=20

validation_status

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

referral_info
Show attributes[+]

Referral details if exists for the subscription.
optional, referral_info

Referral info attributes

referral_code

Referral code if available for the subscription.
optional, string, max chars=50

coupon_code

Referral coupon code if available for the subscription.
optional, string, max chars=50

referrer_id

Referrer id if available for the subscription.
optional, string, max chars=19

external_reference_id

External reference id in referral system for the subscription.
optional, string, max chars=50

reward_status

Reward status for the referral subscription.
optional, enumerated string, default=pending

Possible values are

pendingPending.paidPaid.invalidInvalid.

referral_system

Source referral system for the referral subscription.
optional, enumerated string

Possible values are

referral_candyReferral Candy.referral_saasquatchReferral Saasquatch.friendbuyFriendbuy.

account_id

Referral account id.
string, max chars=50

campaign_id

Referral campaign id.
string, max chars=50

external_campaign_id

Referral external campaign id.
optional, string, max chars=100

friend_offer_type

Friend offer type for the referral camapign.
optional, enumerated string

Possible values are

noneNone.couponCoupon.coupon_codeCoupon Code.

referrer_reward_type

Referrer reward type for the referral campaign.
optional, enumerated string

Possible values are

noneNone.referral_direct_rewardReferral Direct Reward.custom_promotional_creditCustom Promotional Credit.custom_revenue_percent_basedCustom Revenue Percent Based.

notify_referral_system

Whether or not to notify the referral purchases to the referral system.
optional, enumerated string

Possible values are

noneNone.first_paid_conversionFirst Paid Conversion.all_invoicesAll Invoices.

destination_url

Destination url for the referral campaign.
optional, string, max chars=250

post_purchase_widget_enabled

Whether post purchase widget is enabled for this campaign.
boolean, default=true

contract_term
Show attributes[+]

Contract terms for this subscription.
optional, contract_term

Contract term attributes

id

Id that uniquely identifies the contract term in the site.
string, max chars=50

status

Current status of contract.
enumerated string

Possible values are

activeAn actively running contract term.completedThe contract term has run its full duration.cancelledThe contract term was ended because:

a change in the subscription caused a subscription term reset.
the subscription was cancelled due to non-payment.

.terminatedThe contract term was terminated ahead of completion.

contract_start

The start date of the contract term.
timestamp(UTC) in seconds

contract_end

The end date of the contract term.
timestamp(UTC) in seconds

billing_cycle

The number of billing cycles of the subscription that the contract term is for.
integer, min=0

action_at_term_end

Action to be taken when the contract term completes.
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.

total_contract_value

The sum of the totals of all the invoices raised as part of the contract term. For active contract terms, this includes the invoices raised thus far and estimated invoice totals till the end of the contract term. If the subscription was imported with the contract term, then this value includes the value passed for total_amount_raised.
in cents, default=0, min=0

cancellation_cutoff_period

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

created_at

The date when the contract term was created.
timestamp(UTC) in seconds

subscription_id

The Id of the subscription that this contract term is for.
string, max chars=50

remaining_billing_cycles

The number of subscription billing cycles remaining after the current one for the contract term. This attribute is only returned for active contract terms.
optional, integer, min=0

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

Creates a new subscription along with the customer. You can attach a plan, plan quantity, one or more addons and coupon while creating this subscription.

Future Subscriptions

If the start_date is specified, the subscription will be created in 'future' state (.ie, instead of starting immediately it will be scheduled to start at the specified 'start_date'). Besides if 'trial' is specified (plan configuration or specified explictly using trial_end), the subscription will go into 'trial' state when it starts. Otherwise it will directly become 'active' when it starts.

Trial Period

If the plan has trial period or if the trial_end is specified explicitly, the subscription will be created in 'in_trial' state.

If the card details are passed, it is not charged until the end of the trial period. Incase you need to verify the card you could enable the 'card verification option' in the gateway settings.

Invoice

If the plan does not have a trial period and if any of the recurring items has charges, then a invoice would be raised immediately. If 'auto_collection' is turned 'on', then card attributes are mandatory and subscription will be created only if the payment was successful.

Card details

Passing card details to this API involves PCI liability at your end as sensitive card information passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable

If you are using Stripe gateway, you can use Stripe.js with your checkout form. Take a look at this Stripe tutorial for more details.
If you are using Braintree gateway, you can use Braintree.js with your checkout form. Please refer this tutorial for more details.
If you are using Authorize.Net gateway, you use Accept.js with your checkout form.
In case you are using the Adyen gateway, you will have to use the Adyen’s Client Side Encryption to encrypt sensitive cardholder data. Once the cardholder data is encrypted, pass the value in adyen.encrypted.data as temp token in this API.

You can also use our Hosted Pages based integration.

Billing Address

The Billing Address is significant especially when EU VAT taxes are involved, for tax calculations will be based on this address. For customers without Billing Address, EU VAT taxes will not be included. Thus ensure to set this properly if you have configured EU VAT Tax.

Note: For the sites created before 1st Mar 2014, customer's billing address and 'vat_number' will be replaced automatically whenever the associated card gets updated. i.e existing values for billing address and 'vat_number' will be cleared and the new values will be set. This behaviour is changed now - The VAT number should always be passed along billing address and not with card address. Both the addresses have to be dealt separately.

Billing Address attributes shall be explicitly passed for customers paying offline(Cash, Check, Bank Transfer etc).

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "state_code": "CA",
            "validation_status": "not_validated",
            "zip": "91789"
        },
        "card_status": "no_card",
        "created_at": 1517505643,
        "deleted": false,
        "email": "john@user.com",
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWkkwI2Tn",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505643000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505643
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "amount_to_collect": 895,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "state_code": "CA",
            "validation_status": "not_validated",
            "zip": "91789"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWkkwI2Tn",
        "date": 1517505643,
        "deleted": false,
        "due_date": 1517505643,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__11",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVnHhSBWkkwI2Tn",
                "date_from": 1517505643,
                "date_to": 1519924843,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnHhSBWkkxu2Tp",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnHhSBWkkwI2Tn",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "new_sales_amount": 895,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517505643000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 895,
        "subscription_id": "__test__KyVnHhSBWkkwI2Tn",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517505643,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517505643,
        "auto_collection": "off",
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505643,
        "currency_code": "USD",
        "current_term_end": 1519924843,
        "current_term_start": 1517505643,
        "customer_id": "__test__KyVnHhSBWkkwI2Tn",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505643,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkkwI2Tn",
        "mrr": 0,
        "next_billing_at": 1519924843,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505643000,
        "started_at": 1517505643,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505643
    }
}

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505647,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWklx92UA",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505647000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505647
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 200,
        "amount_paid": 0,
        "amount_to_collect": 200,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWklx92UA",
        "date": 1517505647,
        "deleted": false,
        "due_date": 1517505647,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__14",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 200,
                "customer_id": "__test__KyVnHhSBWklx92UA",
                "date_from": 1517505647,
                "date_to": 1519924847,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnHhSBWklyY2UC",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnHhSBWklx92UA",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 200
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "new_sales_amount": 200,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517505647000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 200,
        "subscription_id": "__test__KyVnHhSBWklx92UA",
        "tax": 0,
        "term_finalized": true,
        "total": 200,
        "updated_at": 1517505647,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517505647,
        "auto_collection": "off",
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505647,
        "currency_code": "USD",
        "current_term_end": 1519924847,
        "current_term_start": 1517505647,
        "customer_id": "__test__KyVnHhSBWklx92UA",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505647,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWklx92UA",
        "mrr": 0,
        "next_billing_at": 1519924847,
        "object": "subscription",
        "plan_amount": 200,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 200,
        "resource_version": 1517505647000,
        "started_at": 1517505647,
        "status": "active",
        "total_dues": 200,
        "updated_at": 1517505647
    }
}

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505645,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWklIN2Tu",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505645000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505645
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1300,
        "amount_paid": 0,
        "amount_to_collect": 1300,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWklIN2Tu",
        "date": 1517505645,
        "deleted": false,
        "discounts": [
            {
                "amount": 90,
                "description": "Plan Only Coupon",
                "entity_id": "plan_only_coupon",
                "entity_type": "item_level_coupon",
                "object": "discount"
            },
            {..}
        ],
        "due_date": 1517505645,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__12",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_item_discounts": [
            {
                "coupon_id": "plan_only_coupon",
                "discount_amount": 90,
                "discount_type": "item_level_coupon",
                "line_item_id": "li___test__KyVnHhSBWklKE2Tw",
                "object": "line_item_discount"
            },
            {..}
        ],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVnHhSBWklIN2Tu",
                "date_from": 1517505645,
                "date_to": 1519924845,
                "description": "No Trial",
                "discount_amount": 90,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnHhSBWklKE2Tw",
                "is_taxed": false,
                "item_level_discount_amount": 90,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnHhSBWklIN2Tu",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "new_sales_amount": 1300,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517505645000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1300,
        "subscription_id": "__test__KyVnHhSBWklIN2Tu",
        "tax": 0,
        "term_finalized": true,
        "total": 1300,
        "updated_at": 1517505645,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517505645,
        "addons": [
            {
                "amount": 495,
                "id": "ssl",
                "object": "addon",
                "quantity": 1,
                "unit_price": 495
            },
            {..}
        ],
        "auto_collection": "off",
        "billing_period": 1,
        "billing_period_unit": "month",
        "coupon": "plan_only_coupon",
        "coupons": [
            {
                "applied_count": 1,
                "coupon_id": "plan_only_coupon",
                "object": "coupon"
            },
            {..}
        ],
        "created_at": 1517505645,
        "currency_code": "USD",
        "current_term_end": 1519924845,
        "current_term_start": 1517505645,
        "customer_id": "__test__KyVnHhSBWklIN2Tu",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505645,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWklIN2Tu",
        "mrr": 0,
        "next_billing_at": 1519924845,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505645000,
        "started_at": 1517505645,
        "status": "active",
        "total_dues": 1300,
        "updated_at": 1517505645
    }
}

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517505646,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWklcY2U3",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505646000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505646
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "amount_to_collect": 895,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWklcY2U3",
        "date": 1517505646,
        "deleted": false,
        "due_date": 1517505646,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__13",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVnHhSBWklcY2U3",
                "date_from": 1517505646,
                "date_to": 1519924846,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnHhSBWkldr2U5",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnHhSBWklcY2U3",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "new_sales_amount": 895,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517505646000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 895,
        "subscription_id": "__test__KyVnHhSBWklcY2U3",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517505646,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517505646,
        "auto_collection": "off",
        "billing_period": 1,
        "billing_period_unit": "month",
        "cf_gender": "Male",
        "created_at": 1517505646,
        "currency_code": "USD",
        "current_term_end": 1519924846,
        "current_term_start": 1517505646,
        "customer_id": "__test__KyVnHhSBWklcY2U3",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505646,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWklcY2U3",
        "meta_data": {"features": {
            "post-usage-quota": "512kbps",
            "speed-within-quota": "2MBbps",
            "usage-limit": "5GB"
        }},
        "mrr": 0,
        "next_billing_at": 1519924846,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505646000,
        "started_at": 1517505646,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505646
    }
}

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "balances": [
            {
                "balance_currency_code": "USD",
                "currency_code": "USD",
                "excess_payments": 0,
                "object": "customer_balance",
                "promotional_credits": 0,
                "refundable_credits": 0,
                "unbilled_charges": 2780
            },
            {..}
        ],
        "card_status": "no_card",
        "created_at": 1517505649,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkmHx2UH",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505649000,
        "taxability": "taxable",
        "unbilled_charges": 2780,
        "updated_at": 1517505649
    },
    "subscription": {
        "activated_at": 1517505649,
        "addons": [
            {
                "amount": 495,
                "id": "ssl",
                "object": "addon",
                "quantity": 1,
                "unit_price": 495
            },
            {..}
        ],
        "auto_collection": "off",
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505649,
        "currency_code": "USD",
        "current_term_end": 1519924849,
        "current_term_start": 1517505649,
        "customer_id": "__test__KyVnHhSBWkmHx2UH",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkmHx2UH",
        "mrr": 0,
        "next_billing_at": 1522603249,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505649000,
        "started_at": 1517505649,
        "status": "active",
        "updated_at": 1517505649
    },
    "unbilled_charges": [
        {
            "amount": 495,
            "currency_code": "USD",
            "customer_id": "__test__KyVnHhSBWkmHx2UH",
            "date_from": 1519924849,
            "date_to": 1522603249,
            "deleted": false,
            "description": "SSL",
            "discount_amount": 0,
            "entity_id": "ssl",
            "entity_type": "addon",
            "id": "li___test__KyVnHhSBWkmLK2UM",
            "is_voided": false,
            "object": "unbilled_charge",
            "pricing_model": "flat_fee",
            "quantity": 1,
            "subscription_id": "__test__KyVnHhSBWkmHx2UH",
            "unit_amount": 495
        },
        {..}
    ]
}

URL Format POST

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

id

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
optional, string, max chars=50

plan_unit_price_in_decimal

When price overriding is enabled for the site, the price or per-unit price of the plan can be set here. The value set for the plan is used by default. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.
optional, string, max chars=33

plan_quantity_in_decimal

The decimal representation of the quantity of the plan purchased. Can be provided for quantity-based plans and only when multi-decimal pricing is enabled.
optional, string, max chars=33

plan_id

Identifier of the plan for this subscription.
required, string, max chars=100

plan_quantity

Plan quantity for this subscription.
optional, integer, default=1, min=1

plan_unit_price

Amount that will override the Plan's default price.
optional, in cents, min=0

setup_fee

Amount that will override the default setup fee.
optional, in cents, min=0

trial_end

The time at which the trial ends for this subscription. Can be specified to override the default trial period.If '0' is passed, the subscription will be activated immediately.
optional, timestamp(UTC) in seconds

billing_cycles

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

mandatory_addons_to_remove[0..n]

List of addons IDs that are mandatory to the plan and has to be removed from the subscription.
optional, list of string

start_date

The date/time at which the subscription is to start or has started. If not provided, the subscription starts immediately. If set to a value in the past then that date/time should not be more than a plan billing period into the past.
optional, timestamp(UTC) in seconds

auto_collection

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

Possible values are

terms_to_charge

The number of subscription billing cycles (including the first one) to invoice in advance.
optional, integer, min=1

billing_alignment_mode

Override the billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing.
optional, enumerated string

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.

offline_payment_method

The preferred offline payment method for the subscription.
optional, enumerated string

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

po_number

Purchase order number for this subscription.
optional, string, max chars=100

coupon_ids[0..n]

Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string

token_id

The Chargebee payment token generated by Chargebee JS.
optional, string, max chars=40

affiliate_token

A unique tracking token.
optional, string, max chars=250

invoice_notes

Notes to be added to any invoice for this subscription.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

invoice_immediately

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.
optional, boolean

free_period

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.
optional, integer, min=1

free_period_unit

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.
optional, enumerated string

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

contract_term_billing_cycle_on_renewal

Number of billing cycles the new contract term should run for, on contract renewal. The default value is as specified in the site settings.
optional, integer, min=1, max=100

client_profile_id

Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, string, max chars=50

customer

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

customer[id]

Id for the new customer. If not given, this will be same as the subscription id.
optional, string, max chars=50

customer[email]

Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70

customer[first_name]

First name of the customer.
optional, string, max chars=150

customer[last_name]

Last name of the customer.
optional, string, max chars=150

customer[company]

Company name of the customer.
optional, string, max chars=250

customer[taxability]

Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable

Possible values are

taxableCustomer is taxable.exempt

Customer is exempted from tax
Optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.

customer[locale]

Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.
optional, string, max chars=50

customer[entity_code]

The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration.
optional, enumerated string

Possible values are

aFederal government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.

eCharitable or benevolent organization.fReligious organization.gResale.hCommercial agricultural production.iIndustrial production/manufacturer.jDirect pay permit.kDirect mail.lOther or custom.mEducational organization.nLocal government.pCommercial aquaculture.qCommercial Fishery.rNon-resident.med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.

Show all values[+]

customer[exempt_number]

Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's AvaTax for Sales integration.
optional, string, max chars=100

customer[net_term_days]

The number of days within which the customer has to make payment for the invoice.
optional, integer, default=0

customer[taxjar_exemption_category]

Indicates the exemption type of the customer. This is applicable only if you use Chargebee’s TaxJar integration.
optional, enumerated string

Possible values are

wholesaleWhole-sale.governmentGovernment.otherOther.

customer[phone]

Phone number of the customer.
optional, string, max chars=50

customer[auto_collection]

Whether payments needs to be collected automatically for this customer.
optional, enumerated string, default=on

Possible values are

onWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.offAutomatic collection of charges will not be made. All payments must be recorded offline.

customer[offline_payment_method]

The preferred offline payment method for the subscription.
optional, enumerated string

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

customer[allow_direct_debit]

Whether the customer can pay via Direct Debit.
optional, boolean, default=false

customer[consolidated_invoicing]

Applicable when consolidated invoicing is enabled. Indicates whether invoice consolidation should happen during subscription renewals. Needs to be set only if this value is different from the defaults configured.
optional, boolean

customer[vat_number]

VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20

customer[registered_for_gst]

Confirms that a customer is registered under GST. This field is available for Australia only.
optional, boolean

customer[business_customer_without_vat_number]

Confirms that a customer is a valid business without VAT number.
optional, boolean

customer[exemption_details]

Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
To know more about what values you need to provide, refer to this Avalara’s API document.
optional, jsonarray

customer[customer_type]

Indicates the type of the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

residentialWhen the purchase is made by a customer for home use.businessWhen the purchase is made at a place of business.senior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaks.industrialWhen the purchase is made by an industrial business.

card

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

card[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

card[first_name]

Cardholder's first name.
optional, string, max chars=50

card[last_name]

Cardholder's last name.
optional, string, max chars=50

card[number]

The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500

card[expiry_month]

Card expiry month.
required if card provided, integer, min=1, max=12

card[expiry_year]

Card expiry year.
required if card provided, integer

card[cvv]

The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520

card[billing_addr1]

Address line 1, as available in card billing address.
optional, string, max chars=150

card[billing_addr2]

Address line 2, as available in card billing address.
optional, string, max chars=150

card[billing_city]

City, as available in card billing address.
optional, string, max chars=50

card[billing_state_code]

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

card[billing_state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

card[billing_zip]

Postal or Zip code, as available in card billing address.
optional, string, max chars=20

card[billing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

bank_account

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

bank_account[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

bank_account[iban]

Account holder’s International Bank Account Number.
optional, string, min chars=10, max chars=50

bank_account[first_name]

Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150

bank_account[last_name]

Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150

bank_account[company]

Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=250

bank_account[email]

Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
optional, string, max chars=70

bank_account[bank_name]

Name of account holder’s bank.
optional, string, max chars=100

bank_account[account_number]

Account holder’s bank account number.
optional, string, min chars=4, max chars=17

bank_account[routing_number]

Bank account routing number.
optional, string, min chars=3, max chars=9

bank_account[bank_code]

Indicates the bank code.
optional, string, max chars=20

bank_account[account_type]

For Authorize.net ACH users only. Indicates the type of account.
optional, enumerated string

Possible values are

checkingChecking Account.savingsSavings Account.business_checkingBusiness Checking Account.

bank_account[account_holder_type]

For Stripe ACH users only. Indicates the account holder type.
optional, enumerated string

Possible values are

individualIndividual.companyCompany.

bank_account[echeck_type]

For Authorize.net ACH users only. Indicates the type of eCheck.
optional, enumerated string

Possible values are

webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.

bank_account[issuing_country]

2-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
optional, string, max chars=50

bank_account[swedish_identity_number]

For GoCardless Autogiro users only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
optional, string, min chars=10, max chars=12

payment_method

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

payment_method[type]

The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
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.

genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.

Show all values[+]

payment_method[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

payment_method[reference_id]

The reference id. In the case of Amazon and PayPal this will be the billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=200

payment_method[tmp_token]

Single-use token created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet or card details. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k

payment_method[issuing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

payment_intent

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

payment_intent[id]

Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
optional, string, max chars=150

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_info]

Applicable only for Braintree gateway. Can be used only for Braintree’s Advance Fraud Management feature. Pass a stringified JSON containing the device_session_id and fraud_merchant_id as an input to fingerprint. Here’s a sample to it.
optional, jsonobject

billing_address

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

billing_address[first_name]

The first name of the billing contact.
optional, string, max chars=150

billing_address[last_name]

The last name of the billing contact.
optional, string, max chars=150

billing_address[email]

The email address.
optional, string, max chars=70

billing_address[company]

The company name.
optional, string, max chars=250

billing_address[phone]

The phone number.
optional, string, max chars=50

billing_address[line1]

Address line 1.
optional, string, max chars=150

billing_address[line2]

Address line 2.
optional, string, max chars=150

billing_address[line3]

Address line 3.
optional, string, max chars=150

billing_address[city]

The name of the city.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

billing_address[zip]

Zip or Postal code.
optional, string, max chars=20

billing_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

billing_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

shipping_address

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

shipping_address[first_name]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

shipping_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

contract_term

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

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
optional, enumerated string, default=cancel

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.

contract_term[cancellation_cutoff_period]

addons

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

addons[id][0..n]

Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100

addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1

addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

addons[unit_price][0..n]

addons[unit_price_in_decimal][0..n]

When price overriding is enabled for the site, the price or per-unit price of the addon can be set here. The value set for the addon is used by default. However, the price provided here is considered as the price of the addon for an entire billing cycle of the subscription regardless of the value of the addon period. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.
optional, string, max chars=33

addons[billing_cycles][0..n]

Number of billing cycles the addon will be charged for. When not set, the addon is attached to the subscription for an indefinite number of billing cycles. While updating a subscription to a plan with a different billing period, set this parameter again or its value will be lost. And so, the addon will be attached indefinitely.
optional, integer, min=1

addons[trial_end][0..n]

event_based_addons

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

event_based_addons[id][0..n]

A unique 'id' used to identify the addon.
optional, string, max chars=100

event_based_addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1

event_based_addons[unit_price][0..n]

Amount that will override the Addon's default price.
optional, in cents, min=0

event_based_addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

event_based_addons[unit_price_in_decimal][0..n]

When price overriding is enabled for the site, the price or per-unit price of the addon can be set here. The value set for the addon is used by default. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.
optional, string, max chars=33

event_based_addons[service_period_in_days][0..n]

Defines service period of the addon in days from the day of charge.
optional, integer, min=1, max=730

event_based_addons[on_event][0..n]

Event on which this addon will be charged.
optional, enumerated string

Possible values are

event_based_addons[charge_once][0..n]

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true

event_based_addons[charge_on][0..n]

Indicates when the non-recurring addon will be charged.
optional, enumerated string

Possible values are

immediatelyCharges for the addon will be applied immediately.on_eventCharge for the addon will be applied on the occurrence of a specified event.

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

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

Creates a new subscription for an existing customer. You can attach a plan, plan quantity, one or more addons and coupon while creating this subscription.

If the plan does not have a trial period and if any of the recurring-item has charges, then the customer is charged immediately if auto_collection is turned 'on'. In that case, subscription is created only if the customer has a payment method on file and attempted payment is successful.

Notes

If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.

Sample Request

curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWkmi22UR/subscriptions \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d shipping_address[first_name]="Mark" \
     -d shipping_address[last_name]="Henry" \
     -d shipping_address[company]="chargebee" \
     -d start_date=1600968050

copy

curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWkmi22UR/subscriptions \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d shipping_address[first_name]="Mark" \
     -d shipping_address[last_name]="Henry" \
     -d shipping_address[company]="chargebee" \
     -d start_date=1600968050

# creates a subscription for customer with addons and coupons.
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWkn672UW/subscriptions \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d addons[id][0]="day-pass" \
     -d addons[quantity][0]=2 \
     -d addons[id][1]="ssl" \
     -d coupon_ids[0]="plan_only_coupon" \
     -d coupon_ids[1]="plan_quantity_coupon"

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505650,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__KyVnHhSBWkmi22UR",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505650000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505650
    },
    "subscription": {
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505650,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWkmi22UR",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkmjz2UT",
        "next_billing_at": 1600968050,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505650000,
        "shipping_address": {
            "company": "chargebee",
            "first_name": "Mark",
            "last_name": "Henry",
            "object": "shipping_address",
            "validation_status": "not_validated"
        },
        "start_date": 1600968050,
        "status": "future",
        "updated_at": 1517505650
    }
}

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505652,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "David",
        "id": "__test__KyVnHhSBWkn672UW",
        "last_name": "Villa",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505652000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505652
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1520,
        "amount_paid": 0,
        "amount_to_collect": 1520,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "David",
            "last_name": "Villa",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWkn672UW",
        "date": 1517505652,
        "deleted": false,
        "discounts": [
            {
                "amount": 200,
                "description": "Plan Quantity Coupon",
                "entity_id": "plan_quantity_coupon",
                "entity_type": "item_level_coupon",
                "object": "discount"
            },
            {..}
        ],
        "due_date": 1517505652,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__15",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_item_discounts": [
            {
                "coupon_id": "plan_only_coupon",
                "discount_amount": 70,
                "discount_type": "item_level_coupon",
                "line_item_id": "li___test__KyVnHhSBWknC22Ua",
                "object": "line_item_discount"
            },
            {..}
        ],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVnHhSBWkn672UW",
                "date_from": 1517505652,
                "date_to": 1519924852,
                "description": "No Trial",
                "discount_amount": 270,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnHhSBWknC22Ua",
                "is_taxed": false,
                "item_level_discount_amount": 270,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnHhSBWkn7m2UY",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "new_sales_amount": 1520,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517505652000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1520,
        "subscription_id": "__test__KyVnHhSBWkn7m2UY",
        "tax": 0,
        "term_finalized": true,
        "total": 1520,
        "updated_at": 1517505652,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517505652,
        "addons": [
            {
                "amount": 495,
                "id": "ssl",
                "object": "addon",
                "quantity": 1,
                "unit_price": 495
            },
            {..}
        ],
        "billing_period": 1,
        "billing_period_unit": "month",
        "coupon": "plan_only_coupon",
        "coupons": [
            {
                "applied_count": 1,
                "coupon_id": "plan_only_coupon",
                "object": "coupon"
            },
            {..}
        ],
        "created_at": 1517505652,
        "currency_code": "USD",
        "current_term_end": 1519924852,
        "current_term_start": 1517505652,
        "customer_id": "__test__KyVnHhSBWkn672UW",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505652,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkn7m2UY",
        "mrr": 0,
        "next_billing_at": 1519924852,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505652000,
        "started_at": 1517505652,
        "status": "active",
        "total_dues": 1520,
        "updated_at": 1517505652
    }
}

URL Format POST

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

id

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
optional, string, max chars=50

plan_unit_price_in_decimal

plan_quantity_in_decimal

The decimal representation of the quantity of the plan purchased. Can be provided for quantity-based plans and only when multi-decimal pricing is enabled.
optional, string, max chars=33

plan_id

Identifier of the plan for this subscription.
required, string, max chars=100

plan_quantity

Plan quantity for this subscription.
optional, integer, default=1, min=1

plan_unit_price

Amount that will override the Plan's default price.
optional, in cents, min=0

setup_fee

Amount that will override the default setup fee.
optional, in cents, min=0

trial_end

billing_cycles

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

mandatory_addons_to_remove[0..n]

List of addons IDs that are mandatory to the plan and has to be removed from the subscription.
optional, list of string

start_date

auto_collection

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

Possible values are

terms_to_charge

The number of subscription billing cycles (including the first one) to invoice in advance.
optional, integer, min=1

billing_alignment_mode

Override the billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing.
optional, enumerated string

Possible values are

offline_payment_method

The preferred offline payment method for the subscription.
optional, enumerated string

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

po_number

Purchase order number for this subscription.
optional, string, max chars=100

coupon_ids[0..n]

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

payment_source_id

Id of the payment source to be attached to this subscription.
optional, string, max chars=40

override_relationship

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

invoice_notes

Notes to be added to any invoice for this subscription.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

invoice_immediately

free_period

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.
optional, integer, min=1

free_period_unit

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.
optional, enumerated string

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

contract_term_billing_cycle_on_renewal

Number of billing cycles the new contract term should run for, on contract renewal. The default value is as specified in the site settings.
optional, integer, min=1, max=100

shipping_address

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

shipping_address[first_name]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

shipping_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_info]

contract_term

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

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
optional, enumerated string, default=cancel

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.

contract_term[cancellation_cutoff_period]

addons

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

addons[id][0..n]

Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100

addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1

addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

addons[unit_price][0..n]

addons[unit_price_in_decimal][0..n]

addons[billing_cycles][0..n]

addons[trial_end][0..n]

event_based_addons

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

event_based_addons[id][0..n]

A unique 'id' used to identify the addon.
optional, string, max chars=100

event_based_addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1

event_based_addons[unit_price][0..n]

Amount that will override the Addon's default price.
optional, in cents, min=0

event_based_addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

event_based_addons[unit_price_in_decimal][0..n]

event_based_addons[service_period_in_days][0..n]

Defines service period of the addon in days from the day of charge.
optional, integer, min=1, max=730

event_based_addons[on_event][0..n]

Event on which this addon will be charged.
optional, enumerated string

Possible values are

event_based_addons[charge_once][0..n]

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true

event_based_addons[charge_on][0..n]

Indicates when the non-recurring addon will be charged.
optional, enumerated string

Possible values are

immediatelyCharges for the addon will be applied immediately.on_eventCharge for the addon will be applied on the occurrence of a specified event.

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

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

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "list": [
        {
            "customer": {
                "allow_direct_debit": false,
                "auto_collection": "off",
                "card_status": "no_card",
                "created_at": 1517505659,
                "deleted": false,
                "excess_payments": 0,
                "first_name": "Mark",
                "id": "__test__KyVnHhSBWkp5t2VV",
                "last_name": "Henry",
                "net_term_days": 0,
                "object": "customer",
                "pii_cleared": "active",
                "preferred_currency_code": "USD",
                "promotional_credits": 0,
                "refundable_credits": 0,
                "resource_version": 1517505659000,
                "taxability": "taxable",
                "unbilled_charges": 0,
                "updated_at": 1517505659
            },
            "subscription": {
                "addons": [
                    {
                        "amount": 495,
                        "id": "ssl",
                        "object": "addon",
                        "quantity": 1,
                        "unit_price": 495
                    },
                    {..}
                ],
                "billing_period": 1,
                "billing_period_unit": "month",
                "contract_term": {
                    "action_at_term_end": "renew",
                    "billing_cycle": 5,
                    "cancellation_cutoff_period": 3,
                    "contract_end": 1615141800,
                    "contract_start": 1509511210,
                    "created_at": 1509511210,
                    "id": "__test__KyVnHhSBWkp8U2VZ",
                    "object": "contract_term",
                    "remaining_billing_cycles": 5,
                    "status": "active",
                    "total_contract_value": 7850
                },
                "contract_term_billing_cycle_on_renewal": 3,
                "created_at": 1517505659,
                "currency_code": "USD",
                "customer_id": "__test__KyVnHhSBWkp5t2VV",
                "deleted": false,
                "due_invoices_count": 0,
                "has_scheduled_changes": false,
                "id": "__test__KyVnHhSBWkp852VX",
                "next_billing_at": 1602095400,
                "object": "subscription",
                "plan_amount": 895,
                "plan_free_quantity": 0,
                "plan_id": "no_trial",
                "plan_quantity": 1,
                "plan_unit_price": 895,
                "remaining_billing_cycles": 5,
                "resource_version": 1517505659000,
                "started_at": 1517505659,
                "status": "in_trial",
                "trial_end": 1602095400,
                "trial_start": 1517505659,
                "updated_at": 1517505659
            }
        },
        {..}
    ],
    "next_offset": "[\"1517505658000\",\"225000000983\"]"
}

URL Format GET

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

limit

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

offset

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.
optional, string, max chars=1000

include_deleted

Indicates whether to include deleted objects in the list. The deleted objects have the attribute deleted as true.
optional, boolean, default=false

sort_by[<sort-order>]

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.
optional, string filter

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

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

Example → id[is] = "8gsnbYfsMLds"
optional, string filter

customer_id[<operator>]

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

Example → customer_id[is_not] = "8gsnbYfsMLds"
optional, string filter

plan_id[<operator>]

Identifier of the plan for this subscription.
Supported operators : is, is_not, starts_with, in, not_in

Example → plan_id[is] = "basic"
optional, string filter

status[<operator>]

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

Example → status[is] = "active"
optional, enumerated string filter

cancel_reason[<operator>]

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"
optional, enumerated string filter

cancel_reason_code[<operator>]

remaining_billing_cycles[<operator>]

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

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

Example → remaining_billing_cycles[lt] = "3"
optional, integer filter

created_at[<operator>]

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

Example → created_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter

activated_at[<operator>]

Time at which the subscription moved from in_trial state to active. Same as started_at for subscriptions that had no trial.
Supported operators : after, before, on, between, is_present

Example → activated_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter

next_billing_at[<operator>]

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

Example → next_billing_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter

cancelled_at[<operator>]

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

Example → cancelled_at[before] = "1435054328"
optional, timestamp(UTC) in seconds filter

has_scheduled_changes[<operator>]

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

Example → has_scheduled_changes[is] = "true"
optional, boolean filter

updated_at[<operator>]

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

Example → updated_at[after] = "1243545465"
optional, timestamp(UTC) in seconds filter

offline_payment_method[<operator>]

The preferred offline payment method for the subscription. Possible values are : no_preference, cash, check, bank_transfer, ach_credit, sepa_credit.
Supported operators : is, is_not, in, not_in

Example → offline_payment_method[is] = "cash"
optional, enumerated string filter

override_relationship[<operator>]

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"
optional, boolean filter

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

next_offset

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”.
optional, string, max chars=1000

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

Sample Request

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

copy

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

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

Sample Response [ JSON ]

{"list": [
    {"contract_term": {
        "action_at_term_end": "renew",
        "billing_cycle": 12,
        "cancellation_cutoff_period": 0,
        "contract_end": 1549041627,
        "contract_start": 1517505627,
        "created_at": 1517505628,
        "id": "__test__KyVnHhSBWkgk02SJ",
        "object": "contract_term",
        "remaining_billing_cycles": 11,
        "status": "active",
        "total_contract_value": 10740
    }},
    {..}
]}

{"list": [
    {"contract_term": {
        "action_at_term_end": "renew",
        "billing_cycle": 1,
        "cancellation_cutoff_period": 0,
        "contract_end": 1517505635,
        "contract_start": 1517505635,
        "created_at": 1517505635,
        "id": "__test__KyVnHhSBWkijx2So",
        "object": "contract_term",
        "status": "terminated",
        "total_contract_value": 895
    }},
    {..}
]}

URL Format GET

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

limit

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

offset

contract_term

Resource object representing contract_term.
always returned

next_offset

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”.
optional, string, max chars=1000

Retrieves a subscription.

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505683,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkv9J2YH",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505683000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505683
    },
    "subscription": {
        "activated_at": 1517505683,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505683,
        "currency_code": "USD",
        "current_term_end": 1519924883,
        "current_term_start": 1517505683,
        "customer_id": "__test__KyVnHhSBWkv9J2YH",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505683,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkv9J2YH",
        "mrr": 0,
        "next_billing_at": 1519924883,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505683000,
        "started_at": 1517505683,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505683
    }
}

URL Format GET

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

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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

plan_id
plan_quantity
plan_unit_price
setup_fee
billing_period
billing_period_unit
plan_free_quantity
remaining_billing_cycles
addons
coupons

Other attributes such as status, next_billing_at are not changed and will reflect the current subscription values.

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "card": {
        "card_type": "visa",
        "created_at": 1517505684,
        "customer_id": "__test__KyVnHhSBWkvUM2YO",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "credit",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
        "iin": "411111",
        "last4": "1111",
        "masked_number": "************1111",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWkvV42YQ",
        "resource_version": 1517505684000,
        "status": "valid",
        "updated_at": 1517505684
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505684,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkvUM2YO",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWkvV12YP",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWkvV42YQ",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505684000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505684
    },
    "subscription": {
        "activated_at": 1517505684,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505684,
        "currency_code": "USD",
        "current_term_end": 1519924884,
        "current_term_start": 1517505684,
        "customer_id": "__test__KyVnHhSBWkvUM2YO",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": true,
        "id": "__test__KyVnHhSBWkvUM2YO",
        "mrr": 0,
        "next_billing_at": 1519924884,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "sub_free",
        "plan_quantity": 1,
        "plan_unit_price": 0,
        "resource_version": 1517505684000,
        "started_at": 1517505684,
        "status": "active",
        "updated_at": 1517505684
    }
}

URL Format GET

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

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "card": {
        "card_type": "visa",
        "created_at": 1517505675,
        "customer_id": "__test__KyVnHhSBWkt5V2XR",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "credit",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
        "iin": "411111",
        "last4": "1111",
        "masked_number": "************1111",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWkt6G2XT",
        "resource_version": 1517505675000,
        "status": "valid",
        "updated_at": 1517505675
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505675,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkt5V2XR",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWkt6C2XS",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWkt6G2XT",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505675000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505675
    },
    "subscription": {
        "activated_at": 1517505675,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505675,
        "currency_code": "USD",
        "current_term_end": 1519924875,
        "current_term_start": 1517505675,
        "customer_id": "__test__KyVnHhSBWkt5V2XR",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkt5V2XR",
        "mrr": 0,
        "next_billing_at": 1519924875,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505675000,
        "started_at": 1517505675,
        "status": "active",
        "updated_at": 1517505675
    }
}

URL Format POST

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

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

credit_notes

Resource object representing credit_note.
optional

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

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

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

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505673,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWksgR2XI",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505673000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505673
    },
    "subscription": {
        "activated_at": 1517505673,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505673,
        "currency_code": "USD",
        "current_term_end": 1519924873,
        "current_term_start": 1517505673,
        "customer_id": "__test__KyVnHhSBWksgR2XI",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505673,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWksgR2XI",
        "mrr": 0,
        "next_billing_at": 1519924873,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505673000,
        "started_at": 1517505673,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505673
    }
}

URL Format POST

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

billing_cycles

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

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

Removes Coupons associated with the Subscription. If the param 'coupon_ids' is not specified, all the Coupons linked to the Subscription will be removed.

Sample Request

# removes the listed coupons associated with the subscription.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkrtw2X0/remove_coupons \
     -X POST  \
     -u {site_api_key}:\
     -d coupon_ids[0]="plan_only_coupon"

copy

# removes the listed coupons associated with the subscription.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkrtw2X0/remove_coupons \
     -X POST  \
     -u {site_api_key}:\
     -d coupon_ids[0]="plan_only_coupon"

# removes all the coupons associated with the subscription.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWksKp2X9/remove_coupons \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "company": "wwe",
        "created_at": 1517505670,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWkrtw2X0",
        "last_name": "Cena",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505670000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505670
    },
    "subscription": {
        "activated_at": 1517505670,
        "auto_collection": "off",
        "billing_period": 1,
        "billing_period_unit": "month",
        "coupon": "plan_quantity_coupon",
        "coupons": [
            {
                "applied_count": 1,
                "coupon_id": "plan_quantity_coupon",
                "object": "coupon"
            },
            {..}
        ],
        "created_at": 1517505670,
        "currency_code": "USD",
        "current_term_end": 1519924870,
        "current_term_start": 1517505670,
        "customer_id": "__test__KyVnHhSBWkrtw2X0",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkrtw2X0",
        "mrr": 0,
        "next_billing_at": 1519924870,
        "object": "subscription",
        "plan_amount": 100,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 100,
        "resource_version": 1517505671000,
        "started_at": 1517505670,
        "status": "active",
        "updated_at": 1517505671
    }
}

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "company": "wwe",
        "created_at": 1517505672,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWksKp2X9",
        "last_name": "Cena",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505672000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505672
    },
    "subscription": {
        "activated_at": 1517505672,
        "auto_collection": "off",
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505672,
        "currency_code": "USD",
        "current_term_end": 1519924872,
        "current_term_start": 1517505672,
        "customer_id": "__test__KyVnHhSBWksKp2X9",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWksKp2X9",
        "mrr": 0,
        "next_billing_at": 1519924872,
        "object": "subscription",
        "plan_amount": 100,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 100,
        "resource_version": 1517505672000,
        "started_at": 1517505672,
        "status": "active",
        "updated_at": 1517505672
    }
}

URL Format POST

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

coupon_ids[0..n]

Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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

You can modify the plan, plan quantity and add or remove addons for the subscription. By default the changes are applied immediately and the charges (/credits) are prorated and adjusted with the next billing term. You may also choose to effect the changes at the end of the current term by passing end_of_term as "true". In this case proration will not be done.

Only the parameters that are passed are modified for the subscription. Rest will reflect the existing values.

By default, the addons passed are appended to the existing list of addons for this subscription. In case a passed addon already exists for this subscription, quantity value is replaced. If you want to completely replace the addons for this subscription, pass replace_addon_list as "true".

Card and 'vat_number' attributes can also be passed during subscription update. If they are passed, corresponding Billing Info attributes - the Billing Address and 'vat_number' - will be replaced automatically.

Passing credit card details to this API involves PCI liability at your end as sensitive card info passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable

If you are using Stripe gateway, you can use Stripe.js with your checkout form. Take a look at this Stripe tutorial for more details.
If you are using Braintree gateway, you can use Braintree.js with your checkout form. Please refer this tutorial for more details.
If you are using Authorize.Net gateway, you use Accept.js with your checkout form.
If you are using the Adyen gateway, you will have to use the Adyen’s Client Side Encryption to encrypt sensitive cardholder data. Once the cardholder data is encrypted, pass the value in adyen.encrypted.data as temp token in this API.
You can also use our Hosted Pages based integration.

Notes

Proration Scenario: A customer changes from a $15 plan to $30 plan after 15 days of a monthly term. He will be charged for $7.50 immediately. The following Credit Note and Invoice will be generated

Credit Note
Prorated credits for Old Plan	$7.50

Invoice
Prorated charges for New Plan	$15.00
Total	$15.00
Credits	($7.50)
Amount Due	$7.50

Meanwhile downgrading will result in net credits being created which will be applied when the subscription is charged on start of the next term. Learn more about our proration scenarios here.

Billing Cycle: The billing period for a subscription does not change if the plans intervals of both old and new are same. However, if a customer changes to a plan that has different billing interval(say monthly to yearly), the billing period is reset. Customer is charged immediately for the modified subscription after applying credit for the unused period for the old subscription.

Card and VAT number Input: If they are passed, corresponding Billing Address attributes and vat_number will be replaced. i.e existing values for Billing Address and 'vat_number' will be cleared and the new values will be set.

If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.

Advance charges, if any, will be refunded as credits and a new invoice will be generated on renewal.

Sample Request

# updates the subscription's plan and replaces the addons associated with
# it .The changes made will be effective from current end
# of term.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkvzp2Yd \
     -u {site_api_key}:\
     -d plan_id="plan1" \
     -d addons[id][0]="sub_ssl" \
     -d addons[id][1]="sub_monitor" \
     -d addons[quantity][1]=2 \
     -d end_of_term="true"

copy

# updates the subscription's plan and replaces the addons associated with
# it .The changes made will be effective from current end
# of term.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkvzp2Yd \
     -u {site_api_key}:\
     -d plan_id="plan1" \
     -d addons[id][0]="sub_ssl" \
     -d addons[id][1]="sub_monitor" \
     -d addons[quantity][1]=2 \
     -d end_of_term="true"

# Resets the subscription's term.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkx5j2ZC \
     -u {site_api_key}:\
     -d plan_unit_price=300 \
     -d force_term_reset="true"

# reactivates a cancelled subscription from a specific date.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkwhA2Z2 \
     -u {site_api_key}:\
     -d reactivate_from=1517505689

# updates the customer's card details.The changes made are effective immediately.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkwL02Yl \
     -u {site_api_key}:\
     -d card[number]="5105105105105100" \
     -d card[cvv]="100" \
     -d card[expiry_year]=2022 \
     -d card[expiry_month]=12 \
     -d end_of_term="false"

Sample Response [ JSON ]

{
    "credit_notes": [],
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505686,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkvzp2Yd",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505686000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505686
    },
    "subscription": {
        "activated_at": 1517505686,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505686,
        "currency_code": "USD",
        "current_term_end": 1519924886,
        "current_term_start": 1517505686,
        "customer_id": "__test__KyVnHhSBWkvzp2Yd",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505686,
        "has_scheduled_changes": true,
        "id": "__test__KyVnHhSBWkvzp2Yd",
        "mrr": 0,
        "next_billing_at": 1519924886,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505686000,
        "started_at": 1517505686,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505686
    }
}

{
    "card": {
        "card_type": "american_express",
        "created_at": 1517505690,
        "customer_id": "__test__KyVnHhSBWkx5j2ZC",
        "expiry_month": 2,
        "expiry_year": 2022,
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWkx6Z2ZE",
        "resource_version": 1517505690000,
        "status": "valid",
        "updated_at": 1517505690
    },
    "credit_notes": [
        {
            "allocations": [
                {
                    "allocated_amount": 300,
                    "allocated_at": 1517505690,
                    "invoice_date": 1517505690,
                    "invoice_id": "__demo_inv__38",
                    "invoice_status": "paid"
                },
                {..}
            ],
            "amount_allocated": 300,
            "amount_available": 595,
            "amount_refunded": 0,
            "base_currency_code": "USD",
            "create_reason_code": "Subscription Change",
            "currency_code": "USD",
            "customer_id": "__test__KyVnHhSBWkx5j2ZC",
            "date": 1517505690,
            "deleted": false,
            "exchange_rate": 1,
            "fractional_correction": 0,
            "id": "__demo_cn__2",
            "line_item_discounts": [],
            "line_item_taxes": [],
            "line_items": [
                {
                    "amount": 895,
                    "customer_id": "__test__KyVnHhSBWkx5j2ZC",
                    "date_from": 1517505690,
                    "date_to": 1519924890,
                    "description": "No Trial - Prorated Credits for 01-Feb-2018 - 01-Mar-2018",
                    "discount_amount": 0,
                    "entity_id": "no_trial",
                    "entity_type": "plan",
                    "id": "li___test__KyVnHhSBWkxCd2ZS",
                    "is_taxed": false,
                    "item_level_discount_amount": 0,
                    "object": "line_item",
                    "pricing_model": "per_unit",
                    "quantity": 1,
                    "subscription_id": "__test__KyVnHhSBWkx5j2ZC",
                    "tax_amount": 0,
                    "tax_exempt_reason": "tax_not_configured",
                    "unit_amount": 895
                },
                {..}
            ],
            "linked_refunds": [],
            "object": "credit_note",
            "price_type": "tax_exclusive",
            "reason_code": "subscription_change",
            "reference_invoice_id": "__demo_inv__37",
            "resource_version": 1517505690000,
            "round_off_amount": 0,
            "status": "refund_due",
            "sub_total": 895,
            "subscription_id": "__test__KyVnHhSBWkx5j2ZC",
            "taxes": [],
            "total": 895,
            "type": "refundable",
            "updated_at": 1517505690
        },
        {..}
    ],
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "balances": [
            {
                "balance_currency_code": "USD",
                "currency_code": "USD",
                "excess_payments": 0,
                "object": "customer_balance",
                "promotional_credits": 0,
                "refundable_credits": 595,
                "unbilled_charges": 0
            },
            {..}
        ],
        "card_status": "valid",
        "created_at": 1517505690,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkx5j2ZC",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWkx6U2ZD",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWkx6Z2ZE",
        "promotional_credits": 0,
        "refundable_credits": 595,
        "resource_version": 1517505690000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505690
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 0,
        "amount_to_collect": 0,
        "applied_credits": [
            {
                "applied_amount": 300,
                "applied_at": 1517505690,
                "cn_create_reason_code": "Subscription Change",
                "cn_date": 1517505690,
                "cn_id": "__demo_cn__2",
                "cn_reason_code": "subscription_change",
                "cn_status": "refund_due"
            },
            {..}
        ],
        "base_currency_code": "USD",
        "credits_applied": 300,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWkx5j2ZC",
        "date": 1517505690,
        "deleted": false,
        "due_date": 1517505690,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__38",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 300,
                "customer_id": "__test__KyVnHhSBWkx5j2ZC",
                "date_from": 1517505690,
                "date_to": 1519924890,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnHhSBWkxCU2ZQ",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnHhSBWkx5j2ZC",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 300
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "paid_at": 1517505690,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517505690000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 300,
        "subscription_id": "__test__KyVnHhSBWkx5j2ZC",
        "tax": 0,
        "term_finalized": true,
        "total": 300,
        "updated_at": 1517505690,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517505690,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505690,
        "currency_code": "USD",
        "current_term_end": 1519924890,
        "current_term_start": 1517505690,
        "customer_id": "__test__KyVnHhSBWkx5j2ZC",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkx5j2ZC",
        "mrr": 0,
        "next_billing_at": 1519924890,
        "object": "subscription",
        "plan_amount": 300,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 300,
        "resource_version": 1517505690000,
        "started_at": 1517505690,
        "status": "active",
        "updated_at": 1517505690
    }
}

{
    "credit_notes": [],
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505688,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkwhA2Z2",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505688000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505688
    },
    "subscription": {
        "activated_at": 1517505688,
        "billing_period": 1,
        "billing_period_unit": "month",
        "cancelled_at": 1517505689,
        "created_at": 1517505688,
        "currency_code": "USD",
        "current_term_end": 1517505689,
        "current_term_start": 1517505688,
        "customer_id": "__test__KyVnHhSBWkwhA2Z2",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505688,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkwhA2Z2",
        "mrr": 0,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505689000,
        "started_at": 1517505688,
        "status": "cancelled",
        "total_dues": 895,
        "updated_at": 1517505689
    }
}

{
    "card": {
        "card_type": "mastercard",
        "created_at": 1517505687,
        "customer_id": "__test__KyVnHhSBWkwL02Yl",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "prepaid",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
        "iin": "510510",
        "last4": "5100",
        "masked_number": "************5100",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWkwPG2Yt",
        "resource_version": 1517505687000,
        "status": "valid",
        "updated_at": 1517505687
    },
    "credit_notes": [],
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505687,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkwL02Yl",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWkwPC2Ys",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWkwPG2Yt",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505687000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505687
    },
    "subscription": {
        "activated_at": 1517505687,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505687,
        "currency_code": "USD",
        "current_term_end": 1519924887,
        "current_term_start": 1517505687,
        "customer_id": "__test__KyVnHhSBWkwL02Yl",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkwL02Yl",
        "mrr": 0,
        "next_billing_at": 1519924887,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505687000,
        "started_at": 1517505687,
        "status": "active",
        "updated_at": 1517505687
    }
}

URL Format POST

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

plan_id

Identifier of the plan for this subscription.
optional, string, max chars=100

plan_quantity

Represents the plan quantity for this subscription.
optional, integer, min=1

plan_unit_price

Amount that will override the Plan's default price.
optional, in cents, min=0

setup_fee

Amount that will override the default setup fee.
optional, in cents, min=0

replace_addon_list

Should be true if the existing addons should be replaced with the ones that are being passed.
optional, boolean

mandatory_addons_to_remove[0..n]

List of addons IDs that are mandatory to the plan and has to be removed from the subscription.
optional, list of string

plan_quantity_in_decimal

The decimal representation of the quantity of the plan purchased. Can be provided for quantity-based plans and only when multi-decimal pricing is enabled.
optional, string, max chars=33

plan_unit_price_in_decimal

start_date

The new start date of a future subscription. Applicable only for future subscriptions.
optional, timestamp(UTC) in seconds

trial_end

End of the trial period for the subscription. This overrides the trial period set for the plan. In Product Catalog v2 this overrides trial period set for the plan-item. Set it to 0 to have no trial period.
optional, timestamp(UTC) in seconds

billing_cycles

The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan is used. For Product Catalog v2, billing cycles set for plan-item price is used by default.
optional, integer, min=0

terms_to_charge

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.
optional, integer, min=1

reactivate_from

When the subscription is reactivated as described under the reactivate parameter, this is the date/time at which the subscription should be reactivated.
optional, timestamp(UTC) in seconds

billing_alignment_mode

Override the billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing.
optional, enumerated string

Possible values are

auto_collection

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

Possible values are

offline_payment_method

The preferred offline payment method for the subscription.
optional, enumerated string

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

po_number

Purchase order number for this subscription.
optional, string, max chars=100

coupon_ids[0..n]

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

replace_coupon_list

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.
optional, boolean

prorate

Raise prorated credits or charges as applicable while changing the subscription. When not provided, the value is taken from the site settings.
optional, boolean

end_of_term

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

force_term_reset

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.
optional, boolean, default=false

reactivate

Applicable only for cancelled subscriptions. When passed as true, the canceled subscription is activated; otherwise subscription changes are made without changing its status. If not passed, subscription will be activated only if subscription_items is passed.
optional, boolean

token_id

The Chargebee payment token generated by Chargebee JS.
optional, string, max chars=40

invoice_notes

Notes to be added to any invoice for this subscription.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

invoice_immediately

override_relationship

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

contract_term_billing_cycle_on_renewal

Number of billing cycles the new contract term should run for, on contract renewal. The default value is as specified in the site settings.
optional, integer, min=1, max=100

free_period

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.
optional, integer, min=1

free_period_unit

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.
optional, enumerated string

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

card

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

card[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

card[first_name]

Cardholder's first name.
optional, string, max chars=50

card[last_name]

Cardholder's last name.
optional, string, max chars=50

card[number]

The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500

card[expiry_month]

Card expiry month.
required if card provided, integer, min=1, max=12

card[expiry_year]

Card expiry year.
required if card provided, integer

card[cvv]

The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520

card[billing_addr1]

Address line 1, as available in card billing address.
optional, string, max chars=150

card[billing_addr2]

Address line 2, as available in card billing address.
optional, string, max chars=150

card[billing_city]

City, as available in card billing address.
optional, string, max chars=50

card[billing_state_code]

card[billing_state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

card[billing_zip]

Postal or Zip code, as available in card billing address.
optional, string, max chars=20

card[billing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

payment_method

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

payment_method[type]

The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
optional, enumerated string

Possible values are

Show all values[+]

payment_method[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

payment_method[reference_id]

payment_method[tmp_token]

Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k

payment_method[issuing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_info]

billing_address

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

billing_address[first_name]

The first name of the billing contact.
optional, string, max chars=150

billing_address[last_name]

The last name of the billing contact.
optional, string, max chars=150

billing_address[email]

The email address.
optional, string, max chars=70

billing_address[company]

The company name.
optional, string, max chars=250

billing_address[phone]

The phone number.
optional, string, max chars=50

billing_address[line1]

Address line 1.
optional, string, max chars=150

billing_address[line2]

Address line 2.
optional, string, max chars=150

billing_address[line3]

Address line 3.
optional, string, max chars=150

billing_address[city]

The name of the city.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

billing_address[zip]

Zip or Postal code.
optional, string, max chars=20

billing_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

billing_address[validation_status]

The address verification status.
optional, enumerated string

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

shipping_address

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

shipping_address[first_name]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

shipping_address[validation_status]

The address verification status.
optional, enumerated string

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

customer

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

customer[vat_number]

VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20

customer[business_customer_without_vat_number]

Confirms that a customer is a valid business without VAT number.
optional, boolean

customer[registered_for_gst]

Confirms that a customer is registered under GST. This field is available for Australia only.
optional, boolean

contract_term

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

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
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 cancel.

contract_term[cancellation_cutoff_period]

addons

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

addons[id][0..n]

Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100

addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1

addons[unit_price][0..n]

addons[billing_cycles][0..n]

addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

addons[unit_price_in_decimal][0..n]

addons[trial_end][0..n]

The time at which the trial ends for the addon. To update this value, redo the complete addon set using replace_addon_list. (Addon trial periods must be enabled by Chargebee Support.).
optional, timestamp(UTC) in seconds

event_based_addons

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

event_based_addons[id][0..n]

A unique 'id' used to identify the addon.
optional, string, max chars=100

event_based_addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1

event_based_addons[unit_price][0..n]

Amount that will override the Addon's default price.
optional, in cents, min=0

event_based_addons[service_period_in_days][0..n]

Defines service period of the addon in days from the day of charge.
optional, integer, min=1, max=730

event_based_addons[charge_on][0..n]

Indicates when the non-recurring addon will be charged.
optional, enumerated string

Possible values are

immediatelyCharges for the addon will be applied immediately.on_eventCharge for the addon will be applied on the occurrence of a specified event.

event_based_addons[on_event][0..n]

Event on which this addon will be charged.
optional, enumerated string

Possible values are

event_based_addons[charge_once][0..n]

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean

event_based_addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

event_based_addons[unit_price_in_decimal][0..n]

When price overriding is enabled for the site, the price or per-unit price of the addon can be set here. The value set for the addonis used by default. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.
optional, string, max chars=33

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

credit_notes

Resource object representing credit_note.
optional

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.

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505623,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkfbN2Rf",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505623000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505623
    },
    "subscription": {
        "activated_at": 1517505623,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505623,
        "currency_code": "USD",
        "current_term_end": 1601490600,
        "current_term_start": 1517505623,
        "customer_id": "__test__KyVnHhSBWkfbN2Rf",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505623,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkfbN2Rf",
        "mrr": 0,
        "next_billing_at": 1601490600,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505623000,
        "started_at": 1517505623,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505623
    }
}

URL Format POST

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

term_ends_at

The time at which the current term should end for this subscription.
required, timestamp(UTC) in seconds

prorate

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

invoice_immediately

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

credit_notes

Resource object representing credit_note.
optional

This operation 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__KyVnHhSBWkrVS2Wn/reactivate \
     -X POST  \
     -u {site_api_key}:\
     -d invoice_immediately="true" \
     -d billing_cycles=4

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505669,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkrVS2Wn",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505669000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505669
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "amount_to_collect": 895,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWkrVS2Wn",
        "date": 1517505669,
        "deleted": false,
        "due_date": 1517505669,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__23",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVnHhSBWkrVS2Wn",
                "date_from": 1517505669,
                "date_to": 1519924869,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnHhSBWkrbQ2Ww",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnHhSBWkrVS2Wn",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517505669000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 895,
        "subscription_id": "__test__KyVnHhSBWkrVS2Wn",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517505669,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517505669,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505669,
        "currency_code": "USD",
        "current_term_end": 1519924869,
        "current_term_start": 1517505669,
        "customer_id": "__test__KyVnHhSBWkrVS2Wn",
        "deleted": false,
        "due_invoices_count": 2,
        "due_since": 1517505669,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkrVS2Wn",
        "mrr": 0,
        "next_billing_at": 1519924869,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "remaining_billing_cycles": 3,
        "resource_version": 1517505669000,
        "started_at": 1517505669,
        "status": "active",
        "total_dues": 1790,
        "updated_at": 1517505669
    }
}

URL Format POST

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

trial_end

The time at which the trial should end for this subscription.
optional, timestamp(UTC) in seconds

billing_cycles

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

reactivate_from

When the subscription is reactivated as described under the reactivate parameter, this is the date/time at which the subscription should be reactivated.
optional, timestamp(UTC) in seconds

invoice_immediately

billing_alignment_mode

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.
optional, enumerated string

Possible values are

terms_to_charge

contract_term_billing_cycle_on_renewal

Number of billing cycles the new contract term should run for, on contract renewal. The default value is as specified in the site settings.
optional, integer, min=1, max=100

contract_term

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

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
optional, enumerated string, default=cancel

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.

contract_term[cancellation_cutoff_period]

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_info]

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

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__KyVnHhSBWkeIw2R1/add_charge_at_term_end \
     -u {site_api_key}:\
     -d amount=300 \
     -d description="Service Charge"

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

amount

The amount to be charged.
optional, in cents, min=1

description

Description for this charge.
required, string, max chars=250

amount_in_decimal

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.
optional, string, max chars=33

avalara_sale_type

Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction is for an item that is subject to vendor use tax.

avalara_transaction_type

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.
optional, integer

avalara_service_type

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.
optional, integer

date_from

The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds

date_to

The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds

estimate

Resource object representing estimate.
always returned

Adds a "non-recurring addon" charge to a 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 the charges for the non-recurring addon 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__KyVnHhSBWkfvE2Rn/charge_addon_at_term_end \
     -u {site_api_key}:\
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=3 \
     -d addon_unit_price=100

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkfvE2Rn/charge_addon_at_term_end \
     -u {site_api_key}:\
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=3 \
     -d addon_unit_price=100

Sample Response [ JSON ]

{"estimate": {
    "created_at": 1517505625,
    "invoice_estimate": {
        "amount_due": 1195,
        "amount_paid": 0,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWkfvE2Rn",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 300,
                "customer_id": "__test__KyVnHhSBWkfvE2Rn",
                "date_from": 1517505624,
                "date_to": 1517505624,
                "description": "non_recurring_addon",
                "discount_amount": 0,
                "entity_id": "non_recurring_addon",
                "entity_type": "addon",
                "id": "li___test__KyVnHhSBWkg3f2Ru",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 3,
                "subscription_id": "__test__KyVnHhSBWkfvE2Rn",
                "tax_amount": 0,
                "unit_amount": 100
            },
            {..}
        ],
        "object": "invoice_estimate",
        "price_type": "tax_exclusive",
        "recurring": true,
        "round_off_amount": 0,
        "sub_total": 1195,
        "taxes": [],
        "total": 1195
    },
    "object": "estimate",
    "subscription_estimate": {
        "currency_code": "USD",
        "id": "__test__KyVnHhSBWkfvE2Rn",
        "next_billing_at": 1519924824,
        "object": "subscription_estimate",
        "status": "active"
    }
}}

URL Format POST

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

addon_id

The ID of the non-recurring addon to be charged.
required, string, max chars=100

addon_quantity

The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1

addon_unit_price

Amount that will override the Addon's default price.
optional, in cents, default=addon amount, min=0

addon_quantity_in_decimal

The decimal representation of the quantity of the non-recurring addon. Provide the value in major units of the currency. Must be provided when the addon is quantity-based. This parameter can only be passed when multi-decimal pricing is enabled.
optional, string, max chars=33

addon_unit_price_in_decimal

When price overriding is enabled for the site, the price or per-unit price of the non-recurring addon can be set here. The value set for the addon is used by default. Provide the value as a decimal string in major units of the currency. This parameter can only be passed when multi-decimal pricing is enabled.
optional, string, default=Addon Amount in Decimal, max chars=33

date_from

The time when the service period for the addon starts.
optional, timestamp(UTC) in seconds

date_to

The time when the service period for the addon ends.
optional, timestamp(UTC) in seconds

estimate

Resource object representing estimate.
always returned

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.

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__KyVkmQSCX2uew22/charge_future_renewals \
     -u {site_api_key}:

copy

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

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2vCA2M/charge_future_renewals \
     -u {site_api_key}:\
     -d invoice_immediately="false" \
     -d terms_to_charge=3

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2vWP2w/charge_future_renewals \
     -u {site_api_key}:\
     -d schedule_type="fixed_intervals" \
     -d terms_to_charge=4 \
     -d fixed_interval_schedule[days_before_renewal]=5 \
     -d fixed_interval_schedule[end_schedule_on]="after_number_of_intervals" \
     -d fixed_interval_schedule[number_of_occurrences]=3

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2vM62f/charge_future_renewals \
     -u {site_api_key}:\
     -d schedule_type="specific_dates" \
     -d specific_dates_schedule[date][0]=1518339706 \
     -d specific_dates_schedule[terms_to_charge][0]=2 \
     -d specific_dates_schedule[date][1]=1523523706 \
     -d specific_dates_schedule[terms_to_charge][1]=2

Sample Response [ JSON ]

{
    "card": {
        "card_type": "american_express",
        "created_at": 1517475704,
        "customer_id": "__test__KyVkmQSCX2uew22",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "payment_source_id": "pm___test__KyVkmQSCX2uhT24",
        "resource_version": 1517475704000,
        "status": "valid",
        "updated_at": 1517475704
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517475703,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVkmQSCX2uew22",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
            "object": "payment_method",
            "reference_id": "tok___test__KyVkmQSCX2uga23",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVkmQSCX2uhT24",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517475704000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517475704
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 895,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVkmQSCX2uew22",
        "date": 1517475705,
        "deleted": false,
        "due_date": 1517475705,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": true,
        "id": "__demo_inv__2",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVkmQSCX2uew22",
                "date_from": 1519894903,
                "date_to": 1522573303,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVkmQSCX2v3L2G",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVkmQSCX2uew22",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 895,
                "applied_at": 1517475705,
                "txn_amount": 895,
                "txn_date": 1517475705,
                "txn_id": "txn___test__KyVkmQSCX2v4U2H",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "paid_at": 1517475705,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517475705000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 895,
        "subscription_id": "__test__KyVkmQSCX2uew22",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517475705,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517475703,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517475703,
        "currency_code": "USD",
        "current_term_end": 1519894903,
        "current_term_start": 1517475703,
        "customer_id": "__test__KyVkmQSCX2uew22",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_advance_invoices": false,
        "has_scheduled_changes": false,
        "id": "__test__KyVkmQSCX2uew22",
        "mrr": 0,
        "next_billing_at": 1522573303,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517475704000,
        "started_at": 1517475703,
        "status": "active",
        "updated_at": 1517475704
    }
}

{
    "card": {
        "card_type": "american_express",
        "created_at": 1517475705,
        "customer_id": "__test__KyVkmQSCX2vCA2M",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "payment_source_id": "pm___test__KyVkmQSCX2vDE2O",
        "resource_version": 1517475705000,
        "status": "valid",
        "updated_at": 1517475705
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "balances": [
            {
                "balance_currency_code": "USD",
                "currency_code": "USD",
                "excess_payments": 0,
                "object": "customer_balance",
                "promotional_credits": 0,
                "refundable_credits": 0,
                "unbilled_charges": 2685
            },
            {..}
        ],
        "card_status": "valid",
        "created_at": 1517475705,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVkmQSCX2vCA2M",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
            "object": "payment_method",
            "reference_id": "tok___test__KyVkmQSCX2vD72N",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVkmQSCX2vDE2O",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517475706000,
        "taxability": "taxable",
        "unbilled_charges": 2685,
        "updated_at": 1517475706
    },
    "subscription": {
        "activated_at": 1517475705,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517475705,
        "currency_code": "USD",
        "current_term_end": 1519894905,
        "current_term_start": 1517475705,
        "customer_id": "__test__KyVkmQSCX2vCA2M",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_advance_invoices": false,
        "has_scheduled_changes": false,
        "id": "__test__KyVkmQSCX2vCA2M",
        "mrr": 0,
        "next_billing_at": 1519894905,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517475706000,
        "started_at": 1517475705,
        "status": "active",
        "updated_at": 1517475706
    }
}

{
    "advance_invoice_schedules": [
        {
            "fixed_interval_schedule": {
                "days_before_renewal": 5,
                "end_schedule_on": "after_number_of_intervals",
                "number_of_occurrences": 3,
                "object": "fixed_interval_schedule",
                "terms_to_charge": 4
            },
            "id": "__test__KyVkmQSCX2vhp3A",
            "object": "advance_invoice_schedule",
            "schedule_type": "fixed_intervals"
        },
        {..}
    ],
    "card": {
        "card_type": "american_express",
        "created_at": 1517475707,
        "customer_id": "__test__KyVkmQSCX2vWP2w",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "payment_source_id": "pm___test__KyVkmQSCX2vXT2y",
        "resource_version": 1517475707000,
        "status": "valid",
        "updated_at": 1517475707
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517475707,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVkmQSCX2vWP2w",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
            "object": "payment_method",
            "reference_id": "tok___test__KyVkmQSCX2vXP2x",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVkmQSCX2vXT2y",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517475707000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517475707
    },
    "subscription": {
        "activated_at": 1517475707,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517475707,
        "currency_code": "USD",
        "current_term_end": 1519894907,
        "current_term_start": 1517475707,
        "customer_id": "__test__KyVkmQSCX2vWP2w",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_advance_invoices": true,
        "has_scheduled_changes": false,
        "id": "__test__KyVkmQSCX2vWP2w",
        "mrr": 0,
        "next_billing_at": 1519462907,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517475707000,
        "started_at": 1517475707,
        "status": "active",
        "updated_at": 1517475707
    }
}

{
    "advance_invoice_schedules": [
        {
            "id": "__test__KyVkmQSCX2vRK2t",
            "object": "advance_invoice_schedule",
            "schedule_type": "specific_dates",
            "specific_dates_schedule": {
                "date": 1518339706,
                "object": "specific_dates_schedule",
                "terms_to_charge": 2
            }
        },
        {..}
    ],
    "card": {
        "card_type": "american_express",
        "created_at": 1517475706,
        "customer_id": "__test__KyVkmQSCX2vM62f",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "payment_source_id": "pm___test__KyVkmQSCX2vNG2h",
        "resource_version": 1517475706000,
        "status": "valid",
        "updated_at": 1517475706
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517475706,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVkmQSCX2vM62f",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
            "object": "payment_method",
            "reference_id": "tok___test__KyVkmQSCX2vNC2g",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVkmQSCX2vNG2h",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517475706000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517475706
    },
    "subscription": {
        "activated_at": 1517475706,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517475706,
        "currency_code": "USD",
        "current_term_end": 1519894906,
        "current_term_start": 1517475706,
        "customer_id": "__test__KyVkmQSCX2vM62f",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_advance_invoices": true,
        "has_scheduled_changes": false,
        "id": "__test__KyVkmQSCX2vM62f",
        "mrr": 0,
        "next_billing_at": 1518339706,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517475706000,
        "started_at": 1517475706,
        "status": "active",
        "updated_at": 1517475706
    }
}

URL Format POST

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

terms_to_charge

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.

.
optional, integer, default=1, min=1

invoice_immediately

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

schedule_type

The type of advance invoice or advance invoicing schedule.
optional, enumerated string

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.

fixed_interval_schedule

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

fixed_interval_schedule[number_of_occurrences]

The number of advance invoices to generate. 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. This parameter is applicable only when fixed_interval_schedule[end_schedule_on] = after_number_of_intervals.
optional, integer, min=1

fixed_interval_schedule[days_before_renewal]

The number of days before each interval that advance invoices are generated.
optional, integer, min=1

fixed_interval_schedule[end_schedule_on]

Specifies when the schedule should end.
optional, enumerated string

Possible values are

after_number_of_intervalsAdvance invoices are generated a specified number of times.specific_dateEnd the advance invoicing schedule on a specific date.subscription_endAdvance invoices are generated for as long as the subscription is active.

fixed_interval_schedule[end_date]

The date when the schedule should end. Advance invoices are not generated beyond this date. It must be at least 1 day before the start of the last billing cycle of the subscription and also within 5 years from the current date. This parameter is only applicable when fixed_interval_schedule[end_schedule_on] = specific_date.
optional, timestamp(UTC) in seconds

specific_dates_schedule

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

specific_dates_schedule[terms_to_charge][0..n]

The number of billing cycles to charge for, on the date specified. Applicable only when schedule_type is specific_dates.
optional, integer

specific_dates_schedule[date][0..n]

The unique id of the member of the advance_invoice_schedule array which corresponds to the specific_dates_schedule that you intend to modify. Only applicable when schedule_type is specific_dates.
optional, timestamp(UTC) in seconds

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

advance_invoice_schedules

Resource object representing advance_invoice_schedule.
optional

Modifies the advance invoicing schedule for a subscription.

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

copy

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

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

Sample Response [ JSON ]

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

{"advance_invoice_schedules": [
    {
        "fixed_interval_schedule": {
            "days_before_renewal": 3,
            "end_schedule_on": "subscription_end",
            "object": "fixed_interval_schedule",
            "terms_to_charge": 1
        },
        "id": "__test__KyVkmQSCX2wAO3i",
        "object": "advance_invoice_schedule",
        "schedule_type": "fixed_intervals"
    },
    {..}
]}

URL Format POST

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

terms_to_charge

The number of billing cycles in one interval.
optional, integer, min=1

schedule_type

The type of advance invoice or advance invoicing schedule.
optional, enumerated string

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.

fixed_interval_schedule

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

fixed_interval_schedule[number_of_occurrences]

fixed_interval_schedule[days_before_renewal]

The number of days before each interval that advance invoices are generated.
optional, integer, min=1

fixed_interval_schedule[end_schedule_on]

Specifies when the schedule should end.
optional, enumerated string

Possible values are

fixed_interval_schedule[end_date]

specific_dates_schedule

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

specific_dates_schedule[id][0..n]

The unique id of the member of the advance_invoice_schedule array which corresponds to the specific_dates_schedule that you intend to modify. Only applicable when schedule_type is specific_dates.
optional, string, max chars=50

specific_dates_schedule[terms_to_charge][0..n]

The number of billing cycles to charge for, on the date specified. Applicable only when schedule_type is specific_dates.
optional, integer

specific_dates_schedule[date][0..n]

advance_invoice_schedules

Resource object representing advance_invoice_schedule.
always returned

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format GET

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

advance_invoice_schedules

Resource object representing advance_invoice_schedule.
always returned

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

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "advance_invoice_schedules": [],
    "subscription": {
        "card": {
            "card_type": "american_express",
            "created_at": 1517475710,
            "customer_id": "__test__KyVkmQSCX2wFs3l",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "not_known",
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
            "iin": "378282",
            "last4": "0005",
            "masked_number": "***********0005",
            "object": "card",
            "payment_source_id": "pm___test__KyVkmQSCX2wGm3n",
            "resource_version": 1517475710000,
            "status": "valid",
            "updated_at": 1517475710
        },
        "customer": {
            "allow_direct_debit": false,
            "auto_collection": "on",
            "card_status": "valid",
            "created_at": 1517475710,
            "deleted": false,
            "excess_payments": 0,
            "id": "__test__KyVkmQSCX2wFs3l",
            "net_term_days": 0,
            "object": "customer",
            "payment_method": {
                "gateway": "chargebee",
                "gateway_account_id": "gw___test__KyVkdtSCX2uP11g",
                "object": "payment_method",
                "reference_id": "tok___test__KyVkmQSCX2wGi3m",
                "status": "valid",
                "type": "card"
            },
            "pii_cleared": "active",
            "preferred_currency_code": "USD",
            "primary_payment_source_id": "pm___test__KyVkmQSCX2wGm3n",
            "promotional_credits": 0,
            "refundable_credits": 0,
            "resource_version": 1517475710000,
            "taxability": "taxable",
            "unbilled_charges": 0,
            "updated_at": 1517475710
        },
        "subscription": {
            "activated_at": 1517475710,
            "billing_period": 1,
            "billing_period_unit": "month",
            "created_at": 1517475710,
            "currency_code": "USD",
            "current_term_end": 1519894910,
            "current_term_start": 1517475710,
            "customer_id": "__test__KyVkmQSCX2wFs3l",
            "deleted": false,
            "due_invoices_count": 0,
            "has_scheduled_advance_invoices": false,
            "has_scheduled_changes": false,
            "id": "__test__KyVkmQSCX2wFs3l",
            "mrr": 0,
            "next_billing_at": 1519894910,
            "object": "subscription",
            "plan_amount": 895,
            "plan_free_quantity": 0,
            "plan_id": "no_trial",
            "plan_quantity": 1,
            "plan_unit_price": 895,
            "resource_version": 1517475710000,
            "started_at": 1517475710,
            "status": "active",
            "updated_at": 1517475710
        }
    }
}

URL Format POST

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

specific_dates_schedule

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

specific_dates_schedule[id][0..n]

When schedule_type = specific_dates, pass the id of the specific_dates_schedule that you want to remove. If not passed, the entire advance_invoice_schedule is removed.
optional, string, max chars=50

subscription

Resource object representing subscription.
always returned

advance_invoice_schedules

Resource object representing advance_invoice_schedule.
optional

Imports a subscription into Chargebee.

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

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/import_subscription \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d status="active" \
     -d current_term_end=1602095400 \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[locale]="fr-CA" \
     -d customer[phone]="+1-949-999-9999" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d billing_cycles=5 \
     -d addons[id][0]="ssl" \
     -d contract_term[action_at_term_end]="renew" \
     -d contract_term_billing_cycle_on_renewal=3 \
     -d contract_term[contract_start]=1509511210 \
     -d contract_term[cancellation_cutoff_period]=3 \
     -d contract_term[created_at]=1509511210 \
     -d contract_term[total_amount_raised]="900" \
     -d contract_term[billing_cycle]=5

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/import_subscription \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d status="active" \
     -d current_term_end=1602095400 \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[locale]="fr-CA" \
     -d customer[phone]="+1-949-999-9999" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d billing_cycles=5 \
     -d addons[id][0]="ssl" \
     -d contract_term[action_at_term_end]="renew" \
     -d contract_term_billing_cycle_on_renewal=3 \
     -d contract_term[contract_start]=1509511210 \
     -d contract_term[cancellation_cutoff_period]=3 \
     -d contract_term[created_at]=1509511210 \
     -d contract_term[total_amount_raised]="900" \
     -d contract_term[billing_cycle]=5

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "state_code": "CA",
            "validation_status": "not_validated",
            "zip": "91789"
        },
        "card_status": "no_card",
        "created_at": 1517505656,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnHhSBWko452Uw",
        "last_name": "Doe",
        "locale": "fr-CA",
        "net_term_days": 0,
        "object": "customer",
        "phone": "+1-949-999-9999",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505656000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505656
    },
    "subscription": {
        "activated_at": 1517505655,
        "addons": [
            {
                "amount": 495,
                "id": "ssl",
                "object": "addon",
                "quantity": 1,
                "unit_price": 495
            },
            {..}
        ],
        "billing_period": 1,
        "billing_period_unit": "month",
        "contract_term": {
            "action_at_term_end": "renew",
            "billing_cycle": 5,
            "cancellation_cutoff_period": 3,
            "contract_end": 1612722600,
            "contract_start": 1509511210,
            "created_at": 1509511210,
            "id": "__test__KyVnHhSBWko4l2Uy",
            "object": "contract_term",
            "remaining_billing_cycles": 4,
            "status": "active",
            "total_contract_value": 6460
        },
        "contract_term_billing_cycle_on_renewal": 3,
        "created_at": 1517505656,
        "currency_code": "USD",
        "current_term_end": 1602095400,
        "current_term_start": 1517505655,
        "customer_id": "__test__KyVnHhSBWko452Uw",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWko452Uw",
        "mrr": 0,
        "next_billing_at": 1602095400,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "remaining_billing_cycles": 4,
        "resource_version": 1517505656000,
        "started_at": 1517505655,
        "status": "active",
        "updated_at": 1517505656
    }
}

URL Format POST

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

id

Id for the new subscription. If not given, this will be auto-generated.
optional, string, max chars=50

client_profile_id

Indicates the Client profile id for the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, string, max chars=50

plan_unit_price_in_decimal

plan_quantity_in_decimal

The decimal representation of the quantity of the plan purchased. Can be provided for quantity-based plans and only when multi-decimal pricing is enabled.
optional, string, max chars=33

plan_id

Identifier of the plan for this subscription.
required, string, max chars=100

plan_quantity

Plan quantity for this subscription.
optional, integer, default=1, min=1

plan_unit_price

Amount that will override the Plan's default price.
optional, in cents, min=0

setup_fee

Amount that will override the default setup fee.
optional, in cents, min=0

trial_end

billing_cycles

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

start_date

auto_collection

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

Possible values are

po_number

Purchase order number for this subscription.
optional, string, max chars=100

coupon_ids[0..n]

Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string

contract_term_billing_cycle_on_renewal

Number of billing cycles the new contract term should run for, on contract renewal. The default value is as specified in the site settings.
optional, integer, min=1, max=100

status

Current state of the subscription.
required, enumerated string

Possible values are

current_term_end

End of the current billing term. Subscription is renewed immediately after this. If not given, this will be calculated based on plan billing cycle.
optional, timestamp(UTC) in seconds

current_term_start

Start of the current billing period of the subscription.
optional, timestamp(UTC) in seconds

trial_start

cancelled_at

Time at which subscription was cancelled or is set to be cancelled.
optional, timestamp(UTC) in seconds

started_at

Time at which the subscription was started. Is null for futuresubscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds

pause_date

resume_date

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.
optional, timestamp(UTC) in seconds

create_current_term_invoice

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.
optional, boolean, default=false

affiliate_token

A unique tracking token.
optional, string, max chars=250

invoice_notes

Notes to be added to any invoice for this subscription.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

customer

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

customer[id]

Id for the new customer. If not given, this will be same as the subscription id.
optional, string, max chars=50

customer[email]

Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70

customer[first_name]

First name of the customer.
optional, string, max chars=150

customer[last_name]

Last name of the customer.
optional, string, max chars=150

customer[company]

Company name of the customer.
optional, string, max chars=250

customer[taxability]

Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable

Possible values are

taxableCustomer is taxable.exempt

Customer is exempted from tax
Optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.

customer[locale]

customer[entity_code]

The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration.
optional, enumerated string

Possible values are

aFederal government.bState government.cTribe/Status Indian/Indian Band.dForeign diplomat.

Show all values[+]

customer[exempt_number]

customer[net_term_days]

The number of days within which the customer has to make payment for the invoice.
optional, integer, default=0

customer[taxjar_exemption_category]

Indicates the exemption type of the customer. This is applicable only if you use Chargebee’s TaxJar integration.
optional, enumerated string

Possible values are

wholesaleWhole-sale.governmentGovernment.otherOther.

customer[phone]

Phone number of the customer.
optional, string, max chars=50

customer[customer_type]

Indicates the type of the customer. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

customer[auto_collection]

Whether payments needs to be collected automatically for this customer.
optional, enumerated string, default=on

Possible values are

onWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.offAutomatic collection of charges will not be made. All payments must be recorded offline.

customer[allow_direct_debit]

Whether the customer can pay via Direct Debit.
optional, boolean, default=false

customer[vat_number]

VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20

contract_term

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

contract_term[id]

Id that uniquely identifies the contract term in the site.
optional, string, max chars=50

contract_term[created_at]

The date when the contract term was created.
optional, timestamp(UTC) in seconds

contract_term[contract_start]

The start date of the contract term.
optional, timestamp(UTC) in seconds

contract_term[billing_cycle]

The number of billing cycles of the subscription that the contract term is for.
optional, integer, min=0

contract_term[total_amount_raised]

The amount raised for the contract term up until the time of importing the subscription. This gets added to total_contract_value.
optional, in cents, default=0, min=0

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
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 cancel.

contract_term[cancellation_cutoff_period]

card

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

card[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

card[first_name]

Cardholder's first name.
optional, string, max chars=50

card[last_name]

Cardholder's last name.
optional, string, max chars=50

card[number]

The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500

card[expiry_month]

Card expiry month.
required if card provided, integer, min=1, max=12

card[expiry_year]

Card expiry year.
required if card provided, integer

card[cvv]

The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520

card[billing_addr1]

Address line 1, as available in card billing address.
optional, string, max chars=150

card[billing_addr2]

Address line 2, as available in card billing address.
optional, string, max chars=150

card[billing_city]

City, as available in card billing address.
optional, string, max chars=50

card[billing_state_code]

card[billing_state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

card[billing_zip]

Postal or Zip code, as available in card billing address.
optional, string, max chars=20

card[billing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

payment_method

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

payment_method[type]

The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
optional, enumerated string

Possible values are

Show all values[+]

payment_method[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

payment_method[reference_id]

payment_method[issuing_country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

billing_address

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

billing_address[first_name]

The first name of the billing contact.
optional, string, max chars=150

billing_address[last_name]

The last name of the billing contact.
optional, string, max chars=150

billing_address[email]

The email address.
optional, string, max chars=70

billing_address[company]

The company name.
optional, string, max chars=250

billing_address[phone]

The phone number.
optional, string, max chars=50

billing_address[line1]

Address line 1.
optional, string, max chars=150

billing_address[line2]

Address line 2.
optional, string, max chars=150

billing_address[line3]

Address line 3.
optional, string, max chars=150

billing_address[city]

The name of the city.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

billing_address[zip]

Zip or Postal code.
optional, string, max chars=20

billing_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

billing_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

shipping_address

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

shipping_address[first_name]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

shipping_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

transaction

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

transaction[amount]

The payment transaction amount. This parameter should be passed only if the invoice is created for current term.
optional, in cents, min=1

transaction[payment_method]

The payment method of this transaction. This parameter should be passed only if the invoice is created for current term.
optional, enumerated string, default=card

Possible values are

cashCash.checkCheck.

bank_transferBank Transfer.otherPayment Methods other than the above types.

Show all values[+]

transaction[reference_number]

The reference number for this transaction. For example, check number in case of check payment_method. This parameter should be passed only if the invoice is created for current term.
optional, string, max chars=100

transaction[date]

The date of occurence of the transaction. This parameter should be passed only if the invoice is created for current term.
optional, timestamp(UTC) in seconds

addons

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

addons[id][0..n]

Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100

addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1

addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

addons[unit_price][0..n]

addons[unit_price_in_decimal][0..n]

addons[billing_cycles][0..n]

event_based_addons

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

event_based_addons[id][0..n]

A unique 'id' used to identify the addon.
optional, string, max chars=100

event_based_addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1

event_based_addons[unit_price][0..n]

Amount that will override the Addon's default price.
optional, in cents, min=0

event_based_addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

event_based_addons[unit_price_in_decimal][0..n]

event_based_addons[service_period_in_days][0..n]

Defines service period of the addon in days from the day of charge.
optional, integer, min=1, max=730

event_based_addons[on_event][0..n]

Event on which this addon will be charged.
optional, enumerated string

Possible values are

event_based_addons[charge_once][0..n]

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true

charged_event_based_addons

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

charged_event_based_addons[id][0..n]

Addon id.
optional, string, max chars=100

charged_event_based_addons[last_charged_at][0..n]

Timestamp indicating when this add-on was last charged for this subscription.
optional, timestamp(UTC) in seconds

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

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

Sample Request

curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWkp5t2VV/import_subscription \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d status="in_trial" \
     -d trial_end=1602095400 \
     -d billing_cycles=5 \
     -d addons[id][0]="ssl" \
     -d contract_term[action_at_term_end]="renew" \
     -d contract_term_billing_cycle_on_renewal=3 \
     -d contract_term[contract_start]=1509511210 \
     -d contract_term[cancellation_cutoff_period]=3 \
     -d contract_term[created_at]=1509511210 \
     -d contract_term[total_amount_raised]="900" \
     -d contract_term[billing_cycle]=5

copy

curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWkp5t2VV/import_subscription \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d status="in_trial" \
     -d trial_end=1602095400 \
     -d billing_cycles=5 \
     -d addons[id][0]="ssl" \
     -d contract_term[action_at_term_end]="renew" \
     -d contract_term_billing_cycle_on_renewal=3 \
     -d contract_term[contract_start]=1509511210 \
     -d contract_term[cancellation_cutoff_period]=3 \
     -d contract_term[created_at]=1509511210 \
     -d contract_term[total_amount_raised]="900" \
     -d contract_term[billing_cycle]=5

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505659,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__KyVnHhSBWkp5t2VV",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505659000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505659
    },
    "subscription": {
        "addons": [
            {
                "amount": 495,
                "id": "ssl",
                "object": "addon",
                "quantity": 1,
                "unit_price": 495
            },
            {..}
        ],
        "billing_period": 1,
        "billing_period_unit": "month",
        "contract_term": {
            "action_at_term_end": "renew",
            "billing_cycle": 5,
            "cancellation_cutoff_period": 3,
            "contract_end": 1615141800,
            "contract_start": 1509511210,
            "created_at": 1509511210,
            "id": "__test__KyVnHhSBWkp8U2VZ",
            "object": "contract_term",
            "remaining_billing_cycles": 5,
            "status": "active",
            "total_contract_value": 7850
        },
        "contract_term_billing_cycle_on_renewal": 3,
        "created_at": 1517505659,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWkp5t2VV",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkp852VX",
        "next_billing_at": 1602095400,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "remaining_billing_cycles": 5,
        "resource_version": 1517505659000,
        "started_at": 1517505659,
        "status": "in_trial",
        "trial_end": 1602095400,
        "trial_start": 1517505659,
        "updated_at": 1517505659
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/import_subscription

id

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
optional, string, max chars=50

plan_unit_price_in_decimal

plan_quantity_in_decimal

The decimal representation of the quantity of the plan purchased. Can be provided for quantity-based plans and only when multi-decimal pricing is enabled.
optional, string, max chars=33

plan_id

Identifier of the plan for this subscription.
required, string, max chars=100

plan_quantity

Plan quantity for this subscription.
optional, integer, default=1, min=1

plan_unit_price

Amount that will override the Plan's default price.
optional, in cents, min=0

setup_fee

Amount that will override the default setup fee.
optional, in cents, min=0

trial_end

billing_cycles

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

start_date

auto_collection

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

Possible values are

po_number

Purchase order number for this subscription.
optional, string, max chars=100

coupon_ids[0..n]

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

payment_source_id

Id of the payment source to be attached to this subscription.
optional, string, max chars=40

status

Current state of the subscription.
required, enumerated string

Possible values are

current_term_end

End of the current billing term. Subscription is renewed immediately after this. If not given, this will be calculated based on plan billing cycle.
optional, timestamp(UTC) in seconds

current_term_start

Start of the current billing period of the subscription.
optional, timestamp(UTC) in seconds

trial_start

cancelled_at

Time at which subscription was cancelled or is set to be cancelled.
optional, timestamp(UTC) in seconds

started_at

Time at which the subscription was started. Is null for futuresubscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds

pause_date

resume_date

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.
optional, timestamp(UTC) in seconds

contract_term_billing_cycle_on_renewal

Number of billing cycles the new contract term should run for, on contract renewal. The default value is as specified in the site settings.
optional, integer, min=1, max=100

create_current_term_invoice

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.
optional, boolean, default=false

invoice_notes

Notes to be added to any invoice for this subscription.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription.
optional, jsonobject

contract_term

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

contract_term[id]

Id that uniquely identifies the contract term in the site.
optional, string, max chars=50

contract_term[created_at]

The date when the contract term was created.
optional, timestamp(UTC) in seconds

contract_term[contract_start]

The start date of the contract term.
optional, timestamp(UTC) in seconds

contract_term[billing_cycle]

The number of billing cycles of the subscription that the contract term is for.
optional, integer, min=0

contract_term[total_amount_raised]

The amount raised for the contract term up until the time of importing the subscription. This gets added to total_contract_value.
optional, in cents, default=0, min=0

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
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 cancel.

contract_term[cancellation_cutoff_period]

transaction

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

transaction[amount]

The payment transaction amount. This parameter should be passed only if the invoice is created for current term.
optional, in cents, min=1

transaction[payment_method]

The payment method of this transaction. This parameter should be passed only if the invoice is created for current term.
optional, enumerated string, default=card

Possible values are

cashCash.checkCheck.

bank_transferBank Transfer.otherPayment Methods other than the above types.

Show all values[+]

transaction[reference_number]

transaction[date]

The date of occurence of the transaction. This parameter should be passed only if the invoice is created for current term.
optional, timestamp(UTC) in seconds

shipping_address

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

shipping_address[first_name]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

shipping_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

addons

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

addons[id][0..n]

Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100

addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1

addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

addons[unit_price][0..n]

addons[unit_price_in_decimal][0..n]

addons[billing_cycles][0..n]

event_based_addons

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

event_based_addons[id][0..n]

A unique 'id' used to identify the addon.
optional, string, max chars=100

event_based_addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1

event_based_addons[unit_price][0..n]

Amount that will override the Addon's default price.
optional, in cents, min=0

event_based_addons[quantity_in_decimal][0..n]

The decimal representation of the quantity of the addon. Can be provided for quantity-based addons and only when multi-decimal pricing is enabled.
optional, string, max chars=33

event_based_addons[unit_price_in_decimal][0..n]

event_based_addons[service_period_in_days][0..n]

Defines service period of the addon in days from the day of charge.
optional, integer, min=1, max=730

event_based_addons[on_event][0..n]

Event on which this addon will be charged.
optional, enumerated string

Possible values are

event_based_addons[charge_once][0..n]

If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true

charged_event_based_addons

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

charged_event_based_addons[id][0..n]

Addon id.
optional, string, max chars=100

charged_event_based_addons[last_charged_at][0..n]

Timestamp indicating when this add-on was last charged for this subscription.
optional, timestamp(UTC) in seconds

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

Import previous contract terms. Error is thrown if there’s no subscription identified for the subscription_id.
For contract terms in active state, import is only allowed 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@chargebee.com to get this enabled.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkogZ2VF/import_contract_term \
     -X POST  \
     -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

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkogZ2VF/import_contract_term \
     -X POST  \
     -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"

Sample Response [ JSON ]

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

URL Format POST

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

contract_term_billing_cycle_on_renewal

Number of billing cycles the new contract term should run for, on contract renewal. The default value is as specified in the site settings.
optional, integer, min=1, max=100

contract_term

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

contract_term[id]

Id that uniquely identifies the contract term in the site.
optional, string, max chars=50

contract_term[created_at]

The date when the contract term was created.
optional, timestamp(UTC) in seconds

contract_term[contract_start]

The start date of the contract term.
optional, timestamp(UTC) in seconds

contract_term[contract_end]

The end date of the contract term.
optional, timestamp(UTC) in seconds

contract_term[status]

Current status of contract.
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:

a change in the subscription caused a subscription term reset.
the subscription was cancelled due to non-payment.

.terminatedThe contract term was terminated ahead of completion.

contract_term[total_amount_raised]

The amount raised for the contract term up until the time of importing the subscription. This gets added to total_contract_value.
optional, in cents, default=0, min=0

contract_term[total_contract_value]

contract_term[billing_cycle]

The number of billing cycles of the subscription that the contract term is for.
optional, integer, min=0

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
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 cancel.

contract_term[cancellation_cutoff_period]

contract_term

Resource object representing contract_term.
always returned

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__KyVnHhSBWkqEX2W6/override_billing_profile \
     -X POST  \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__KyVnHhSBWkqIK2WD" \
     -d auto_collection="on"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkqEX2W6/override_billing_profile \
     -X POST  \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__KyVnHhSBWkqIK2WD" \
     -d auto_collection="on"

Sample Response [ JSON ]

{
    "payment_source": {
        "card": {
            "brand": "american_express",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "not_known",
            "iin": "378282",
            "last4": "0005",
            "masked_number": "***********0005",
            "object": "card"
        },
        "created_at": 1517505664,
        "customer_id": "__test__KyVnHhSBWkqDI2W4",
        "deleted": false,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
        "id": "pm___test__KyVnHhSBWkqIK2WD",
        "object": "payment_source",
        "reference_id": "tok___test__KyVnHhSBWkqIE2WC",
        "resource_version": 1517505664000,
        "status": "valid",
        "type": "card",
        "updated_at": 1517505664
    },
    "subscription": {
        "activated_at": 1517505664,
        "auto_collection": "on",
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505664,
        "currency_code": "USD",
        "current_term_end": 1519924864,
        "current_term_start": 1517505664,
        "customer_id": "__test__KyVnHhSBWkqDI2W4",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkqEX2W6",
        "mrr": 0,
        "next_billing_at": 1519924864,
        "object": "subscription",
        "payment_source_id": "pm___test__KyVnHhSBWkqIK2WD",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505664000,
        "started_at": 1517505664,
        "status": "active",
        "updated_at": 1517505664
    }
}

URL Format POST

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

payment_source_id

Unique identifier of the payment source to be attached to this subscription.
optional, string, max chars=40

auto_collection

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

Possible values are

subscription

Resource object representing subscription.
always returned

payment_source

Resource object representing payment_source.
optional

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__KyVnHhSBWknaq2Ui/delete \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "card": {
        "card_type": "american_express",
        "created_at": 1517505654,
        "customer_id": "__test__KyVnHhSBWknaq2Ui",
        "expiry_month": 12,
        "expiry_year": 2022,
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWknbq2Uk",
        "resource_version": 1517505654000,
        "status": "valid",
        "updated_at": 1517505654
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505654,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWknaq2Ui",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWknbm2Uj",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWknbq2Uk",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505654000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505654
    },
    "subscription": {
        "activated_at": 1517505654,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505654,
        "currency_code": "USD",
        "current_term_end": 1519924854,
        "current_term_start": 1517505654,
        "customer_id": "__test__KyVnHhSBWknaq2Ui",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWknaq2Ui",
        "mrr": 0,
        "next_billing_at": 1519924854,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505654000,
        "started_at": 1517505654,
        "status": "active",
        "updated_at": 1517505654
    }
}

URL Format POST

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

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

Pausing a subscription will move the subscription from its current state to Paused state, and will stop all recurring actions.

You could schedule the pause by passing specific_date/end_of_term parameter in pause_option. If scheduled, the subscription will not be paused until the specific_date/end_of_term is reached.

UNBILLED CHARGES

Any unbilled charges present in the subscription can be invoiced by specifying invoice or no_action. If invoice is chosen, automatic charge will be attempted on the payment method available if the customer has enabled auto-collection. If payment collection fails or when auto-collection is not enabled, the invoice will be closed as unpaid.
If no_action is chosen, charges will be added to the resumption invoice.

INVOICE DUNNING HANDLING

If invoice is in the dunning cycle, invoice_dunning_handing allows you to stop or continue dunning.

Note:

Applicable only for active/non-renewing subscriptions.
For non-renewing subscriptions, pause_date and resume_date should be before the cancellation date. If paused indefinitely, the subscription will be cancelled on the cancelled_at date.
Advance charges, if any, will be refunded as credits.

Sample Request

# pauses the subscription on end of term.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkqkc2WM/pause \
     -X POST  \
     -u {site_api_key}:\
     -d pause_option="end_of_term"

copy

# pauses the subscription on end of term.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkqkc2WM/pause \
     -X POST  \
     -u {site_api_key}:\
     -d pause_option="end_of_term"

# pauses the subscription immediately .Invoice will be raised for the
# unbilledcharges present.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkr7v2WU/pause \
     -X POST  \
     -u {site_api_key}:\
     -d pause_option="immediately" \
     -d unbilled_charges_handling="invoice"

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505666,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkqkc2WM",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505666000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505666
    },
    "subscription": {
        "activated_at": 1517505666,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505666,
        "currency_code": "USD",
        "current_term_end": 1519924866,
        "current_term_start": 1517505666,
        "customer_id": "__test__KyVnHhSBWkqkc2WM",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505666,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkqkc2WM",
        "mrr": 0,
        "object": "subscription",
        "pause_date": 1519924866,
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505666000,
        "started_at": 1517505666,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505666
    }
}

{
    "card": {
        "card_type": "american_express",
        "created_at": 1517505667,
        "customer_id": "__test__KyVnHhSBWkr7v2WU",
        "expiry_month": 2,
        "expiry_year": 2022,
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWkr8f2WW",
        "resource_version": 1517505667000,
        "status": "valid",
        "updated_at": 1517505667
    },
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517505667,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkr7v2WU",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWkr8b2WV",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWkr8f2WW",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505667000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505667
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 895,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWkr7v2WU",
        "date": 1517505667,
        "deleted": false,
        "due_date": 1517505667,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__21",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "customer_id": "__test__KyVnHhSBWkr7v2WU",
                "date_from": 1517505667,
                "date_to": 1519924867,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnHhSBWkr9L2WY",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnHhSBWkr7v2WU",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 895,
                "applied_at": 1517505667,
                "txn_amount": 895,
                "txn_date": 1517505667,
                "txn_id": "txn___test__KyVnHhSBWkrCH2Wf",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 895,
        "object": "invoice",
        "paid_at": 1517505667,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517505667000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 895,
        "subscription_id": "__test__KyVnHhSBWkr7v2WU",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517505667,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1517505667,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505667,
        "currency_code": "USD",
        "current_term_end": 1519924867,
        "current_term_start": 1517505667,
        "customer_id": "__test__KyVnHhSBWkr7v2WU",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkr7v2WU",
        "mrr": 0,
        "object": "subscription",
        "pause_date": 1517505667,
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505667000,
        "started_at": 1517505667,
        "status": "paused",
        "updated_at": 1517505667
    }
}

URL Format POST

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

pause_option

List of options to pause the subscription.
optional, enumerated string

Possible values are

immediatelyPause immediately.end_of_termPause at the end of current term.specific_datePause on a specific date.

pause_date

Date on which the subscription will be paused. Applicable when 'specific_date' option is chosen in the pause_option field.
optional, timestamp(UTC) in seconds

unbilled_charges_handling

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

Possible values are

no_actionRetain as unbilled.invoiceInvoice charges.

invoice_dunning_handling

Handles dunning for invoices already in the dunning cycle, when subscription is paused. Applicable when pause_option is set as 'immediately'.
optional, enumerated string

Possible values are

continueContinue dunning.stopStop dunning.

resume_date

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.
optional, timestamp(UTC) in seconds

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

credit_notes

Resource object representing credit_note.
optional

Cancelling a subscription will move the subscription from its current state to Cancelled, and will stop all recurring actions.

You could schedule the cancellation by passing end_of_term parameter as true. If scheduled, the subscription status will be set to non_renewing if it is in active state, until the end of term, and then cancelled. A subscription's state will not change if it is in in_trial state. However, cancellation will be scheduled at the end of the trial.

CREDIT OPTION

On subscription cancellation, credits can be issued against current term charges of the subscription by using credit_option_for_current_term_charges. You can choose to either provide no credits, prorate credits for the unused period or issue full credits for the current term charges.

UNBILLED CHARGES

Any unbilled charges present in the subscription can either be invoiced or deleted by specifying unbilled_charges_option. Note that automatic charge will be attempted on the payment method available if the customer has enabled auto-collection. If not, the invoice will be closed as unpaid.

ACCOUNT RECEIVABLES

Specifying account_receivables_handling allows you to close invoices of the subscription which have amounts due. The invoices are chosen for payment collection or for writing off the due amount 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.

If specified as write_off, the amount due of past invoices will be written-off. Note: If the invoices of the subscription are consolidated, and any of the subscriptions in the consolidated invoice are still active(future, in-trial, active, and non-renewing), these invoices will not be selected for the write-off operation.

ACCOUNT PAYABLES

Specifying refundable_credits_handling allows you to provide refunds for refundable credits remaining, after they are applied to a subscription’s due invoices. The refund initiated will be asynchronous and the payment refunded event will be triggered on refund success. Note: Consolidated credit notes of the subscription will not be selected for refund.

Canceling Contract Terms

Subscriptions with contract terms can only be cancelled 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
end_of_term or cancel_at should not be passed when using contract terms; use contract_term_cancel_option instead.
The event_based_addons parameter is used when canceling contract terms 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 an event-based addon with the on_event parameter set to contract_term_termination

Notes

Advance charges, if any, will be refunded as credits.

Sample Request

# cancels the subscription after the term ends.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkekU2RC/cancel \
     -X POST  \
     -u {site_api_key}:\
     -d end_of_term="true"

copy

# cancels the subscription after the term ends.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkekU2RC/cancel \
     -X POST  \
     -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__KyVnHhSBWkf9f2RK/cancel \
     -X POST  \
     -u {site_api_key}:\
     -d credit_option_for_current_term_charges="prorate" \
     -d end_of_term="false"

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505620,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkekU2RC",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505620000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505620
    },
    "subscription": {
        "activated_at": 1517505620,
        "billing_period": 1,
        "billing_period_unit": "month",
        "cancelled_at": 1519924820,
        "created_at": 1517505620,
        "currency_code": "USD",
        "current_term_end": 1519924820,
        "current_term_start": 1517505620,
        "customer_id": "__test__KyVnHhSBWkekU2RC",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505620,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkekU2RC",
        "mrr": 0,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "remaining_billing_cycles": 0,
        "resource_version": 1517505620000,
        "started_at": 1517505620,
        "status": "non_renewing",
        "total_dues": 895,
        "updated_at": 1517505620
    }
}

{
    "card": {
        "card_type": "american_express",
        "created_at": 1517505621,
        "customer_id": "__test__KyVnHhSBWkf9f2RK",
        "expiry_month": 2,
        "expiry_year": 2022,
        "funding_type": "not_known",
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "payment_source_id": "pm___test__KyVnHhSBWkfAz2RM",
        "resource_version": 1517505621000,
        "status": "valid",
        "updated_at": 1517505621
    },
    "credit_notes": [
        {
            "allocations": [],
            "amount_allocated": 0,
            "amount_available": 895,
            "amount_refunded": 0,
            "base_currency_code": "USD",
            "create_reason_code": "Subscription Cancellation",
            "currency_code": "USD",
            "customer_id": "__test__KyVnHhSBWkf9f2RK",
            "date": 1517505621,
            "deleted": false,
            "exchange_rate": 1,
            "fractional_correction": 0,
            "id": "__demo_cn__1",
            "line_item_discounts": [],
            "line_item_taxes": [],
            "line_items": [
                {
                    "amount": 895,
                    "customer_id": "__test__KyVnHhSBWkf9f2RK",
                    "date_from": 1517505621,
                    "date_to": 1519924821,
                    "description": "No Trial - Prorated Credits for 01-Feb-2018 - 01-Mar-2018",
                    "discount_amount": 0,
                    "entity_id": "no_trial",
                    "entity_type": "plan",
                    "id": "li___test__KyVnHhSBWkfHJ2Ra",
                    "is_taxed": false,
                    "item_level_discount_amount": 0,
                    "object": "line_item",
                    "pricing_model": "per_unit",
                    "quantity": 1,
                    "subscription_id": "__test__KyVnHhSBWkf9f2RK",
                    "tax_amount": 0,
                    "tax_exempt_reason": "tax_not_configured",
                    "unit_amount": 895
                },
                {..}
            ],
            "linked_refunds": [],
            "object": "credit_note",
            "price_type": "tax_exclusive",
            "reason_code": "subscription_cancellation",
            "reference_invoice_id": "__demo_inv__3",
            "resource_version": 1517505622000,
            "round_off_amount": 0,
            "status": "refund_due",
            "sub_total": 895,
            "subscription_id": "__test__KyVnHhSBWkf9f2RK",
            "taxes": [],
            "total": 895,
            "type": "refundable",
            "updated_at": 1517505622
        },
        {..}
    ],
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "balances": [
            {
                "balance_currency_code": "USD",
                "currency_code": "USD",
                "excess_payments": 0,
                "object": "customer_balance",
                "promotional_credits": 0,
                "refundable_credits": 895,
                "unbilled_charges": 0
            },
            {..}
        ],
        "card_status": "valid",
        "created_at": 1517505621,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkf9f2RK",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__KyVnGlSBWkdgV1e9",
            "object": "payment_method",
            "reference_id": "tok___test__KyVnHhSBWkfAq2RL",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__KyVnHhSBWkfAz2RM",
        "promotional_credits": 0,
        "refundable_credits": 895,
        "resource_version": 1517505622000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505622
    },
    "subscription": {
        "activated_at": 1517505621,
        "billing_period": 1,
        "billing_period_unit": "month",
        "cancelled_at": 1517505621,
        "created_at": 1517505621,
        "currency_code": "USD",
        "current_term_end": 1517505621,
        "current_term_start": 1517505621,
        "customer_id": "__test__KyVnHhSBWkf9f2RK",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkf9f2RK",
        "mrr": 0,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505622000,
        "started_at": 1517505621,
        "status": "cancelled",
        "updated_at": 1517505622
    }
}

URL Format POST

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

end_of_term

Set this to true if you want to cancel the subscription at the end of the current subscription billing cycle.
optional, boolean, default=false

cancel_at

Specify the date at which you want to cancel the subscription. Do not pass if end_of_term is passed as true.
optional, timestamp(UTC) in seconds

credit_option_for_current_term_charges

Specify this if you want to issue credits against the current term charges. Not applicable when 'end_of_term' is true.
optional, enumerated string

Possible values are

noneNo credits will be issued against current term charges.prorateProrated credits for the unused period will be issued against current term charges.fullCredits will be issued for all the current term charges.

unbilled_charges_option

Applicable when unbilled charges are present for this subscription. If specified as delete, these charges will be deleted instead of getting invoiced immediately. Note: On the invoice raised, an automatic charge will be attempted on the payment method available if customer's auto-collection property is ‘ON’. Not applicable when 'end_of_term' is true.
optional, enumerated string

Possible values are

invoiceUnbilled charges will be raised as an invoice. An attempt to collect payment will be made.deleteUnbilled charges will be deleted.

account_receivables_handling

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.
optional, enumerated string

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.

refundable_credits_handling

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.
optional, enumerated string

Possible values are

no_actionNo action is taken. .schedule_refundInitiates refund of the remaining credits.

contract_term_cancel_option

Cancels the current contract term.

terminate_immediately immediately does the following:
- sets the contract term status to terminated.
- Cancels the subscription.
- Collects any termination fee.
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.

.
optional, enumerated string

Possible values are

terminate_immediatelyTerminate immediately.end_of_contract_termEnd of contract term.

cancel_reason_code

event_based_addons

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

event_based_addons[id][0..n]

The unique id of the event-based addon that represents the termination fee.
optional, string, max chars=100

event_based_addons[quantity][0..n]

The quantity associated with the termination fee. Applicable only when the addon for the termination charge is quantity-based.
optional, integer, min=1

event_based_addons[unit_price][0..n]

The termination fee. In case it is quantity-based, this is the fee per unit.
optional, in cents, min=0

event_based_addons[service_period_in_days][0..n]

The service period of the termination fee—expressed in days—starting from the current date.
optional, integer, min=1, max=730

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

credit_notes

Resource object representing credit_note.
optional

This operation 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.

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.

Sample Request

# resumes a subscription immediately by scheduling payment collection for unpaid
# invoices.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkuL42Xz/resume \
     -X POST  \
     -u {site_api_key}:\
     -d resume_option="immediately" \
     -d unpaid_invoices_handling="schedule_payment_collection"

copy

# resumes a subscription immediately by scheduling payment collection for unpaid
# invoices.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkuL42Xz/resume \
     -X POST  \
     -u {site_api_key}:\
     -d resume_option="immediately" \
     -d unpaid_invoices_handling="schedule_payment_collection"

# resumes the subscription on a specific date.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkulN2Y8/resume \
     -X POST  \
     -u {site_api_key}:\
     -d resume_option="specific_date" \
     -d resume_date=1518110481

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505679,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkuL42Xz",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505679000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505679
    },
    "subscription": {
        "activated_at": 1517505679,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505679,
        "currency_code": "USD",
        "current_term_end": 1519924879,
        "current_term_start": 1517505679,
        "customer_id": "__test__KyVnHhSBWkuL42Xz",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505679,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkuL42Xz",
        "mrr": 0,
        "next_billing_at": 1519924879,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505680000,
        "started_at": 1517505679,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505680
    }
}

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505681,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkulN2Y8",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505681000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505681
    },
    "subscription": {
        "activated_at": 1517505681,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505681,
        "currency_code": "USD",
        "current_term_end": 1519924881,
        "current_term_start": 1517505681,
        "customer_id": "__test__KyVnHhSBWkulN2Y8",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505681,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkulN2Y8",
        "mrr": 0,
        "next_billing_at": 1519924881,
        "object": "subscription",
        "pause_date": 1517505681,
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505681000,
        "resume_date": 1518110481,
        "started_at": 1517505681,
        "status": "paused",
        "total_dues": 895,
        "updated_at": 1517505681
    }
}

URL Format POST

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

resume_option

List of options to resume the subscription.
optional, enumerated string

Possible values are

immediatelyResume immediately.specific_dateResume on a specific date.

resume_date

Date on which the subscription will be resumed. Applicable when resume_option is set as 'specific_date'.
optional, timestamp(UTC) in seconds

charges_handling

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.
optional, enumerated string

Possible values are

invoice_immediatelyInvoice immediately.add_to_unbilled_chargesAdd to unbilled charges.

unpaid_invoices_handling

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.
optional, enumerated string

Possible values are

no_actionRetain as unpaid.schedule_payment_collectionCollect payment.

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_info]

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

invoice

Resource object representing invoice.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

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.

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505676,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWktUL2Xh",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505676000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505676
    },
    "subscription": {
        "activated_at": 1517505676,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505676,
        "currency_code": "USD",
        "current_term_end": 1519924876,
        "current_term_start": 1517505676,
        "customer_id": "__test__KyVnHhSBWktUL2Xh",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505676,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWktUL2Xh",
        "mrr": 0,
        "next_billing_at": 1519924876,
        "object": "subscription",
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505677000,
        "started_at": 1517505676,
        "status": "active",
        "total_dues": 895,
        "updated_at": 1517505677
    }
}

URL Format POST

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

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

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.

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505678,
        "deleted": false,
        "excess_payments": 0,
        "id": "__test__KyVnHhSBWkty42Xq",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505678000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505678
    },
    "subscription": {
        "activated_at": 1517505678,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505678,
        "currency_code": "USD",
        "current_term_end": 1519924878,
        "current_term_start": 1517505678,
        "customer_id": "__test__KyVnHhSBWkty42Xq",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505678,
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWkty42Xq",
        "mrr": 0,
        "object": "subscription",
        "pause_date": 1517505678,
        "plan_amount": 895,
        "plan_free_quantity": 0,
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "plan_unit_price": 895,
        "resource_version": 1517505678000,
        "started_at": 1517505678,
        "status": "paused",
        "total_dues": 895,
        "updated_at": 1517505678
    }
}

URL Format POST

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

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

Sample subscription [ JSON ]

API Index URL GET

Subscription attributes

Create a subscription¶

Future Subscriptions

Trial Period

Invoice

Card details

Billing Address

Related Tutorials

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Create subscription for customer¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List subscriptions¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

List contract terms for a subscription¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Retrieve a subscription¶

Sample Response [ JSON ]

URL Format GET

Returns

Sample admin console URL

Retrieve with scheduled changes¶

Sample Response [ JSON ]

URL Format GET

Returns

Remove scheduled changes¶

Sample Response [ JSON ]

URL Format POST

Returns

Remove scheduled cancellation¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Remove coupons¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update a subscription¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Change term end¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Reactivate a subscription¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Add charge at term end¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns