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

API Index URL GET

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

id

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

currency_code

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

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.

plan_unit_price

optional, in cents, min=0
Amount that will override the Plan's default price. The unit depends on the type of currency.

setup_fee

optional, in cents, min=0
Amount that will override the default setup fee. The unit depends on the type of currency.

billing_period

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

billing_period_unit

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

Possible values are

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

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.

auto_collection

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

Possible values are

onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.

plan_quantity_in_decimal

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

plan_unit_price_in_decimal

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

customer_id

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

plan_amount

optional, in cents, min=0
The total amount for the plan.

plan_free_quantity

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

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.pausedThe subscription is paused. The subscription will not renew while in this state.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.

trial_end_action

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

Possible values are

site_defaultThe action configured for the site at the time when the trial ends, takes effect. This is the default value when trial_end_action is not defined for the plan.plan_defaultThe action configured for the site at the time when the trial ends, takes effect. This is the default value when trial_end_action is defined for the plan.activate_subscriptionThe subscription activates and charges are raised for non-metered items.cancel_subscriptionThe subscription cancels.

current_term_start

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

current_term_end

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

next_billing_at

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

created_at

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

started_at

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

activated_at

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

gift_id

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

contract_term_billing_cycle_on_renewal

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

override_relationship

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

pause_date

optional, timestamp(UTC) in seconds
When a pause has been scheduled, it is the date/time of scheduled pause. When the subscription is in the paused state, it is the date/time when the subscription was paused.

resume_date

optional, timestamp(UTC) in seconds
For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

cancelled_at

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

cancel_reason

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

Possible values are

not_paidNot 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

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.

resource_version

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

updated_at

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

has_scheduled_advance_invoices

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

has_scheduled_changes

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

payment_source_id

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

plan_free_quantity_in_decimal

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

plan_amount_in_decimal

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

cancel_schedule_created_at

optional, timestamp(UTC) in seconds
This is the date/time at which the most recent cancellation schedule for the subscription was created in Chargebee. Applicable only for cancelled subscriptions or subscriptions that are scheduled for cancellation.

offline_payment_method

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

Possible values are

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

channel

optional, enumerated string
The subscription channel this object originated from and is maintained in.

Possible values are

webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.play_storeThe object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.

In-App Subscriptions is currently in early access. Contact eap@chargebee.com for more information.

due_invoices_count

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

due_since

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

total_dues

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

mrr

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

exchange_rate

optional, bigdecimal, min=1E-9, max=999999999.999999999
Exchange rate used for base currency conversion.This value is updated to the rate configured on your site each time any change is made to the subscription.

base_currency_code

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

invoice_notes

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

meta_data

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

deleted

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

changes_scheduled_at

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

cancel_reason_code

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

free_period

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

free_period_unit

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

Possible values are

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

create_pending_invoices

optional, boolean

Indicates whether the invoices for this subscription are generated with a pending status. This attribute is set to true automatically when the subscription has item prices that belong to metered items.

You can also set this to true explicitly using the create/update subscription operations. This is useful in the following scenarios:

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

Applicable only when Metered Billing is enabled for the site

auto_close_invoices

optional, boolean
Set to false to override for this subscription, the site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute has a higher precedence than the same attribute at the customer level.

business_entity_id

optional, string, max chars=50
The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.

Note

Multiple Business Entities is a feature available only on Product Catalog 2.0.

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.

unit_price

optional, in cents, min=0

The price or per-unit-price of the addon. The value depends on the type of currency.

Note:

For recurring addons, this is the final price or per-unit price for each billing period of the subscription, regardless of the addon period. For example, consider the following details:

The unit_price provided is $10
The addon billing period is 1 month.
The plan billing period is 3 months.
The addon is only billed for $10 on each subscription renewal.

amount

optional, in cents, min=0
The total amount for the addon. The format of the value depends upon the currency.

trial_end

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

remaining_billing_cycles

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

quantity_in_decimal

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

unit_price_in_decimal

optional, string, max chars=39

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

Note:

For recurring addons, this is the final price or per-unit price for each billing period of the subscription, regardless of the addon period. For example, consider the following details:

The unit_price_in_decimal provided is $10.75
The addon billing period is 1 month.
The plan billing period is 3 months.
The addon is only billed for $10.75 on each subscription renewal.

amount_in_decimal

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

proration_type

optional, enumerated string
Type of proration for addons.

Possible values are

full_termThe full price for the addon is charged; no proration is applied.partial_termThe addon charges are prorated for the remaining period in the current term.noneThere is no proration done in this instance; therefore, the addon is not charged at all

event_based_addons
Show attributes[+]

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

Event based addon attributes

id

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

quantity

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

unit_price

in cents, min=0
Amount that will override the Addon's default price. The unit depends on the type of currency.

on_event

enumerated string
Event on which this addon will be charged.

Possible values are

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

charge_once

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

quantity_in_decimal

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

unit_price_in_decimal

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

charged_event_based_addons
Show attributes[+]

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

Charged event based addon attributes

id

string, max chars=100
Addon id.

last_charged_at

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

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.

validation_status

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

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.

index

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

referral_info
Show attributes[+]

optional, referral_info
Referral details if exists for the subscription

Referral info attributes

referral_code

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

coupon_code

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

referrer_id

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

external_reference_id

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

reward_status

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

Possible values are

