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 ]

{
    "id": "8avVGOkx8U1MX",
    "customer_id": "8avVGOkx8U1MX",
    "plan_id": "basic",
    "plan_quantity": 1,
    "plan_unit_price": 900,
    "billing_period": 1,
    "billing_period_unit": "month",
    "plan_free_quantity": 0,
    "status": "non_renewing",
    "trial_start": 1412101812,
    "trial_end": 1414780212,
    "current_term_start": 1496255412,
    "current_term_end": 1498847412,
    "remaining_billing_cycles": 0,
    "created_at": 1412101812,
    "started_at": 1412101812,
    "activated_at": 1414780212,
    "cancelled_at": 1498847412,
    "updated_at": 1496825846,
    "has_scheduled_changes": false,
    "resource_version": 1496825846000,
    "deleted": false,
    "object": "subscription",
    "currency_code": "USD",
    "due_invoices_count": 2,
    "due_since": 1438367412,
    "total_dues": 1800,
    "mrr": 900,
    "exchange_rate": 1.0,
    "base_currency_code": "USD",
    "shipping_address": {
        "first_name": "Benjamin",
        "last_name": "Ross",
        "company": "Acme Inc",
        "phone": "+1 (614) 226-4809",
        "line1": "345, Redington Av",
        "line2": "Suite 1200",
        "city": "Los Angeles",
        "state_code": "CA",
        "state": "California",
        "country": "US",
        "validation_status": "not_validated",
        "object": "shipping_address"
    }
}

API Index URL GET

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

id

A unique identifier to identify the subscription. You will use this to perform all operations on this subscription.
string, max chars=50

customer_id

Identifier of the customer with whom this subscription is associated.
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

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

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.cancelledThe subscription has been cancelled. No new recurring actions will take place, but any pending payments will be collected.

start_date

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

trial_start

Start of the trial period for the subscription. Presence of this value for 'future' subscription implies the subscription will go into 'trial' state when it starts.
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 'trial' state when it starts.
optional, timestamp(UTC) in seconds

current_term_start

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

current_term_end

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

next_billing_at

Date on which the next billing happens.
optional, timestamp(UTC) in seconds

remaining_billing_cycles

The number of billing cycles this subscription will run.
optional, integer, min=0

po_number

Purchase Order Number for this subscription.
optional, string, max chars=100

created_at

Subscription created time.
optional, timestamp(UTC) in seconds

started_at

Time at which the subscription got started. Will be null for 'future' subscriptions 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 state.
optional, timestamp(UTC) in seconds

cancelled_at

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

cancel_reason

Possible reason the subscription might be cancelled.
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 token (such as shopping cart id). Used in refersion integration (a affiliate management service). This token should be same as the id that is passed to the tracking pixel url.
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 this subscription was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.
Note: This value does not change when the following attributes are changed: due_invoices_count, due_since, total_dues.
optional, timestamp(UTC) in seconds

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

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. All payments must be recorded offline.

due_invoices_count

Total number of invoices that are due for payment.
optional, integer

due_since

Time since this subscription has unpaid invoices.
optional, timestamp(UTC) in seconds

total_dues

Outstanding balance amount for this subscription.
optional, in cents, min=0

mrr

Monthly recurring revenue for the subscription.
Note: This may not return accurate values since updated asynchronously.
optional, in cents, min=1

exchange_rate

Exchange rate used for base currency conversion.
optional, bigdecimal, min=1E-9, max=999999999.999999999

base_currency_code

Base currency code (ISO 4217 format).
optional, string, max chars=3

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=1000

meta_data

Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject

deleted

Indicates that this resource has been deleted.
boolean

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

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

First name.
optional, string, max chars=150

last_name

Last name.
optional, string, max chars=150

email

Email.
optional, string, max chars=70

company

Company name.
optional, string, max chars=250

phone

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

City.
optional, string, max chars=50

state_code

The ISO 3166-2 state/province code. Supported only for countries US and Canada.
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

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. Please refer this 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.

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 ]

{
    "subscription": {
        "id": "8asyvQLqrimA4N",
        "customer_id": "8asyvQLqrimA4N",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "in_trial",
        "trial_start": 1496826087,
        "trial_end": 1499418087,
        "next_billing_at": 1499418087,
        "created_at": 1496826087,
        "started_at": 1496826087,
        "updated_at": 1496826087,
        "has_scheduled_changes": false,
        "resource_version": 1496826087000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 0
    },
    "customer": {
        "id": "8asyvQLqrimA4N",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@user.com",
        "phone": "+1-949-999-9999",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1496826087,
        "taxability": "taxable",
        "updated_at": 1496826087,
        "locale": "fr-CA",
        "resource_version": 1496826087000,
        "deleted": false,
        "object": "customer",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "card_status": "no_card",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    }
}

