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

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

Sample subscription [ JSON ]

{
    "activated_at": 1517506669,
    "created_at": 1517506669,
    "current_term_end": 1519925869,
    "current_term_start": 1517506669,
    "due_invoices_count": 1,
    "due_since": 1517506669,
    "has_scheduled_changes": false,
    "id": "__test__5SK0bLNFRFuBv6r6j",
    "object": "subscription",
    "plan_id": "no_trial",
    "plan_quantity": 1,
    "started_at": 1517506669,
    "status": "active",
    "total_dues": 895
}

API Index URL GET

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

id

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

plan_id

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

plan_quantity

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

start_date

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

trial_end

optional, timestamp(UTC) in seconds
End of the trial period for the subscription. Presence of this value for 'future' subscription implies the subscription will go into 'in_trial' state when it starts.

remaining_billing_cycles

optional, integer, min=0

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

po_number

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

status

enumerated string
Current state of the subscription

Possible values are

futureThe subscription is scheduled to start at a future date.in_trialThe subscription is in trial.activeThe subscription is active and will be charged for automatically based on the items in it.non_renewingThe subscription will be canceled at the end of the current term.cancelledThe subscription has been canceled and is no longer in service.

trial_start

optional, timestamp(UTC) in seconds
Start of the trial period for the subscription. Presence of this value for future subscription implies the subscription will go into in_trial state when it starts.

current_term_start

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

current_term_end

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

created_at

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

started_at

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

activated_at

optional, timestamp(UTC) in seconds
Time at which the subscription status last changed to active. For example, this value is updated when an in_trial or cancelled subscription activates.

cancelled_at

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

cancel_reason

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

Possible values are

not_paidNot Paid.no_cardNo Card.fraud_review_failedFraud Review Failed.non_compliant_eu_customerNon Compliant EU Customer.

affiliate_token

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

created_from_ip

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

has_scheduled_changes

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

due_invoices_count

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

due_since

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

total_dues

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

invoice_notes

optional, string, max chars=2000
A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

meta_data

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

addons
Show attributes[+]

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

Addon attributes

id

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

quantity

optional, integer, default=1, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.

coupons
Show attributes[+]

optional, list of coupon
List of coupons for this subscription

Coupon attributes

coupon_id

string, max chars=100
Used to uniquely identify the coupon

apply_till

optional, timestamp(UTC) in seconds
The date till when the coupon can be applied. Applicable for limited_period coupons only.

applied_count

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

coupon_code

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

shipping_address
Show attributes[+]

optional, shipping_address
Shipping address for the subscription.

Shipping address attributes

first_name

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

last_name

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

email

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

company

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

phone

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

line1

optional, string, max chars=150
Address line 1

line2

optional, string, max chars=150
Address line 2

line3

optional, string, max chars=150
Address line 3

city

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

state_code

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

state

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

country

optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

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

Brexit

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

zip

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

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

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

Future Subscriptions

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

Trial Period

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

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

Invoice

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

Card details

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

If you are using Stripe gateway, you can use Stripe.js with your checkout form. Take a look at this Stripe tutorial for more details.
If you are using Braintree gateway, you can use Braintree.js with your checkout form. Please refer this tutorial for more details.

You can also use our Hosted Pages based integration.

Billing Address

The Billing Address is significant especially when EU VAT or Customized Tax options are in use, because tax calculations will be based on this address.
In the case of EU VAT, for customers without Billing Address, taxes will not be included.
In the case of Customized Tax option, the billing address will be used to determine tax if shipping address is not available for the customer. If both addresses are not available, tax calculation will not happen.

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

Shipping Address

The Shipping Address is significant for the Customized Tax option, because tax calculations will be based on this address. For customers without Shipping Address, Billing Address details will be used to calculate taxes. If neither of the addresses are available for a customer, taxes will not be calculated for him/her.