pendingPendingpaidPaidinvalidInvalid

referral_system

optional, enumerated string
Source referral system for the referral subscription

Possible values are

referral_candyReferral Candyreferral_saasquatchReferral SaasquatchfriendbuyFriendbuy

account_id

string, max chars=50
Referral account id

campaign_id

string, max chars=50
Referral campaign id

external_campaign_id

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

friend_offer_type

optional, enumerated string
Friend offer type for the referral camapign

Possible values are

noneNonecouponCouponcoupon_codeCoupon Code

referrer_reward_type

optional, enumerated string
Referrer reward type for the referral campaign

Possible values are

noneNonereferral_direct_rewardReferral Direct Rewardcustom_promotional_creditCustom Promotional Creditcustom_revenue_percent_basedCustom Revenue Percent Based

notify_referral_system

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

Possible values are

noneNonefirst_paid_conversionFirst Paid Conversionall_invoicesAll Invoices

destination_url

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

post_purchase_widget_enabled

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

contract_term
Show attributes[+]

optional, contract_term
Contract terms for this subscription

Contract term attributes

id

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

status

enumerated string
Current status of contract

Possible values are

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

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

terminatedThe contract term was terminated ahead of completion.

contract_start

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

contract_end

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

billing_cycle

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

action_at_term_end

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

Possible values are

renew

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to renew.

evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following:

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to cancel.

total_contract_value

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

total_contract_value_before_tax

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

cancellation_cutoff_period

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

created_at

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

subscription_id

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

remaining_billing_cycles

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

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

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 explicitly using trial_end), the subscription will go into 'trial' state when it starts. Otherwise it will directly become 'active' when it starts.

Trial Period

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

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

Invoice

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

Card details

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

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

You can also use our Hosted Pages based integration.

Legacy behavior:

For sites created before March 1st, 2014: On making this request, the billing_address and vat_number of the customer are deleted and replaced by the values passed with this request. Ensure that you pass the billing address parameters and the vat_number parameters each time you make this request, to avoid losing the same information at the customer-level.
For sites created on or after March 1st, 2014: This request does not alter the billing_address and vat_number of the customer.

Sample Response [ JSON ]

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

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

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

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

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

URL Format POST

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

id

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.

plan_quantity_in_decimal

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

plan_unit_price

optional, in cents, min=0
Plan Unit Amount for create subscription.

plan_unit_price_in_decimal

optional, string, max chars=39
Plan Unit Amount in Decimal for create subscription.

setup_fee

optional, in cents, min=0
Amount that will override the default setup fee. The unit depends on the type of currency.

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.

mandatory_addons_to_remove[0..n]

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

start_date

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

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

auto_collection

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

Possible values are

terms_to_charge

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

billing_alignment_mode

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

Possible values are

immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.

offline_payment_method

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

Possible values are

no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transferach_creditACH Creditsepa_creditSEPA CreditboletoBoleto

po_number

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

coupon_ids[0..n]

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

token_id

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

affiliate_token

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

invoice_notes

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

invoice_date

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

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

meta_data

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

invoice_immediately

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

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

free_period

optional, integer, min=1
The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit.

free_period_unit

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

Possible values are

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

contract_term_billing_cycle_on_renewal

trial_end_action

Possible values are

client_profile_id

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

payment_initiator

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

Possible values are

customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant

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

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

customer[entity_code]

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

Possible values are

aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat

eCharitable or benevolent organizationfReligious organizationgResalehCommercial agricultural productioniIndustrial production/manufacturerjDirect pay permitkDirect maillOther or custommEducational organizationnLocal governmentpCommercial aquacultureqCommercial FisheryrNon-residentmed1US Medical Device Excise Tax with exempt sales taxmed2US Medical Device Excise Tax with taxable sales tax

Show all values[+]

customer[exempt_number]

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

customer[net_term_days]

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

customer[taxjar_exemption_category]

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

Possible values are

wholesaleWhole-salegovernmentGovernmentotherOther

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

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

Possible values are

no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transferach_creditACH Creditsepa_creditSEPA CreditboletoBoleto

customer[allow_direct_debit]

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

customer[consolidated_invoicing]

optional, boolean

Indicates whether invoices raised on the same day for the customer are consolidated. When provided, this overrides the default configuration at the site-level. This parameter can be provided only when Consolidated Invoicing is enabled.

Note:

Any invoices raised when a subscription activates from in_trial or future status, are not consolidated by default. Contact Support to enable consolidation for such invoices.

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.

customer[vat_number_prefix]

optional, string, max chars=10
An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address country as XI (which is United Kingdom - Northern Ireland).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address country as XI. That’s the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.

customer[entity_identifier_scheme]

optional, string, max chars=50
The Peppol BIS scheme associated with the vat_number of the customer. This helps identify the specific type of customer entity. For example, DE:VAT is used for a German business entity while DE:LWID45 is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country. See list of possible values.

Tip:

If there are additional entity identifiers for the customer not associated with the vat_number, they can be provided as the entity_identifiers[] array.

customer[entity_identifier_standard]

optional, string, default=iso6523-actorid-upis, max chars=50
The standard used for specifying the entity_identifier_scheme. Currently only iso6523-actorid-upis is supported and is used by default when not provided.

Tip:

If there are additional entity identifiers for the customer not associated with the vat_number, they can be provided as the entity_identifiers[] array.