URL Format POST

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

id

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

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

start_date

Specify this if you want to start the subscription at a future date instead of starting it immediately.
optional, timestamp(UTC) in seconds

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

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 future renewals for which advance invoicing is done. However, if a new term gets started in this operation, the specified terms_to_charge will be inclusive of this new term.
optional, integer, min=1

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

affiliate_token

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=1000

meta_data

Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject

invoice_immediately

If set to 'false', charge will be consolidated with other unbilled charges.
optional, boolean, default=true

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.exemptCustomer is exempted from tax.

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 the USA and Canada. applicable if you use Chargebee's Avalara integration.
optional, enumerated string

Possible values are

aFederal government (United States).bState government (United States).cTribe/Status Indian/Indian Band (both).dForeign diplomat (both).

eCharitable or benevolent org (both).fReligious or educational org (both).gResale (both).hCommercial agricultural production (both).iIndustrial production/manufacturer (both).jDirect pay permit (United States).kDirect mail (United States).lOther (both).nLocal government (United States).pCommercial aquaculture (Canada).qCommercial Fishery (Canada).rNon-resident (Canada).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 only for Avalara.
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[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[allow_direct_debit]

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

customer[consolidated_invoicing]

If set to true, all subscription charges of this customer will be billed in a single invoice. If this is not passed, the site's default setting will be applied.
optional, boolean

customer[vat_number]

VAT number of this customer. Will be validated using the VIES service. To disable this validation, go to 'Settings -> Site Info & Billing Rules' page and select the checkbox 'Disable VAT validation'.
optional, string, max chars=20

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[tmp_token]

The single-use card token returned by vaults like Stripe/Braintree which act as a substitute for your card details. Before calling this API, you should have submitted your card details to the gateway (Stripe/Braintree) and gotten this token in return.
Note: Supported only for Stripe and Braintree gateways. If this value is specified, there is no need to specify other card details (like number, cvv, etc).
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. 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. The recommended way of passing the state/province information. Supported for US and Canada now. Further if this is specified, 'state' attribute should not be specified as it will be set automatically.
optional, string, max chars=50

card[billing_state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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

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.

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

billing_address

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

billing_address[first_name]

First name.
optional, string, max chars=150

billing_address[last_name]

Last name.
optional, string, max chars=150

billing_address[email]

Email.
optional, string, max chars=70

billing_address[company]

Company name.
optional, string, max chars=250

billing_address[phone]

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]

City.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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]

First name.
optional, string, max chars=150

shipping_address[last_name]

Last name.
optional, string, max chars=150

shipping_address[email]

Email.
optional, string, max chars=70

shipping_address[company]

Company name.
optional, string, max chars=250

shipping_address[phone]

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]

City.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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[unit_price][0..n]

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

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/8avVGOkx8U1MX/subscriptions \
     -u {site_api_key}: \
     -d plan_id="basic"

copy

curl  https://{site}.chargebee.com/api/v2/customers/8avVGOkx8U1MX/subscriptions \
     -u {site_api_key}: \
     -d plan_id="basic"

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8asyvQLqrirB4R",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "in_trial",
        "trial_start": 1496826087,
        "trial_end": 1499418087,
        "next_billing_at": 1499418087,
        "created_at": 1496826087,
        "started_at": 1496826087,
        "updated_at": 1496826087,
        "has_scheduled_changes": false,
        "resource_version": 1496826087000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 0
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826087,
        "resource_version": 1496826087000,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    }
}

URL Format POST

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

id

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

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

start_date

Specify this if you want to start the subscription at a future date instead of starting it immediately.
optional, timestamp(UTC) in seconds

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

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

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

payment_source_id

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

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=1000

meta_data

Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject

invoice_immediately

If set to 'false', charge will be consolidated with other unbilled charges.
optional, boolean, default=true

shipping_address

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

shipping_address[first_name]

First name.
optional, string, max chars=150

shipping_address[last_name]

Last name.
optional, string, max chars=150

shipping_address[email]

Email.
optional, string, max chars=70

shipping_address[company]

Company name.
optional, string, max chars=250

shipping_address[phone]

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]

City.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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[unit_price][0..n]

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

Retrieves the list of subscriptions.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode plan_id[is_not]="basic" \
     --data-urlencode status[is]="active" \
     --data-urlencode sort_by[asc]="created_at"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode plan_id[is_not]="basic" \
     --data-urlencode status[is]="active" \
     --data-urlencode sort_by[asc]="created_at"

Sample Response [ JSON ]