Sample Response [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "state_code": "CA",
            "zip": "91789"
        },
        "card_status": "no_card",
        "created_at": 1517506669,
        "email": "john@user.com",
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__5SK0bLNFRFuBv6r6j",
        "last_name": "Doe",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "invoice": {
        "amount": 895,
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "state_code": "CA",
            "zip": "91789"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__5SK0bLNFRFuBv6r6j",
        "end_date": 1517506669,
        "first_invoice": true,
        "id": "__demo_inv__7",
        "line_items": [
            {
                "amount": 895,
                "date_from": 1517506669,
                "date_to": 1519925869,
                "description": "No Trial",
                "entity_id": "no_trial",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [],
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1517506669,
        "status": "payment_due",
        "sub_total": 895,
        "subscription_id": "__test__5SK0bLNFRFuBv6r6j",
        "tax": 0
    },
    "subscription": {
        "activated_at": 1517506669,
        "created_at": 1517506669,
        "current_term_end": 1519925869,
        "current_term_start": 1517506669,
        "due_invoices_count": 1,
        "due_since": 1517506669,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBv6r6j",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "started_at": 1517506669,
        "status": "active",
        "total_dues": 895
    }
}

URL Format POST

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

id

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

plan_id

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

plan_quantity

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

trial_end

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

billing_cycles

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

start_date

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

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

coupon

optional, string, max chars=100

The id of the coupon. For validating the coupon code provided by the user , use the following codes in combination with the param attribute in the error response.

resource_not_found : Returned if the coupon is not present.
resource_limit_exhausted : Returned if the coupon has expired or the maximum redemption for the coupon has already been reached.
invalid_request : Returned if the coupon is not applicable for the particular plan/addon.

po_number

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

affiliate_token

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

created_from_ip

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

invoice_notes

optional, string, max chars=2000
A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

meta_data

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

customer

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

customer[id]

optional, string, max chars=50
The unique ID of the customer for which this hosted_page should be created. When not provided, a new customer is created with the ID set to the value provided for subscription[id]. If subscription[id] is unavailable, then the customer ID is autogenerated.

customer[email]

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

customer[first_name]

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

customer[last_name]

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

customer[company]

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

customer[taxability]

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

Possible values are

taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt

Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.

customer[phone]

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

customer[auto_collection]

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

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]

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

customer[vat_number]

optional, string, max chars=20
The VAT/tax registration number for the customer. For customers with billing_address country as XI (which is United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.

card

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

card[gateway]

optional, enumerated string
Name of the gateway this payment source is stored with.

Possible values are

chargebeeChargebee test gateway.stripeStripe is a payment gateway.

braintreeBraintree is a payment gateway.authorize_netAuthorize.net is a payment gatewaypaypal_proPayPal Pro Account is a payment gateway.pinPin is a payment gatewayewayeWAY Account is a payment gateway.eway_rapideWAY Rapid is a payment gateway.worldpayWorldPay is a payment gatewaybalanced_paymentsBalanced is a payment gatewaybeanstreamBambora(formerly known as Beanstream) is a payment gateway.bluepayBluePay is a payment gateway.elavonElavon Virtual Merchant is a payment solution.first_data_globalFirst Data Global Gateway Virtual Terminal AccounthdfcHDFC Account is a payment gateway.migsMasterCard Internet Gateway Service payment gateway.nmiNMI is a payment gateway.ogoneIngenico ePayments (formerly known as Ogone) is a payment gateway.paymillPAYMILL is a payment gateway.paypal_payflow_proPayPal Payflow Pro is a payment gateway.sage_paySage Pay is a payment gateway.tco2Checkout is a payment gateway.wirecardWireCard Account is a payment service provider.

Show all values[+]

card[tmp_token]

optional, string, max chars=300
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 and gotten this token in return.
Note: Supported only for Stripe, Braintree and Authorize.Net. If this value is specified, there is no need to specify other card details (like number, cvv, etc).

card[first_name]

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

card[last_name]

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

card[number]

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

card[expiry_month]

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

card[expiry_year]

required if card provided, integer
Card expiry year.

card[cvv]

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

card[billing_addr1]

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

card[billing_addr2]

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

card[billing_city]

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

card[billing_state_code]

card[billing_state]

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

card[billing_zip]

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

card[billing_country]

Brexit

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

card[ip_address]

optional, string, max chars=50
The IP address of the customer. Used primarily for referral integration and EU VAT validation.

payment_method

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

payment_method[type]

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

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.

payment_method[gateway]

optional, enumerated string
Name of the gateway the payment method is associated with.

Possible values are

stripeStripe is a payment gateway.

Show all values[+]

payment_method[reference_id]

optional, string, max chars=200
The reference id. In the case of Amazon and Paypal this will be the billing agreement 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.

payment_intent

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

payment_intent[id]

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

payment_intent[gateway_account_id]

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

payment_intent[gw_token]

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

payment_intent[reference_id]

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

billing_address

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

billing_address[first_name]

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

billing_address[last_name]

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

billing_address[email]

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

billing_address[company]

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

billing_address[phone]

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

billing_address[line1]

optional, string, max chars=150
Address line 1

billing_address[line2]

optional, string, max chars=150
Address line 2

billing_address[line3]

optional, string, max chars=150
Address line 3

billing_address[city]

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

billing_address[state_code]

billing_address[state]

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

billing_address[zip]

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

billing_address[country]

optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Brexit

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

shipping_address

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

shipping_address[first_name]

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

shipping_address[last_name]

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

shipping_address[email]

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

shipping_address[company]

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

shipping_address[phone]

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

shipping_address[line1]

optional, string, max chars=150
Address line 1

shipping_address[line2]

optional, string, max chars=150
Address line 2

shipping_address[line3]

optional, string, max chars=150
Address line 3

shipping_address[city]

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

shipping_address[state_code]

shipping_address[state]

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

shipping_address[zip]

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

shipping_address[country]

Brexit

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

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]

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