customer[is_einvoice_enabled]

optional, boolean
Determines whether the customer is e-invoiced. When set to true or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country). When set to false, the customer is not e-invoiced even if e-invoicing is enabled for their country.

Tip:

It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.

customer[einvoicing_method]

optional, enumerated string
Determines whether to send einvoice manually or automatic.

Possible values are

automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.

customer[registered_for_gst]

optional, boolean
Confirms that a customer is registered under GST. If set to true then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.

customer[business_customer_without_vat_number]

optional, boolean
Confirms that a customer is a valid business without an EU/UK VAT number.

customer[exemption_details]

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

customer[customer_type]

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

Possible values are

residentialWhen the purchase is made by a customer for home usebusinessWhen the purchase is made at a place of businesssenior_citizenWhen the purchase is made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualifies for senior citizen tax breaksindustrialWhen the purchase is made by an industrial business

card

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

card[gateway_account_id]

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

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

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

bank_account

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

bank_account[gateway_account_id]

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

bank_account[iban]

optional, string, min chars=10, max chars=50
Account holder’s International Bank Account Number. For the GoCardless platform, this can be the local bank details

bank_account[first_name]

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

bank_account[last_name]

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

bank_account[company]

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

bank_account[email]

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

bank_account[phone]

optional, string, max chars=50
Phone number of the account holder that is linked to the bank account.

bank_account[bank_name]

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

bank_account[account_number]

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

bank_account[routing_number]

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

bank_account[bank_code]

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

bank_account[account_type]

optional, enumerated string
Represents the account type used to create a payment source. Available for Authorize.net ACH and Razorpay NetBanking users only. If not passed, account type is taken as null.

Possible values are

checkingChecking AccountsavingsSavings Accountbusiness_checkingBusiness Checking AccountcurrentCurrent Account

bank_account[account_holder_type]

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

Possible values are

individualIndividual Account.companyCompany Account.

bank_account[echeck_type]

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

Possible values are

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

bank_account[issuing_country]

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

bank_account[swedish_identity_number]

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

bank_account[billing_address]

optional, jsonobject
The billing address associated with the bank account. The value is a JSON object with the following keys and their values:

first_name:(string, max chars=150) The first name of the contact.
last_name:(string, max chars=150) The last name of the contact.
company_name:(string, max chars=250) The company name for the address.
line1:(string, max chars=180) The first line of the address.
line2:(string, max chars=180) The second line of the address.
country:(string) The name of the country for the address.
country_code:(string, max chars=50) The two-letter, ISO 3166 alpha-2 country code for the address.
state:(string, max chars=50) The name of the state or province for the address. When not provided, this is set automatically for US, Canada, and India.
state_code:(string, max chars=50) The ISO 3166-2 state/province code without the country prefix. This is 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).
city:(string, max chars=50) The city name for the address.
postal_code:(string, max chars=20) The postal or ZIP code for the address.
phone:(string, max chars=50) The contact phone number for the address.
email:(string, max chars=70) The contact email address for the address.

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.

genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.apple_payPayments made via Apple Pay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.venmoPayments made via Venmo pay_toPayments made via PayTo faster_paymentsPayments made via Faster Payments sepa_instant_transferPayments made via Sepa Instant Transfer

Show all values[+]

payment_method[gateway_account_id]

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

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

payment_method[tmp_token]

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

payment_method[issuing_country]

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

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

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

payment_method[additional_information]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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

optional, enumerated string
The list of payment method types (For example, card, ideal, sofort, bancontact, etc.) this Payment Intent is allowed to use. If payment method type is empty, Card is taken as the default type for all gateways except Razorpay.

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

google_paygoogle_paydotpaydotpaygiropaygiropayapple_payapple_payupiupinetbanking_emandatesnetbanking_emandatespaypal_express_checkoutpaypal_express_checkoutdirect_debitdirect_debitboletoboletovenmoamazon_paymentsamazon_paymentspay_tofaster_paymentssepa_instant_transfer

Show all values[+]

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.

payment_intent[additional_information]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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.

billing_address[validation_status]

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

Possible values are

shipping_address

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

shipping_address[first_name]

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

shipping_address[validation_status]

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

Possible values are

contract_term

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

contract_term[action_at_term_end]

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

Possible values are

renew

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to renew.

evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.

contract_term[cancellation_cutoff_period]

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

entity_identifiers

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

entity_identifiers[id][0..n]

optional, string, max chars=40
The unique id for the entity_identifier in Chargebee. When not provided, it is autogenerated.

entity_identifiers[scheme][0..n]

Tip:

If there is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

entity_identifiers[value][0..n]

optional, string, max chars=50
The value of the entity_identifier. This identifies the customer entity on the Peppol network. For example: 10101010-STO-10.

Tip:

entity_identifiers[standard][0..n]

optional, string, default=iso6523-actorid-upis, max chars=50
The standard used for specifying the entity_identifier scheme. Currently, only iso6523-actorid-upis is supported and is used by default when not provided.

Tip:

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.

addons[quantity_in_decimal][0..n]

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

addons[unit_price][0..n]

optional, in cents, min=0
Addon Unit Amount for create subscription

addons[unit_price_in_decimal][0..n]

optional, string, max chars=39
Addon Unit Amount in Decimal for create subscription