{
    "list": [
        {
            "subscription": {
                "id": "8asyvQLqrirB4R",
                "customer_id": "8avVGOkx8U1MX",
                "plan_id": "basic",
                "plan_quantity": 1,
                "plan_unit_price": 900,
                "billing_period": 1,
                "billing_period_unit": "month",
                "plan_free_quantity": 0,
                "status": "in_trial",
                "trial_start": 1496826087,
                "trial_end": 1499418087,
                "next_billing_at": 1499418087,
                "created_at": 1496826087,
                "started_at": 1496826087,
                "updated_at": 1496826087,
                "has_scheduled_changes": false,
                "resource_version": 1496826087000,
                "deleted": false,
                "object": "subscription",
                "currency_code": "USD",
                "due_invoices_count": 0
            },
            "customer": {
                "id": "8avVGOkx8U1MX",
                "first_name": "Benjamin",
                "last_name": "Ross",
                "email": "Benjamin@test.com",
                "auto_collection": "on",
                "net_term_days": 0,
                "allow_direct_debit": false,
                "created_at": 1412101813,
                "taxability": "taxable",
                "updated_at": 1496826087,
                "resource_version": 1496826087000,
                "deleted": false,
                "object": "customer",
                "card_status": "valid",
                "contacts": [
                    {
                        "id": "d334f4g45",
                        "first_name": "aasca",
                        "last_name": "asas",
                        "email": "sss@wss.asc",
                        "label": "ascasc",
                        "enabled": true,
                        "send_account_email": true,
                        "send_billing_email": false,
                        "object": "contact"
                    },
                    {..}
                ],
                "primary_payment_source_id": "pm_8asn8QLqqPW96",
                "payment_method": {
                    "object": "payment_method",
                    "type": "card",
                    "reference_id": "tok_8asn8QLqqPPf5",
                    "gateway": "chargebee",
                    "gateway_account_id": "gw_8asn8QLqqJps2",
                    "status": "valid"
                },
                "promotional_credits": 0,
                "refundable_credits": 0,
                "excess_payments": 0,
                "preferred_currency_code": "USD"
            },
            "card": {
                "status": "valid",
                "gateway": "chargebee",
                "gateway_account_id": "gw_8asn8QLqqJps2",
                "iin": "411111",
                "last4": "1111",
                "card_type": "visa",
                "funding_type": "credit",
                "expiry_month": 1,
                "expiry_year": 2022,
                "object": "card",
                "masked_number": "************1111",
                "customer_id": "8avVGOkx8U1MX",
                "payment_source_id": "pm_8asn8QLqqPW96"
            }
        },
        {..}
    ],
    "next_offset": "[\"1496826087000\",\"140000000097\"]"
}

URL Format GET

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

limit

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

offset

Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000

include_deleted

If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
optional, boolean, default=false

sort_by[<sort-order>]

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

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

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

To filter based on Subscription Id.
Supported operators : is, is_not, starts_with, in, not_in

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

customer_id[<operator>]

To filter based on Subscription Customer Id.
Supported operators : is, is_not, starts_with, in, not_in

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

plan_id[<operator>]

To filter based on Subscription Plan Id.
Supported operators : is, is_not, starts_with, in, not_in

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

status[<operator>]

To filter based on Subscription State. Possible values are : future, in_trial, active, non_renewing, cancelled.
Supported operators : is, is_not, in, not_in

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

cancel_reason[<operator>]

To filter based on Subscription Cancel Reason. 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

remaining_billing_cycles[<operator>]

To filter based on Subscription Remaining Billing Cycles.
Supported operators : is, is_not, lt, lte, gt, gte, between, is_present

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

created_at[<operator>]

To filter based on Subscription Created At.
Supported operators : after, before, on, between

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

activated_at[<operator>]

To filter based on Subscription Activated At.
Supported operators : after, before, on, between

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

next_billing_at[<operator>]

To filter based on Subscription Next Billing At.
Supported operators : after, before, on, between

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

cancelled_at[<operator>]

To filter based on Subscription Cancelled At.
Supported operators : after, before, on, between

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

has_scheduled_changes[<operator>]

To filter based on Subscription Has Scheduled Changes. 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.
Supported operators : after, before, on, between