addons[quantity][0..n]

optional, integer, default=1, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

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

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

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

Notes

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

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517506669,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__5SK0bLNFRFuBvDL6q",
        "last_name": "Henry",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "created_at": 1517506669,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBvED6s",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "shipping_address": {
            "company": "chargebee",
            "first_name": "Mark",
            "last_name": "Henry",
            "object": "shipping_address"
        },
        "start_date": 1548178669,
        "status": "future"
    }
}

URL Format POST

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

id

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

plan_id

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

plan_quantity

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

trial_end

billing_cycles

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

start_date

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

coupon

optional, string, max chars=100

The id of the coupon. For validating the coupon code provided by the user , use the following codes in combination with the param attribute in the error response.

resource_not_found : Returned if the coupon is not present.
resource_limit_exhausted : Returned if the coupon has expired or the maximum redemption for the coupon has already been reached.
invalid_request : Returned if the coupon is not applicable for the particular plan/addon.

po_number

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

invoice_notes

optional, string, max chars=2000
A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

meta_data

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

shipping_address

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

shipping_address[first_name]

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

shipping_address[last_name]

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

shipping_address[email]

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

shipping_address[company]

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

shipping_address[phone]

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

shipping_address[line1]

optional, string, max chars=150
Address line 1

shipping_address[line2]

optional, string, max chars=150
Address line 2

shipping_address[line3]

optional, string, max chars=150
Address line 3

shipping_address[city]

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

shipping_address[state_code]

shipping_address[state]

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

shipping_address[zip]

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

shipping_address[country]

Brexit

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

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

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

payment_intent[gw_token]

payment_intent[reference_id]

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

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]

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

addons[quantity][0..n]