addons[billing_cycles][0..n]

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

addons[trial_end][0..n]

event_based_addons

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

event_based_addons[id][0..n]

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

event_based_addons[quantity][0..n]

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

event_based_addons[unit_price][0..n]

optional, in cents, min=0
Amount that will override the Addon's default price. The unit depends on the type of currency.

event_based_addons[quantity_in_decimal][0..n]

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

event_based_addons[unit_price_in_decimal][0..n]

event_based_addons[service_period_in_days][0..n]

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

event_based_addons[on_event][0..n]

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

Possible values are

event_based_addons[charge_once][0..n]

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

event_based_addons[charge_on][0..n]

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

Possible values are

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charge

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

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

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

Notes

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

Sample Request

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

copy

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

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

Sample Response [ JSON ]

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

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

URL Format POST

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

id

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.

plan_quantity_in_decimal

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

plan_unit_price

optional, in cents, min=0
Amount that will override the Plan's default price. The unit depends on the type of currency.

plan_unit_price_in_decimal

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

setup_fee

optional, in cents, min=0
Amount that will override the default setup fee. The unit depends on the type of currency.

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.

mandatory_addons_to_remove[0..n]

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

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.

auto_collection

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

Possible values are

terms_to_charge

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

billing_alignment_mode

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

Possible values are

offline_payment_method

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

Possible values are

no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transferach_creditACH Creditsepa_creditSEPA CreditboletoBoleto

po_number

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

coupon_ids[0..n]

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

payment_source_id

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

override_relationship

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

invoice_notes

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

invoice_date

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

meta_data

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

invoice_immediately

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

replace_primary_payment_source

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

free_period

optional, integer, min=1
The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit.

free_period_unit

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

Possible values are

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

contract_term_billing_cycle_on_renewal

trial_end_action

Possible values are

payment_initiator

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

Possible values are

customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant

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.

shipping_address[validation_status]

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

Possible values are

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

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

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.

payment_intent[additional_information]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

contract_term

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

contract_term[action_at_term_end]

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

Possible values are

renew

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to renew.

evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.

contract_term[cancellation_cutoff_period]

addons

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

addons[id][0..n]

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.

addons[quantity_in_decimal][0..n]

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

addons[unit_price][0..n]

optional, in cents, min=0
Sub Item Plan Unit Amount for create subscription

addons[unit_price_in_decimal][0..n]

optional, string, max chars=39
Sub Item Plan Unit Amount in Decimal for create subscription

addons[billing_cycles][0..n]

addons[trial_end][0..n]

event_based_addons

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

event_based_addons[id][0..n]

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

event_based_addons[quantity][0..n]

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

event_based_addons[unit_price][0..n]

optional, in cents, min=0
Amount that will override the Addon's default price. The unit depends on the type of currency.

event_based_addons[quantity_in_decimal][0..n]

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

event_based_addons[unit_price_in_decimal][0..n]

event_based_addons[service_period_in_days][0..n]

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

event_based_addons[on_event][0..n]

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

Possible values are

event_based_addons[charge_once][0..n]

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

event_based_addons[charge_on][0..n]

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

Possible values are

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charge

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format GET

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

limit

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

offset

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

include_deleted

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

sort_by[<sort-order>]

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

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

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

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

Example → id[is] = "8gsnbYfsMLds"

customer_id[<operator>]

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

Example → customer_id[is_not] = "8gsnbYfsMLds"

plan_id[<operator>]

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

Example → plan_id[is_not] = "basic"

status[<operator>]

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

Example → status[is] = "active"

cancel_reason[<operator>]

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

Example → cancel_reason[is] = "not_paid"

cancel_reason_code[<operator>]

optional, string filter
Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation. Must be passed if set as mandatory in the app. The codes are case-sensitive.
Supported operators : is, is_not, starts_with, in, not_in

Example → cancel_reason_code[is] = "Not Paid"

remaining_billing_cycles[<operator>]

optional, integer filter

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

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

Example → remaining_billing_cycles[is] = "3"

created_at[<operator>]

optional, timestamp(UTC) in seconds filter
The time at which the subscription was created.
Supported operators : after, before, on, between

Example → created_at[after] = "1435054328"

activated_at[<operator>]

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

Example → activated_at[on] = "1435054328"

next_billing_at[<operator>]

optional, timestamp(UTC) in seconds filter
The date/time at which the next billing for the subscription happens. This is usually right after current_term_end unless multiple subscription terms were invoiced in advance using the terms_to_charge parameter.
Supported operators : after, before, on, between

Example → next_billing_at[after] = "1435054328"

cancelled_at[<operator>]

optional, timestamp(UTC) in seconds filter
Time at which subscription was cancelled or is set to be cancelled.
Supported operators : after, before, on, between

Example → cancelled_at[after] = "1435054328"

has_scheduled_changes[<operator>]

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

Example → has_scheduled_changes[is] = "true"

updated_at[<operator>]

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

Example → updated_at[on] = "1243545465"

offline_payment_method[<operator>]

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

Example → offline_payment_method[is] = "cash"

auto_close_invoices[<operator>]

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

Example → auto_close_invoices[is] = "true"

override_relationship[<operator>]

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

Example → override_relationship[is] = "false"

business_entity_id[<operator>]

optional, string filter
The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.

Note