Example → updated_at[before] = "1243545465"
optional, timestamp(UTC) in seconds 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 the subscription identified by the 'subscription id' specified in the url.

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "non_renewing",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496255412,
        "current_term_end": 1498847412,
        "remaining_billing_cycles": 0,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1414780212,
        "cancelled_at": 1498847412,
        "updated_at": 1496825940,
        "has_scheduled_changes": false,
        "resource_version": 1496825940000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826087,
        "resource_version": 1496826087000,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    }
}

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/8avVGOkx8U1MX

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/8avVGOkx8U1MX/retrieve_with_scheduled_changes \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "no_trial",
        "plan_quantity": 7,
        "plan_unit_price": 1000,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "non_renewing",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496255412,
        "current_term_end": 1498847412,
        "remaining_billing_cycles": 4,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1414780212,
        "cancelled_at": 1498847412,
        "updated_at": 1496825940,
        "has_scheduled_changes": false,
        "resource_version": 1496825940000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826087,
        "resource_version": 1496826087000,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    }
}

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/8avVGOkx8U1MX/remove_scheduled_changes \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "non_renewing",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496255412,
        "current_term_end": 1498847412,
        "remaining_billing_cycles": 0,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1414780212,
        "cancelled_at": 1498847412,
        "updated_at": 1496826088,
        "has_scheduled_changes": false,
        "resource_version": 1496826088000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826087,
        "resource_version": 1496826087000,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    }
}

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

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/8avVGOkx8U1MX/remove_scheduled_cancellation \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496255412,
        "current_term_end": 1498847412,
        "next_billing_at": 1498847412,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1414780212,
        "updated_at": 1496826088,
        "has_scheduled_changes": false,
        "resource_version": 1496826088000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826087,
        "resource_version": 1496826087000,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    }
}

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

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_coupons \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_coupons \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "subscription": {
        "id": "RtSlqIzN6qkgFw",
        "customer_id": "RtSlqIzN6qkgFw",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "in_trial",
        "trial_start": 1496825855,
        "trial_end": 1499417855,
        "next_billing_at": 1499417855,
        "created_at": 1496825855,
        "started_at": 1496825855,
        "updated_at": 1496826088,
        "has_scheduled_changes": false,
        "resource_version": 1496826088000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 0
    },
    "customer": {
        "id": "RtSlqIzN6qkgFw",
        "first_name": "Steve",
        "last_name": "Smith",
        "email": "Steve@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1496825855,
        "taxability": "taxable",
        "updated_at": 1496825856,
        "resource_version": 1496825856000,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "primary_payment_source_id": "pm_8asn8QLqqkYQ68",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqkWe67",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "RtSlqIzN6qkgFw",
        "payment_source_id": "pm_8asn8QLqqkYQ68"
    }
}

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

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. Please refer this tutorial for more details.
If you are using Braintree gateway, you can use Braintree.js with your checkout form.
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

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX \
     -u {site_api_key}: \
     -d plan_id="basic" \
     -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"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX \
     -u {site_api_key}: \
     -d plan_id="basic" \
     -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"

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496255412,
        "current_term_end": 1498847412,
        "next_billing_at": 1498847412,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1414780212,
        "updated_at": 1496826088,
        "has_scheduled_changes": false,
        "resource_version": 1496826088000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826088,
        "resource_version": 1496826088000,
        "deleted": false,
        "object": "customer",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    },
    "credit_notes": []
}

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

start_date

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

trial_end

The time at which the trial should end for this subscription. Can be specified to override the default trial period defined in plan. 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

replace_addon_list

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

terms_to_charge

reactivate_from

The time from which this subscription should be reactivated.
optional, timestamp(UTC) in seconds

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

replace_coupon_list

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

prorate

Add Prorated Credits and Charges, if applicable, while updating the subscription. If this parameter is not passed, the default value set in the Site Settings will be used. Else, it will be assumed as true.
optional, boolean

end_of_term

You can specify when you want to update the subscription.
optional, boolean

force_term_reset

Applicable for 'Active' & 'Non Renewing' states alone. Generally, subscription's term will be reset (i.e current term is ended and a new term starts immediately) when a new plan having different billing frequency is specified in the input. For all the other cases, the subscription's term will remain intact. Now for this later scenario, if you want to force a term reset you can specify this param as 'true'.
Note: Specifying this value as 'false' has no impact on the default behaviour.
optional, boolean, default=false

reactivate

Applicable only for canceled subscriptions. Once this is passed as true, canceled subscription will become active; otherwise subscription changes will be made but the the subscription state will remain canceled. If not passed, subscription will be activated only if there is any change in subscription data.
optional, boolean

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=1000

meta_data

Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject

invoice_immediately

If set to 'false', charge will be consolidated with other unbilled charges.
optional, boolean

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[tmp_token]

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. 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. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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

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]

The single-use card token returned by vaults like Stripe, which act as a substitute for your bank account details. Before calling this API, you should have submitted your bank account details to the gateway ( Stripe ) and gotten this token in return.
required if reference_id not provided, string, max chars=150

billing_address

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

billing_address[first_name]

First name.
optional, string, max chars=150

billing_address[last_name]

Last name.
optional, string, max chars=150

billing_address[email]

Email.
optional, string, max chars=70

billing_address[company]

Company name.
optional, string, max chars=250

billing_address[phone]

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]

City.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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]

First name.
optional, string, max chars=150

shipping_address[last_name]

Last name.
optional, string, max chars=150

shipping_address[email]