optional, integer, default=1, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

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

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "list": [
        {
            "card": {
                "card_type": "american_express",
                "customer_id": "__test__5SK0bLNFRFuBvJV6x",
                "expiry_month": 12,
                "expiry_year": 2019,
                "gateway": "chargebee",
                "iin": "378282",
                "last4": "0005",
                "masked_number": "***********0005",
                "object": "card",
                "status": "valid"
            },
            "customer": {
                "account_credits": 0,
                "allow_direct_debit": false,
                "auto_collection": "on",
                "card_status": "valid",
                "created_at": 1517506669,
                "excess_payments": 0,
                "id": "__test__5SK0bLNFRFuBvJV6x",
                "object": "customer",
                "payment_method": {
                    "gateway": "chargebee",
                    "object": "payment_method",
                    "reference_id": "tok___test__5SK0bLNFRFuBvJm6y",
                    "status": "valid",
                    "type": "card"
                },
                "refundable_credits": 0,
                "taxability": "taxable"
            },
            "subscription": {
                "activated_at": 1517506669,
                "created_at": 1517506669,
                "current_term_end": 1519925869,
                "current_term_start": 1517506669,
                "due_invoices_count": 0,
                "has_scheduled_changes": false,
                "id": "__test__5SK0bLNFRFuBvJV6x",
                "object": "subscription",
                "plan_id": "no_trial",
                "plan_quantity": 1,
                "started_at": 1517506669,
                "status": "active"
            }
        },
        {..}
    ],
    "next_offset": "[\"1517506669000\",\"182000000066\"]"
}

URL Format GET

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

limit

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

offset

optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.

Retrieves the list of subscriptions for a customer sorted by recent created ones on top

Sample Request

curl  https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBvQU7D/subscriptions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

copy

curl  https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBvQU7D/subscriptions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

Sample Response [ JSON ]

{"list": [
    {
        "customer": {
            "account_credits": 0,
            "allow_direct_debit": false,
            "auto_collection": "off",
            "card_status": "no_card",
            "created_at": 1517506670,
            "excess_payments": 0,
            "id": "__test__5SK0bLNFRFuBvQU7D",
            "object": "customer",
            "refundable_credits": 0,
            "taxability": "taxable"
        },
        "subscription": {
            "activated_at": 1517506670,
            "created_at": 1517506670,
            "current_term_end": 1519925870,
            "current_term_start": 1517506670,
            "due_invoices_count": 1,
            "due_since": 1517506670,
            "has_scheduled_changes": false,
            "id": "__test__5SK0bLNFRFuBvSQ7J",
            "object": "subscription",
            "plan_id": "no_trial",
            "plan_quantity": 1,
            "started_at": 1517506670,
            "status": "active",
            "total_dues": 895
        }
    },
    {..}
]}

URL Format GET

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

limit

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

offset

subscription

always returned
Resource object representing subscription

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.

Retrieves a subscription.

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517506674,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBwQA9L",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "activated_at": 1517506674,
        "created_at": 1517506674,
        "current_term_end": 1519925874,
        "current_term_start": 1517506674,
        "due_invoices_count": 1,
        "due_since": 1517506674,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBwQA9L",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "started_at": 1517506674,
        "status": "active",
        "total_dues": 895
    }
}

URL Format GET

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

Sample admin console URL

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

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

plan_id
plan_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/v1/subscriptions/__test__5SK0bLNFRFuBwSh9S/retrieve_with_scheduled_changes \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "card": {
        "card_type": "visa",
        "customer_id": "__test__5SK0bLNFRFuBwSh9S",
        "expiry_month": 12,
        "expiry_year": 2019,
        "gateway": "chargebee",
        "iin": "411111",
        "last4": "1111",
        "masked_number": "************1111",
        "object": "card",
        "status": "valid"
    },
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517506674,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBwSh9S",
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "object": "payment_method",
            "reference_id": "tok___test__5SK0bLNFRFuBwSw9T",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "activated_at": 1517506674,
        "created_at": 1517506674,
        "current_term_end": 1519925874,
        "current_term_start": 1517506674,
        "due_invoices_count": 0,
        "has_scheduled_changes": true,
        "id": "__test__5SK0bLNFRFuBwSh9S",
        "object": "subscription",
        "plan_id": "sub_free",
        "plan_quantity": 1,
        "started_at": 1517506674,
        "status": "active"
    }
}