Multiple Business Entities is a feature available only on Product Catalog 2.0.

Supported operators : is, is_not, starts_with

Example → business_entity_id[is] = "business_entity_id"

channel[<operator>]

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

Example → channel[is_not] = "APP STORE"

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

next_offset

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

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

Sample Request

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

copy

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

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

Sample Response [ JSON ]

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

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

URL Format GET

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

limit

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

offset

contract_term

always returned
Resource object representing contract_term

next_offset

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

Retrieves a subscription.

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format GET

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

subscription

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
plan_unit_price
setup_fee
billing_period
billing_period_unit
plan_free_quantity
remaining_billing_cycles
addons
coupons

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format GET

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

subscription

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

credit_notes

optional
Resource object representing credit_note

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

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

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

billing_cycles

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

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

Sample Request

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

copy

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

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

Sample Response [ JSON ]

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

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

URL Format POST

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

coupon_ids[0..n]

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

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

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

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

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

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

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

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

Notes

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

Credit Note
Prorated credits for Old Plan	$7.50

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

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

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

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

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

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

Sample Request

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

copy

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

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

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

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

Sample Response [ JSON ]

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

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

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

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

URL Format POST

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

plan_id

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.

plan_unit_price

optional, in cents, min=0
Amount that will override the plan's default price. The unit depends on the type of currency. If changes_scheduled_at is in the past and a plan_unit_price is not passed, then the plan’s current unit price is considered even if the plan did not exist on the date as of when the change is scheduled.

setup_fee

optional, in cents, min=0
Amount that will override the default setup fee. The unit depends on the type of currency.

replace_addon_list

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

mandatory_addons_to_remove[0..n]

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

plan_quantity_in_decimal

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

plan_unit_price_in_decimal

optional, string, max chars=39
When price overriding is enabled for the site, the price or per-unit price of the item can be set here. The value set for the item price is used by default. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled. If changes_scheduled_at is in the past and a unit_price_in_decimal is not passed, then the item price’s current unit price is considered even if the item price did not exist on the date as of when the change is scheduled.

invoice_date

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

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

start_date

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

trial_end

optional, timestamp(UTC) in seconds
The time at which the trial has ended or will end for the subscription. 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.

terms_to_charge

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

reactivate_from

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

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

billing_alignment_mode

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

Possible values are

auto_collection

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

Possible values are

offline_payment_method

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

Possible values are

no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transferach_creditACH Creditsepa_creditSEPA CreditboletoBoleto

po_number

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

coupon_ids[0..n]

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

replace_coupon_list

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

prorate

optional, boolean

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

Caveat

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

An immediate previous change was made

with prorate set to false and
no changes were made to the subscription’s billing term and
a change was made to either the subscription’s 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.

force_term_reset

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

reactivate

optional, boolean
When the status of the subscription is cancelled, this parameter determines whether the subscription is reactivated upon making this API request. Unless passed explicitly as false, this parameter is implied as true when you provide plan_id or addons[id]

token_id

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

invoice_notes

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

meta_data

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

invoice_immediately

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

override_relationship

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

changes_scheduled_at

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

Backdating must be enabled for subscription change operations.
Only the following changes can be backdated:

Changes in the recurring items or their prices.
Addition of non-recurring items.

Subscription status is active, cancelled, or non_renewing.
The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is typically the day of the month by which the accounting for the previous month must be closed.
The date is on or after current_term_start.
The date is on or after the last date/time any of the following changes were made:

Changes in the recurring items or their prices.
Addition of non-recurring items.

The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, changes_scheduled_at cannot be earlier than 14th February.

change_option

optional, enumerated string
When the quote is converted, this attribute determines the date/time as of when the subscription change is to be carried out.

Possible values are

immediatelyThe change is carried out immediately.end_of_termThe change is carried out at the end of the current billing cycle of the subscription.specific_dateThe change is carried out as of the date specified under changes_scheduled_at.

contract_term_billing_cycle_on_renewal

free_period

optional, integer, min=1
The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit.

free_period_unit

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

Possible values are

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

trial_end_action

Possible values are

card

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

card[gateway_account_id]

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

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

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud 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

Show all values[+]

payment_method[gateway_account_id]

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

payment_method[reference_id]

payment_method[tmp_token]

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

payment_method[issuing_country]

payment_method[additional_information]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

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.

payment_intent[additional_information]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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.

billing_address[validation_status]

optional, enumerated string
The address verification status.

Possible values are

shipping_address

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

shipping_address[first_name]

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

shipping_address[validation_status]

optional, enumerated string
The address verification status.

Possible values are

customer

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

customer[vat_number]

customer[vat_number_prefix]

customer[entity_identifier_scheme]

Tip:

If there are additional entity identifiers for the customer not associated with the vat_number, they can be provided as the entity_identifiers[] array.

customer[is_einvoice_enabled]

Tip:

It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.

customer[einvoicing_method]

optional, enumerated string
Determines whether to send einvoice manually or automatic.

Possible values are

customer[entity_identifier_standard]

optional, string, max chars=50
The standard used for specifying the entity_identifier_scheme. Currently only iso6523-actorid-upis is supported and is used by default when not provided.

Tip:

If there are additional entity identifiers for the customer not associated with the vat_number, they can be provided as the entity_identifiers[] array.

customer[business_customer_without_vat_number]