Email.
optional, string, max chars=70

shipping_address[company]

Company name.
optional, string, max chars=250

shipping_address[phone]

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]

City.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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]

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]

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.

When changing the current term there won't be any prorations calculated. All future renewals(if applicable) of the subscription will be shifted based on the new date.

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

Notes

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/8avVGOkx8U1MX/change_term_end \
     -u {site_api_key}: \
     -d term_ends_at="1609459199"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/change_term_end \
     -u {site_api_key}: \
     -d term_ends_at="1609459199"

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496255412,
        "current_term_end": 1609459199,
        "next_billing_at": 1609459199,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1414780212,
        "updated_at": 1496826089,
        "has_scheduled_changes": false,
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826089,
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "customer",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    }
}

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

subscription

Resource object representing subscription.
always returned

customer

Resource object representing customer.
always returned

card

Resource object representing card.
optional

unbilled_charges

Resource object representing unbilled_charge.
optional

credit_notes

Resource object representing credit_note.
optional

Cancelling a subscription will move the current state of the subscription to the cancelled state 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. Subscription's state will not change if it is in in_trial state. However, cancellation will be scheduled at the trial end date.

While cancelling a subscription, we try to collect all pending amount against the current and old invoices. No refund for the unused period is processed (let us know if you need have specific refund scenarios).

If the collection of pending charges fails while cancelling, it will still be moved to cancelled status. We will continue to retry collecting the payment based on the configured retry settings until it is manually overridden.

Notes

Advance charges, if any, will be refunded as credits.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/cancel \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/cancel \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "cancelled",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496255412,
        "current_term_end": 1496826089,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1414780212,
        "cancelled_at": 1496826089,
        "updated_at": 1496826089,
        "has_scheduled_changes": false,
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826089,
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "customer",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    }
}

URL Format POST

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

end_of_term

You can specify when you want to cancel the subscription.
optional, boolean, default=false

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

credit_notes

Resource object representing credit_note.
optional

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 canceled 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/8avVGOkx8U1MX/reactivate \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/reactivate \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496826089,
        "current_term_end": 1499418089,
        "next_billing_at": 1499418089,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1496826089,
        "updated_at": 1496826089,
        "has_scheduled_changes": false,
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826089,
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "customer",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    },
    "invoice": {
        "id": "58",
        "customer_id": "8avVGOkx8U1MX",
        "subscription_id": "8avVGOkx8U1MX",
        "recurring": true,
        "status": "paid",
        "price_type": "tax_exclusive",
        "date": 1496826089,
        "due_date": 1496826089,
        "net_term_days": 0,
        "exchange_rate": 1.0,
        "total": 900,
        "amount_paid": 900,
        "amount_adjusted": 0,
        "write_off_amount": 0,
        "credits_applied": 0,
        "amount_due": 0,
        "paid_at": 1496826089,
        "updated_at": 1496826089,
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "invoice",
        "first_invoice": false,
        "has_advance_charges": false,
        "currency_code": "USD",
        "base_currency_code": "USD",
        "tax": 0,
        "line_items": [
            {
                "id": "li_8asyvQLqrjG94a",
                "date_from": 1496826089,
                "date_to": 1499418089,
                "unit_amount": 900,
                "quantity": 1,
                "is_taxed": false,
                "tax_amount": 0,
                "object": "line_item",
                "amount": 900,
                "description": "sample plan",
                "entity_type": "plan",
                "entity_id": "basic",
                "tax_exempt_reason": "tax_not_configured",
                "discount_amount": 0,
                "item_level_discount_amount": 0,
                "subscription_id": "8avVGOkx8U1MX"
            },
            {..}
        ],
        "sub_total": 900,
        "linked_payments": [
            {
                "txn_id": "txn_8asyvQLqrjGW4b",
                "applied_amount": 900,
                "applied_at": 1496826089,
                "txn_status": "success",
                "txn_date": 1496826089,
                "txn_amount": 900
            },
            {..}
        ],
        "applied_credits": [],
        "adjustment_credit_notes": [],
        "issued_credit_notes": [],
        "linked_orders": [],
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    }
}

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

The time from which this subscription should be reactivated.
optional, timestamp(UTC) in seconds

invoice_immediately

If set to 'false', charge will be consolidated with other unbilled charges.
optional, boolean, default=true

terms_to_charge

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/8avVGOkx8U1MX/add_charge_at_term_end \
     -u {site_api_key}: \
     -d amount="1000" \
     -d description="Support charge"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/add_charge_at_term_end \
     -u {site_api_key}: \
     -d amount="1000" \
     -d description="Support charge"

Sample Response [ JSON ]