URL Format GET

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

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/v1/subscriptions/__test__5SK0bLNFRFuBw1g8Z/remove_scheduled_changes \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "card": {
        "card_type": "visa",
        "customer_id": "__test__5SK0bLNFRFuBw1g8Z",
        "expiry_month": 12,
        "expiry_year": 2019,
        "gateway": "chargebee",
        "iin": "411111",
        "last4": "1111",
        "masked_number": "************1111",
        "object": "card",
        "status": "valid"
    },
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517506672,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBw1g8Z",
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "object": "payment_method",
            "reference_id": "tok___test__5SK0bLNFRFuBw1s8a",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "activated_at": 1517506672,
        "created_at": 1517506672,
        "current_term_end": 1519925872,
        "current_term_start": 1517506672,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBw1g8Z",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "started_at": 1517506672,
        "status": "active"
    }
}

URL Format POST

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

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/v1/subscriptions/__test__5SK0bLNFRFuBvxO8Q/remove_scheduled_cancellation \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517506672,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBvxO8Q",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "activated_at": 1517506672,
        "created_at": 1517506672,
        "current_term_end": 1519925872,
        "current_term_start": 1517506672,
        "due_invoices_count": 1,
        "due_since": 1517506672,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBvxO8Q",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "started_at": 1517506672,
        "status": "active",
        "total_dues": 895
    }
}

URL Format POST

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

billing_cycles

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

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

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

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

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

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

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

If you are using Stripe gateway, you can use Stripe.js with your checkout form. Take a look at this Stripe tutorial for more details.
If you are using Braintree gateway, you can use Braintree.js with your checkout form.
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 billed a total of $7.50 immediately. Calculation will be as follows:

Prorated Charge(New Plan)	$15.00
Prorated Credit(Old Plan) for unused period	($7.50)
Total prorated amount	$7.50

Downgrading will result in credit being created which will be applied when the subscription is charged on start of the next term.

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

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

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

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

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517506674,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBwXZ9h",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "activated_at": 1517506674,
        "created_at": 1517506674,
        "current_term_end": 1519925874,
        "current_term_start": 1517506674,
        "due_invoices_count": 1,
        "due_since": 1517506674,
        "has_scheduled_changes": true,
        "id": "__test__5SK0bLNFRFuBwXZ9h",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "started_at": 1517506674,
        "status": "active",
        "total_dues": 895
    }
}

URL Format POST

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

plan_id

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

plan_quantity

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

replace_addon_list

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

start_date

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

trial_end

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

billing_cycles

optional, integer, min=0
The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan is used.

coupon

optional, string, max chars=100

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

Note:

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

po_number

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

prorate

optional, boolean

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

Caveat

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

An immediate previous change was made

with prorate set to false and
no changes were made to the subscription’s billing term and
a change was made to either the subscription’s plan, its addons, or the prices of the plan or addons.

end_of_term

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

invoice_notes

optional, string, max chars=2000
A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

meta_data

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

card

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

card[gateway]

optional, enumerated string
Name of the gateway this payment source is stored with.

Possible values are

chargebeeChargebee test gateway.stripeStripe is a payment gateway.

Show all values[+]

card[tmp_token]

card[first_name]

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

card[last_name]

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

card[number]

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

card[expiry_month]

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

card[expiry_year]

required if card provided, integer
Card expiry year.

card[cvv]

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

card[billing_addr1]

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

card[billing_addr2]

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

card[billing_city]

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

card[billing_state_code]

card[billing_state]

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

card[billing_zip]

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

card[billing_country]

Brexit

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

card[ip_address]

optional, string, max chars=50
The IP address of the customer. Used primarily for referral integration and EU VAT validation.

payment_method

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

payment_method[type]

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

Possible values are

payment_method[gateway]

optional, enumerated string
Name of the gateway the payment method is associated with.

Possible values are

stripeStripe is a payment gateway.

Show all values[+]

payment_method[reference_id]

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

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

payment_intent[gw_token]

payment_intent[reference_id]

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

billing_address

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

billing_address[first_name]

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

billing_address[last_name]

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

billing_address[email]

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

billing_address[company]

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

billing_address[phone]

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

billing_address[line1]

optional, string, max chars=150
Address line 1

billing_address[line2]

optional, string, max chars=150
Address line 2