optional, boolean
Confirms that a customer is a valid business without an EU/UK VAT number.

customer[registered_for_gst]

contract_term

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

contract_term[action_at_term_end]

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

Possible values are

renew

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to renew.

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to cancel.

contract_term[cancellation_cutoff_period]

addons

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

addons[id][0..n]

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.

addons[unit_price][0..n]

optional, in cents, min=0
Amount that will override the Addon's default price. The unit depends on the type of currency. 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 x 3). If changes_scheduled_at is in the past and addons[unit_price][i] is not passed, then the addon’s current unit price is considered even if the addon did not exist on the date as of when the change is scheduled.

addons[billing_cycles][0..n]

addons[quantity_in_decimal][0..n]

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

addons[unit_price_in_decimal][0..n]

optional, string, max chars=39
When price overriding is enabled for the site, the price or per-unit price of the addon can be set here. The value set for the addon is used by default. However, the price provided here is considered as the price of the addon for an entire billing cycle of the subscription regardless of the value of the addon period. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled. If changes_scheduled_at is in the past and addons[unit_price_in_decimal][i] is not passed, then the addon’s current unit price is considered even if the addon did not exist on the date as of when the change is scheduled.

addons[trial_end][0..n]

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

event_based_addons

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

event_based_addons[id][0..n]

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

event_based_addons[quantity][0..n]

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

event_based_addons[unit_price][0..n]

optional, in cents, min=0
Amount that will override the Addon's default price. The unit depends on the type of currency.

event_based_addons[service_period_in_days][0..n]

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

event_based_addons[charge_on][0..n]

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

Possible values are

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

event_based_addons[on_event][0..n]

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

Possible values are

event_based_addons[charge_once][0..n]

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

event_based_addons[quantity_in_decimal][0..n]

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

event_based_addons[unit_price_in_decimal][0..n]

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charge

credit_notes

optional
Resource object representing credit_note

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

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

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

Notes

When changing the term_end for active / non_renewing subscriptions, by default no additional charges (when term gets extended) will be added or credits (when term gets reduced) will be issued. However you can specify prorate param as true for adding prorated charges / issuing prorated credits. Further for the charges that got added, you can specify invoice_immediately as false to add them to unbilled charges and invoice them later.
Advance charges, if any will be credited back during this operation.
Confirm the UTC (Coordinated Universal Time) time zone selected in your Chargebee site matches with your country region.

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

term_ends_at

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

prorate

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

invoice_immediately

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charge

credit_notes

optional
Resource object representing credit_note

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

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

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

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

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

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

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

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

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

Notes

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

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

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

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

trial_end

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

billing_cycles

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

reactivate_from

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

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

invoice_immediately

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

billing_alignment_mode

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

Possible values are

terms_to_charge

invoice_date

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

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

contract_term_billing_cycle_on_renewal

payment_initiator

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

Possible values are

customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant

contract_term

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

contract_term[action_at_term_end]

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

Possible values are

renew

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to renew.

evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.

contract_term[cancellation_cutoff_period]

payment_intent

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

payment_intent[id]

payment_intent[gateway_account_id]

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

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

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.

payment_intent[additional_information]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charge

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

To collect a charge immediately, use this API.

Notes

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

amount

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

description

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

amount_in_decimal

optional, string, max chars=39
The decimal representation of the amount for the one-time charge. Provide the value in major units of the currency. Can be provided only when multi-decimal pricing is enabled.

avalara_sale_type

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

Possible values are

wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax

avalara_transaction_type

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

avalara_service_type

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

date_from

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

date_to

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

estimate

always returned
Resource object representing estimate

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

To collect the charges for the non-recurring addon immediately, use this API.

Notes

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

addon_id

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.

addon_unit_price

optional, in cents, default=addon amount, min=0
Amount that will override the Addon's default price. The unit depends on the type of currency.

addon_quantity_in_decimal

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

addon_unit_price_in_decimal

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

date_from

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

date_to

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

estimate

always returned
Resource object representing estimate

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

Notes

This operation is supported only on select plans. To know more, take a look at our plans and pricing page.
This operation is not supported for non_renewing and cancelled subscriptions.
This operation is not supported if an advance invoice is already present. You could void/delete that invoice and try creating another advance invoice.

Sample Request

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

copy

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

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

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

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

Sample Response [ JSON ]

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

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

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

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

URL Format POST

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

terms_to_charge

optional, integer, default=1, min=1

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

invoice_immediately

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

schedule_type

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

Possible values are

immediateCharge immediately for the number of billing cycles specified by terms_to_charge.specific_datesCharge on specific dates. For each date, specify the number of billing cycles to charge for. Up to 5 dates can be configured.fixed_intervalsCharge at fixed intervals of time. Specify the number of billing cycles that constitute an interval and the number of days before each interval that the invoice should be generated. Also specify when the schedule should end.

fixed_interval_schedule

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

fixed_interval_schedule[number_of_occurrences]

optional, integer, min=1
The number of advance invoices to generate. The schedule is created such that the total number of billing cycles in the schedule does not exceed the remaining_billing_cycles of the subscription. This parameter is applicable only when fixed_interval_schedule[end_schedule_on] = after_number_of_intervals

fixed_interval_schedule[days_before_renewal]

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

fixed_interval_schedule[end_schedule_on]

optional, enumerated string
Specifies when the schedule should end.