{"estimate": {
    "created_at": 1496826089,
    "object": "estimate",
    "subscription_estimate": {
        "id": "8avVGOkx8U1MX",
        "status": "active",
        "next_billing_at": 1499418089,
        "object": "subscription_estimate",
        "currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "invoice_estimate": {
        "recurring": true,
        "price_type": "tax_exclusive",
        "sub_total": 1900,
        "total": 1900,
        "credits_applied": 0,
        "amount_paid": 0,
        "amount_due": 1900,
        "object": "invoice_estimate",
        "line_items": [
            {
                "id": "li_8asyvQLqrjNG4h",
                "date_from": 1496826089,
                "date_to": 1496826089,
                "unit_amount": 1000,
                "quantity": 1,
                "is_taxed": false,
                "tax_amount": 0,
                "object": "line_item",
                "amount": 1000,
                "description": "Support charge",
                "entity_type": "adhoc",
                "discount_amount": 0,
                "item_level_discount_amount": 0
            },
            {..}
        ],
        "taxes": [],
        "line_item_taxes": [],
        "currency_code": "USD",
        "line_item_discounts": []
    }
}}

URL Format POST

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

amount

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

description

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

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/8avVGOkx8U1MX/charge_addon_at_term_end \
     -u {site_api_key}: \
     -d addon_id="ssl" \
     -d addon_unit_price="495"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/charge_addon_at_term_end \
     -u {site_api_key}: \
     -d addon_id="ssl" \
     -d addon_unit_price="495"

Sample Response [ JSON ]

{"estimate": {
    "created_at": 1496826090,
    "object": "estimate",
    "subscription_estimate": {
        "id": "8avVGOkx8U1MX",
        "status": "active",
        "next_billing_at": 1499418089,
        "object": "subscription_estimate",
        "currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "invoice_estimate": {
        "recurring": true,
        "price_type": "tax_exclusive",
        "sub_total": 2395,
        "total": 2395,
        "credits_applied": 0,
        "amount_paid": 0,
        "amount_due": 2395,
        "object": "invoice_estimate",
        "line_items": [
            {
                "id": "li_8asyvQLqrjP44j",
                "date_from": 1496826090,
                "date_to": 1496826090,
                "unit_amount": 495,
                "quantity": 1,
                "is_taxed": false,
                "tax_amount": 0,
                "object": "line_item",
                "amount": 495,
                "description": "Support Charge",
                "entity_type": "addon",
                "entity_id": "support_charge",
                "discount_amount": 0,
                "item_level_discount_amount": 0
            },
            {..}
        ],
        "taxes": [],
        "line_item_taxes": [],
        "currency_code": "USD",
        "line_item_discounts": []
    }
}}

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

estimate

Resource object representing estimate.
always returned

Use this API to create an advance invoice for the future renewals of a subscription. This operation will charge your customer if they have a payment method and Auto Collection is turned on. Any changes scheduled for the subscription will be considered while generating an advance invoice. Read More.

Notes

This operation is not supported for non-renewing and canceled 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/8avVGOkx8U1MX/charge_future_renewals \
     -u {site_api_key}: \
     -d terms_to_charge="1"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/charge_future_renewals \
     -u {site_api_key}: \
     -d terms_to_charge="1"

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496826089,
        "current_term_end": 1499418089,
        "next_billing_at": 1502096489,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1496826089,
        "updated_at": 1496826089,
        "has_scheduled_changes": false,
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826090,
        "resource_version": 1496826090000,
        "deleted": false,
        "object": "customer",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    },
    "invoice": {
        "id": "59",
        "customer_id": "8avVGOkx8U1MX",
        "subscription_id": "8avVGOkx8U1MX",
        "recurring": true,
        "status": "paid",
        "price_type": "tax_exclusive",
        "date": 1496826090,
        "due_date": 1496826090,
        "net_term_days": 0,
        "exchange_rate": 1.0,
        "total": 2395,
        "amount_paid": 2395,
        "amount_adjusted": 0,
        "write_off_amount": 0,
        "credits_applied": 0,
        "amount_due": 0,
        "paid_at": 1496826090,
        "updated_at": 1496826090,
        "resource_version": 1496826090000,
        "deleted": false,
        "object": "invoice",
        "first_invoice": false,
        "has_advance_charges": true,
        "currency_code": "USD",
        "base_currency_code": "USD",
        "tax": 0,
        "line_items": [
            {
                "id": "li_8asyvQLqrjNG4h",
                "date_from": 1496826089,
                "date_to": 1496826089,
                "unit_amount": 1000,
                "quantity": 1,
                "is_taxed": false,
                "tax_amount": 0,
                "object": "line_item",
                "amount": 1000,
                "description": "Support charge",
                "entity_type": "adhoc",
                "tax_exempt_reason": "tax_not_configured",
                "discount_amount": 0,
                "item_level_discount_amount": 0,
                "subscription_id": "8avVGOkx8U1MX"
            },
            {..}
        ],
        "sub_total": 2395,
        "linked_payments": [
            {
                "txn_id": "txn_8asyvQLqrjS44m",
                "applied_amount": 2395,
                "applied_at": 1496826090,
                "txn_status": "success",
                "txn_date": 1496826090,
                "txn_amount": 2395
            },
            {..}
        ],
        "applied_credits": [],
        "adjustment_credit_notes": [],
        "issued_credit_notes": [],
        "linked_orders": [],
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    }
}