billing_address[line3]

optional, string, max chars=150
Address line 3

billing_address[city]

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

billing_address[state_code]

billing_address[state]

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

billing_address[zip]

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

billing_address[country]

optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Brexit

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

shipping_address

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

shipping_address[first_name]

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

shipping_address[last_name]

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

shipping_address[email]

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

shipping_address[company]

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

shipping_address[phone]

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

shipping_address[line1]

optional, string, max chars=150
Address line 1

shipping_address[line2]

optional, string, max chars=150
Address line 2

shipping_address[line3]

optional, string, max chars=150
Address line 3

shipping_address[city]

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

shipping_address[state_code]

shipping_address[state]

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

shipping_address[zip]

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

shipping_address[country]

Brexit

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

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]

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

addons[quantity][0..n]

optional, integer, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

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/v1/subscriptions/__test__5SK0bLNFRFuBuqE6C/change_term_end \
     -u {site_api_key}:\
     -d term_ends_at=1548700200

copy

curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBuqE6C/change_term_end \
     -u {site_api_key}:\
     -d term_ends_at=1548700200

Sample Response [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517506668,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBuqE6C",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "activated_at": 1517506668,
        "created_at": 1517506668,
        "current_term_end": 1548700200,
        "current_term_start": 1517506668,
        "due_invoices_count": 1,
        "due_since": 1517506668,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBuqE6C",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "started_at": 1517506668,
        "status": "active",
        "total_dues": 895
    }
}

URL Format POST

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

term_ends_at

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

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

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

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

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

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

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

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

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

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

Notes

Reactivation of a subscription in non_renewing state has been deprecated. To remove a scheduled cancellation of a non_renewing Subscription, use Remove Scheduled Cancellation API.

However, if you use reactivate API to remove scheduled cancellation for a non_renewing Subscription, then the status will be set to active and the billing cycle will be set to forever. If any value is passed for trial_end or billing cycle, an error will be thrown.

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

Additional Error Scenarios: If there is a need to create an immediate charge and the collection fails, an error will be thrown.

Sample Request

curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBvia7x/reactivate \
     -X POST  \
     -u {site_api_key}:\
     -d billing_cycles=4

copy

curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBvia7x/reactivate \
     -X POST  \
     -u {site_api_key}:\
     -d billing_cycles=4