Possible values are

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

fixed_interval_schedule[end_date]

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

specific_dates_schedule

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

specific_dates_schedule[terms_to_charge][0..n]

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

specific_dates_schedule[date][0..n]

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

subscription

always returned
Resource object representing subscription

customer

always returned
Resource object representing customer

card

optional
Resource object representing card

invoice

optional
Resource object representing invoice

advance_invoice_schedules

optional
Resource object representing advance_invoice_schedule

Modifies the advance invoicing schedule for a subscription.

Sample Request

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

copy

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

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

Sample Response [ JSON ]

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

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

URL Format POST

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

terms_to_charge

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

schedule_type

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

Possible values are

specific_datesCharge on specific dates. For each date, specify the number of billing cycles to charge for. Up to 5 dates can be configured.fixed_intervalsCharge at fixed intervals of time. Specify the number of billing cycles that constitute an interval and the number of days before each interval that the invoice should be generated. Also specify when the schedule should end.

fixed_interval_schedule

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

fixed_interval_schedule[number_of_occurrences]

fixed_interval_schedule[days_before_renewal]

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

fixed_interval_schedule[end_schedule_on]

optional, enumerated string
Specifies when the schedule should end.

Possible values are

fixed_interval_schedule[end_date]

specific_dates_schedule

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

specific_dates_schedule[id][0..n]

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

specific_dates_schedule[terms_to_charge][0..n]

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

specific_dates_schedule[date][0..n]

advance_invoice_schedules

always returned
Resource object representing advance_invoice_schedule

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format GET

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

advance_invoice_schedules

always returned
Resource object representing advance_invoice_schedule

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

specific_dates_schedule

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

specific_dates_schedule[id][0..n]

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

subscription

always returned
Resource object representing subscription

advance_invoice_schedules

optional
Resource object representing advance_invoice_schedule

Regenerates the invoice for the current term of the subscription. The subscription must have status as active or non_renewing. This operation is not allowed when any of the following conditions hold true for the subscription:

An invoice exists for the current term and its status is not voided.
There are unbilled charges for the current term.
The subscription has an advance invoice.

Response

Returns one of the following depending on the value of invoice_immediately:

If the value is true: an invoice object that corresponds to the regenerated invoice.
If the value is false: a list of unbilled_charge objects corresponding to all the unbilled charges created for the current term of the subscription.

Sample Request

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

copy

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

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnOuSHufVfXT/regenerate_invoice \
     -X POST  \
     -u {site_api_key}:\
     -d invoice_immediately="false" \
     -d date_from=1517826222 \
     -d date_to=1519208622 \
     -d prorate="true"

Sample Response [ JSON ]

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

{"unbilled_charges": [
    {
        "amount": 511,
        "currency_code": "USD",
        "customer_id": "__test__KyVnOuSHufVfXT",
        "date_from": 1517826222,
        "date_to": 1519208622,
        "deleted": false,
        "description": "No Trial - Prorated Charges",
        "discount_amount": 0,
        "entity_id": "no_trial",
        "entity_type": "plan",
        "id": "li___test__KyVnOuSHufVs3d",
        "is_voided": false,
        "object": "unbilled_charge",
        "pricing_model": "per_unit",
        "quantity": 1,
        "subscription_id": "__test__KyVnOuSHufVfXT",
        "unit_amount": 511
    },
    {..}
]}

URL Format POST

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

date_from

optional, timestamp(UTC) in seconds
The start date of the period being invoiced. The default value is current_term_start.

date_to

optional, timestamp(UTC) in seconds
The end date of the period being invoiced. The default value is current_term_end.

prorate

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

invoice_immediately

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

invoice

optional
Resource object representing invoice

unbilled_charges

optional
Resource object representing unbilled_charge

Imports a subscription into Chargebee.

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

id

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

client_profile_id

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

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.

plan_quantity_in_decimal

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

plan_unit_price

optional, in cents, min=0
Amount that will override the Plan's default price. The unit depends on the type of currency.

plan_unit_price_in_decimal

setup_fee

optional, in cents, min=0
Amount that will override the default setup fee. The unit depends on the type of currency.

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

optional, timestamp(UTC) in seconds
The date/time at which the subscription is to start or has started. If not provided, the subscription starts immediately.

auto_collection

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

Possible values are

po_number

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

coupon_ids[0..n]

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

contract_term_billing_cycle_on_renewal

status

required, enumerated string
Current state of the subscription.

Possible values are

current_term_end

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

Note:

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

current_term_start

optional, timestamp(UTC) in seconds
Start of the current billing period of the subscription. This is required when the subscription status is paused. When the status is active or non_renewing, it defaults to the current time.

trial_start

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

cancelled_at

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

started_at

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

activated_at

optional, timestamp(UTC) in seconds

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

The following conditions must be satisfied when passing this parameter:

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

Note:

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

pause_date

resume_date

optional, timestamp(UTC) in seconds
For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

create_current_term_invoice

optional, boolean, default=false
Set as true if you want an invoice to be created for the subscription.

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

affiliate_token

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

invoice_notes

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

meta_data

optional, jsonobject
A 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]

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

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

customer[entity_code]

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

Possible values are

aFederal governmentbState governmentcTribe/Status Indian/Indian BanddForeign diplomat

Show all values[+]

customer[exempt_number]

customer[net_term_days]

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

customer[taxjar_exemption_category]

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

Possible values are

wholesaleWhole-salegovernmentGovernmentotherOther

customer[phone]

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

customer[customer_type]

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

Possible values are

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]

customer[vat_number_prefix]

contract_term

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

contract_term[id]

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

contract_term[created_at]

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

contract_term[contract_start]

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

contract_term[billing_cycle]

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

contract_term[total_amount_raised]

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

contract_term[total_amount_raised_before_tax]

optional, in cents, default=0, min=0
The amount raised for the contract term till the time of importing the subscription excluding tax. This amount is added to the total_contract_value_before_tax

contract_term[action_at_term_end]

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

Possible values are

renew

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to renew.

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to cancel.

contract_term[cancellation_cutoff_period]

card

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

card[gateway_account_id]

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

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

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud 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

Show all values[+]

payment_method[gateway_account_id]

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

payment_method[reference_id]

payment_method[issuing_country]

payment_method[additional_information]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

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]

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.

billing_address[validation_status]

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

Possible values are

shipping_address

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

shipping_address[first_name]

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

shipping_address[validation_status]

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

Possible values are

transaction

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

transaction[amount]

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

transaction[payment_method]

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

Possible values are

cashCashcheckCheck

bank_transferBank TransferotherPayment Methods other than the above typescustomCustom

Show all values[+]

transaction[reference_number]

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

transaction[date]

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

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.

addons[quantity_in_decimal][0..n]

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

addons[unit_price][0..n]

optional, in cents, min=0

The price or per-unit-price of the addon. The value depends on the type of currency.

Note:

For recurring addons, this is the final price or per-unit price for each billing period of the subscription, regardless of the addon period. For example, consider the following details:

The unit_price provided is $10
The addon billing period is 1 month.
The plan billing period is 3 months.
The addon is only billed for $10 on each subscription renewal.

addons[unit_price_in_decimal][0..n]

addons[billing_cycles][0..n]

event_based_addons

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

event_based_addons[id][0..n]

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

event_based_addons[quantity][0..n]

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

event_based_addons[unit_price][0..n]

optional, in cents, min=0
Amount that will override the Addon's default price. The unit depends on the type of currency.

event_based_addons[quantity_in_decimal][0..n]

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

event_based_addons[unit_price_in_decimal][0..n]

event_based_addons[service_period_in_days][0..n]

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

event_based_addons[on_event][0..n]

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

Possible values are

event_based_addons[charge_once][0..n]

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

charged_event_based_addons

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

charged_event_based_addons[id][0..n]

optional, string, max chars=100
Addon id.

charged_event_based_addons[last_charged_at][0..n]

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

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

Import the subscription details of a customer.

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

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

id

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.

plan_quantity_in_decimal

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

plan_unit_price

optional, in cents, min=0
Amount that will override the Plan's default price. The unit depends on the type of currency.

plan_unit_price_in_decimal

setup_fee

optional, in cents, min=0
Amount that will override the default setup fee. The unit depends on the type of currency.

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

optional, timestamp(UTC) in seconds
The date/time at which the subscription is to start or has started. If not provided, the subscription starts immediately.

auto_collection

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

Possible values are

po_number

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

coupon_ids[0..n]

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

payment_source_id

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

status

required, enumerated string
Current state of the subscription.

Possible values are

current_term_end

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

Note:

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

current_term_start

trial_start

cancelled_at

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

started_at

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

activated_at

optional, timestamp(UTC) in seconds

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

The following conditions must be satisfied when passing this parameter:

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

Note:

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

pause_date

resume_date

optional, timestamp(UTC) in seconds
For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

contract_term_billing_cycle_on_renewal

create_current_term_invoice

optional, boolean, default=false
Set as true if you want an invoice to be created for the subscription.

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

invoice_notes

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

meta_data

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

contract_term

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

contract_term[id]

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

contract_term[created_at]

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

contract_term[contract_start]

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

contract_term[billing_cycle]

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

contract_term[total_amount_raised]

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

contract_term[total_amount_raised_before_tax]

optional, in cents, default=0, min=0
The amount raised for the contract term till the time of importing the subscription excluding tax. This amount is added to the total_contract_value_before_tax

contract_term[action_at_term_end]

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

Possible values are

renew

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to renew.

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to cancel.

contract_term[cancellation_cutoff_period]

transaction

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

transaction[amount]

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

transaction[payment_method]

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

Possible values are

cashCashcheckCheck

bank_transferBank TransferotherPayment Methods other than the above typescustomCustom

Show all values[+]

transaction[reference_number]

transaction[date]

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

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

Sample subscription [ JSON ]

API Index URL GET

Subscription attributes

Create a subscription¶

Future Subscriptions

Trial Period

Invoice

Card details

Related Tutorials

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Create subscription for customer¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List subscriptions¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

List contract terms for a subscription¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Retrieve a subscription¶

Sample Response [ JSON ]

URL Format GET

Returns

Sample admin console URL

Retrieve with scheduled changes¶

Sample Response [ JSON ]

URL Format GET

Returns

Remove scheduled changes¶

Sample Response [ JSON ]

URL Format POST

Returns

Remove scheduled cancellation¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Remove coupons¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update a subscription¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Change term end¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Reactivate a subscription¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Add charge at term end¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Charge addon at term end¶