URL Format POST

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

terms_to_charge

The number of future renewals for which the advance invoicing is done.
optional, integer, default=1, min=1

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.
always returned

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 customer[email]="john@user.com" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[locale]="fr-CA" \
     -d customer[phone]="+1-949-999-9999" \
     -d plan_id="basic" \
     -d status="active" \
     -d current_term_end="1498847412" \
     -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"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/import_subscription \
     -u {site_api_key}: \
     -d customer[email]="john@user.com" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[locale]="fr-CA" \
     -d customer[phone]="+1-949-999-9999" \
     -d plan_id="basic" \
     -d status="active" \
     -d current_term_end="1498847412" \
     -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"

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8asyvQLqrjYZ4r",
        "customer_id": "8asyvQLqrjYZ4r",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "current_term_start": 1496826090,
        "current_term_end": 1498847412,
        "next_billing_at": 1498847412,
        "created_at": 1496826090,
        "started_at": 1496826090,
        "activated_at": 1496826090,
        "updated_at": 1496826090,
        "has_scheduled_changes": false,
        "resource_version": 1496826090000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 0,
        "mrr": 0
    },
    "customer": {
        "id": "8asyvQLqrjYZ4r",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@user.com",
        "phone": "+1-949-999-9999",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1496826090,
        "taxability": "taxable",
        "updated_at": 1496826090,
        "locale": "fr-CA",
        "resource_version": 1496826090000,
        "deleted": false,
        "object": "customer",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "card_status": "no_card",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    }
}

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

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

start_date

Specify this if you want to start the subscription at a future date instead of starting it immediately.
optional, timestamp(UTC) in seconds

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

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

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

trial_start

cancelled_at

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

started_at

Time at which the subscription got started. Will be null for 'future' subscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds

affiliate_token

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=1000

meta_data

Additional data about this resource can be stored here in the JSON Format. Learn more.
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.exemptCustomer is exempted from tax.

customer[locale]

customer[entity_code]

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

Possible values are

aFederal government (United States).bState government (United States).cTribe/Status Indian/Indian Band (both).dForeign diplomat (both).

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[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[allow_direct_debit]

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

customer[vat_number]

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[tmp_token]

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. 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. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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

payment_method[gateway_account_id]

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

payment_method[reference_id]

billing_address

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

billing_address[first_name]

First name.
optional, string, max chars=150

billing_address[last_name]

Last name.
optional, string, max chars=150

billing_address[email]

Email.
optional, string, max chars=70

billing_address[company]

Company name.
optional, string, max chars=250

billing_address[phone]

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]

City.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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]

First name.
optional, string, max chars=150

shipping_address[last_name]

Last name.
optional, string, max chars=150

shipping_address[email]

Email.
optional, string, max chars=70

shipping_address[company]

Company name.
optional, string, max chars=250

shipping_address[phone]

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]

City.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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[unit_price][0..n]

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/8avVGOkx8U1MX/import_subscription \
     -u {site_api_key}: \
     -d plan_id="basic" \
     -d status="active" \
     -d current_term_end="1498847412"

copy

curl  https://{site}.chargebee.com/api/v2/customers/8avVGOkx8U1MX/import_subscription \
     -u {site_api_key}: \
     -d plan_id="basic" \
     -d status="active" \
     -d current_term_end="1498847412"

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8asyvQLqrjeL4v",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "current_term_start": 1496826090,
        "current_term_end": 1498847412,
        "next_billing_at": 1498847412,
        "created_at": 1496826090,
        "started_at": 1496826090,
        "activated_at": 1496826090,
        "updated_at": 1496826091,
        "has_scheduled_changes": false,
        "resource_version": 1496826091000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 0,
        "mrr": 0
    },
    "customer": {
        "id": "8avVGOkx8U1MX",
        "first_name": "Benjamin",
        "last_name": "Ross",
        "email": "Benjamin@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1412101813,
        "taxability": "taxable",
        "updated_at": 1496826091,
        "resource_version": 1496826091000,
        "deleted": false,
        "object": "customer",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "card_status": "valid",
        "contacts": [
            {
                "id": "d334f4g45",
                "first_name": "aasca",
                "last_name": "asas",
                "email": "sss@wss.asc",
                "label": "ascasc",
                "enabled": true,
                "send_account_email": true,
                "send_billing_email": false,
                "object": "contact"
            },
            {..}
        ],
        "primary_payment_source_id": "pm_8asn8QLqqPW96",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqPPf5",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 1,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "8avVGOkx8U1MX",
        "payment_source_id": "pm_8asn8QLqqPW96"
    }
}

URL Format POST

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

id

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

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

start_date

Specify this if you want to start the subscription at a future date instead of starting it immediately.
optional, timestamp(UTC) in seconds

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

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

payment_source_id

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

trial_start

cancelled_at

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

started_at

Time at which the subscription got started. Will be null for 'future' subscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds

invoice_notes

Invoice Notes for this resource. Read More.
optional, string, max chars=1000

meta_data

Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject

shipping_address

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

shipping_address[first_name]

First name.
optional, string, max chars=150

shipping_address[last_name]

Last name.
optional, string, max chars=150

shipping_address[email]

Email.
optional, string, max chars=70

shipping_address[company]

Company name.
optional, string, max chars=250

shipping_address[phone]

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]

City.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
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[unit_price][0..n]

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

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/8avVGOkx8U1MX/override_billing_profile \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/override_billing_profile \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "subscription": {
        "id": "8avVGOkx8U1MX",
        "customer_id": "8avVGOkx8U1MX",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "trial_start": 1412101812,
        "trial_end": 1414780212,
        "current_term_start": 1496826089,
        "current_term_end": 1499418089,
        "next_billing_at": 1502096489,
        "created_at": 1412101812,
        "started_at": 1412101812,
        "activated_at": 1496826089,
        "updated_at": 1496826089,
        "has_scheduled_changes": false,
        "payment_source_id": "pm_XpbBroXQF5m78F6",
        "resource_version": 1496826089000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 3,
        "due_since": 1394532759,
        "total_dues": 6700,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD",
        "shipping_address": {
            "first_name": "Benjamin",
            "last_name": "Ross",
            "line1": "PO Box 9999",
            "city": "Walnut",
            "state_code": "CA",
            "state": "California",
            "country": "US",
            "zip": "91789",
            "validation_status": "not_validated",
            "object": "shipping_address"
        }
    },
    "payment_source": {
        "id": "pm_XpbBroXQF5m78F6",
        "object": "payment_source",
        "customer_id": "8avVGOkx8U1MX",
        "type": "card",
        "reference_id": "tok_8asn8QLqqRK4G",
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "card": {
            "iin": "385200",
            "last4": "3237",
            "funding_type": "not_known",
            "expiry_month": 12,
            "expiry_year": 2022,
            "masked_number": "************3237",
            "object": "card",
            "brand": "diners_club"
        }
    }
}

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/5cDfREwp3I5lJ/delete \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "subscription": {
        "id": "5cDfREwp3I5lJ",
        "customer_id": "5cDfREwp3I5lJ",
        "plan_id": "basic",
        "plan_quantity": 1,
        "plan_unit_price": 900,
        "billing_period": 1,
        "billing_period_unit": "month",
        "plan_free_quantity": 0,
        "status": "active",
        "trial_start": 1496825846,
        "trial_end": 1496660246,
        "current_term_start": 1496660246,
        "current_term_end": 1499252246,
        "next_billing_at": 1499252246,
        "created_at": 1496825846,
        "started_at": 1496825846,
        "activated_at": 1496660246,
        "updated_at": 1496825847,
        "has_scheduled_changes": false,
        "resource_version": 1496825847000,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "due_invoices_count": 1,
        "due_since": 1496660246,
        "total_dues": 900,
        "mrr": 900,
        "exchange_rate": 1.0,
        "base_currency_code": "USD"
    },
    "customer": {
        "id": "5cDfREwp3I5lJ",
        "first_name": "David",
        "last_name": "White",
        "email": "David@test.com",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1496825846,
        "taxability": "taxable",
        "updated_at": 1496660247,
        "resource_version": 1496660247000,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "primary_payment_source_id": "pm_8asn8QLqqiEu5d",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_8asn8QLqqiDY5c",
            "gateway": "chargebee",
            "gateway_account_id": "gw_8asn8QLqqJps2",
            "status": "valid"
        },
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "preferred_currency_code": "USD"
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_8asn8QLqqJps2",
        "iin": "400551",
        "last4": "0004",
        "card_type": "visa",
        "funding_type": "not_known",
        "expiry_month": 12,
        "expiry_year": 2022,
        "object": "card",
        "masked_number": "************0004",
        "customer_id": "5cDfREwp3I5lJ",
        "payment_source_id": "pm_8asn8QLqqiEu5d"
    }
}

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

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

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

Cancel a subscription¶

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