Sample Response [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517506671,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBvia7x",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "invoice": {
        "amount": 895,
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__5SK0bLNFRFuBvia7x",
        "end_date": 1517506671,
        "first_invoice": false,
        "id": "__demo_inv__13",
        "line_items": [
            {
                "amount": 895,
                "date_from": 1517506671,
                "date_to": 1519925871,
                "description": "No Trial",
                "entity_id": "no_trial",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [],
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1517506671,
        "status": "payment_due",
        "sub_total": 895,
        "subscription_id": "__test__5SK0bLNFRFuBvia7x",
        "tax": 0
    },
    "subscription": {
        "activated_at": 1517506671,
        "created_at": 1517506671,
        "current_term_end": 1519925871,
        "current_term_start": 1517506671,
        "due_invoices_count": 2,
        "due_since": 1517506671,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBvia7x",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "remaining_billing_cycles": 3,
        "started_at": 1517506671,
        "status": "active",
        "total_dues": 1790
    }
}

URL Format POST

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

trial_end

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

billing_cycles

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

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

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

payment_intent[gw_token]

payment_intent[reference_id]

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

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

copy

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

Sample Response [ JSON ]

{"estimate": {
    "amount": 1195,
    "amount_due": 1195,
    "collect_now": false,
    "created_at": 1517506667,
    "credits_applied": 0,
    "line_items": [
        {
            "amount": 300,
            "date_from": 1517506667,
            "date_to": 1517506667,
            "description": "Service Charge",
            "entity_type": "adhoc",
            "is_taxed": false,
            "object": "line_item",
            "quantity": 1,
            "tax": 0,
            "type": "charge",
            "unit_amount": 300
        },
        {..}
    ],
    "object": "estimate",
    "price_type": "tax_exclusive",
    "recurring": true,
    "sub_total": 1195,
    "subscription_id": "__test__5SK0bLNFRFuBuUd5f",
    "subscription_status": "active",
    "term_ends_at": 1519925866
}}

URL Format POST

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

amount

optional, in cents, min=1
The amount to be charged. The unit depends on the type of currency.

description

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

estimate

always returned
Resource object representing estimate

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/v1/subscriptions/__test__5SK0bLNFRFuBuwc6K/charge_addon_at_term_end \
     -u {site_api_key}:\
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=3

copy

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

Sample Response [ JSON ]

{"estimate": {
    "amount": 1195,
    "amount_due": 1195,
    "collect_now": false,
    "created_at": 1517506668,
    "credits_applied": 0,
    "line_items": [
        {
            "amount": 300,
            "date_from": 1517506668,
            "date_to": 1517506668,
            "description": "non_recurring_addon",
            "entity_id": "non_recurring_addon",
            "entity_type": "addon",
            "is_taxed": false,
            "object": "line_item",
            "quantity": 3,
            "tax": 0,
            "type": "charge",
            "unit_amount": 100
        },
        {..}
    ],
    "object": "estimate",
    "price_type": "tax_exclusive",
    "recurring": true,
    "sub_total": 1195,
    "subscription_id": "__test__5SK0bLNFRFuBuwc6K",
    "subscription_status": "active",
    "term_ends_at": 1519925868
}}

URL Format POST

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

addon_id

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

addon_quantity

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

estimate

always returned
Resource object representing estimate

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/v1/subscriptions/__test__5SK0bLNFRFuBvJV6x/delete \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "card": {
        "card_type": "american_express",
        "customer_id": "__test__5SK0bLNFRFuBvJV6x",
        "expiry_month": 12,
        "expiry_year": 2019,
        "gateway": "chargebee",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "status": "valid"
    },
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517506669,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBvJV6x",
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "object": "payment_method",
            "reference_id": "tok___test__5SK0bLNFRFuBvJm6y",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "activated_at": 1517506669,
        "created_at": 1517506669,
        "current_term_end": 1519925869,
        "current_term_start": 1517506669,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBvJV6x",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "started_at": 1517506669,
        "status": "active"
    }
}

URL Format POST

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

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

# cancels the subscription after the term ends.
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBucK5q/cancel \
     -X POST  \
     -u {site_api_key}:\
     -d end_of_term="true"

copy

# cancels the subscription after the term ends.
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBucK5q/cancel \
     -X POST  \
     -u {site_api_key}:\
     -d end_of_term="true"

Sample Response [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517506667,
        "excess_payments": 0,
        "id": "__test__5SK0bLNFRFuBucK5q",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "subscription": {
        "activated_at": 1517506667,
        "cancelled_at": 1519925867,
        "created_at": 1517506667,
        "current_term_end": 1519925867,
        "current_term_start": 1517506667,
        "due_invoices_count": 1,
        "due_since": 1517506667,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBucK5q",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "remaining_billing_cycles": 0,
        "started_at": 1517506667,
        "status": "non_renewing",
        "total_dues": 895
    }
}

URL Format POST

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

end_of_term

optional, boolean, default=false
Set this to true if you want to cancel the subscription at the end of the current subscription billing cycle. The subscription status changes to non_renewing.

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

Sample subscription [ JSON ]

API Index URL GET

Subscription attributes

Create a subscription¶

Future Subscriptions

Trial Period

Invoice

Card details

Billing Address

Shipping 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

Returns

List subscriptions for a customer¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Retrieve a subscription¶

Sample Response [ JSON ]

URL Format GET

Returns

Sample admin console URL

Retrieve with scheduled changes¶

Sample Response [ JSON ]

URL Format GET

Returns

Remove scheduled changes¶

Sample Response [ JSON ]

URL Format POST

Returns

Remove scheduled cancellation¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update a subscription¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Change term end¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Reactivate a subscription¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Add charge at term end¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Charge addon at term end¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns