- Home
- Subscriptions
- Customers
- Payment sources
- Virtual bank accounts
- Cards
- Promotional credits
- Invoices
- Credit notes
- Unbilled charges
- Orders
- Transactions
- Hosted pages
- Estimates
- Plans
- Addons
- Coupons
- Coupon sets
- Coupon codes
- Addresses
- Events
- Comments
- Downloads
- Portal sessions
- Site migration details
- Time machines
- Exports
- Open Source
- Chargebee JS
Subscriptions
Subscription represents the recurring items a customer has subscribed to. The recurring items can be - plan, addons. It may also contain the discount items like coupons.
Subscriptions are invoiced at the start of every term based on the recurring items and charged immediately against the customer's credit card if 'auto_collection' is turned 'on', otherwise the resulting invoice will be created as 'Payment Due'.
Sample subscription [ JSON ]
{
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "non_renewing",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1527791442,
"current_term_end": 1530383442,
"remaining_billing_cycles": 0,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1414780242,
"cancelled_at": 1530383442,
"updated_at": 1528093635,
"has_scheduled_changes": false,
"resource_version": 1528093635000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 2,
"due_since": 1438367442,
"total_dues": 1800,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"company": "Acme Inc",
"phone": "+1 (614) 226-4809",
"line1": "345, Redington Av",
"line2": "Suite 1200",
"city": "Los Angeles",
"state_code": "CA",
"state": "California",
"country": "US",
"validation_status": "not_validated",
"object": "shipping_address"
}
}
API Index URL GET
https://{site}.chargebee.com/api/v2/subscriptions
A unique identifier to identify the subscription. You will use this to perform all operations on this subscription.
string, max chars=50
string, max chars=50
Identifier of the customer with whom this subscription is associated.
string, max chars=50
string, max chars=50
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
optional, integer, min=1
optional, integer, min=1
Defines billing frequency in association with the billing period.
optional, enumerated string
optional, enumerated string
Possible values are
weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).
Current state of the subscription.
enumerated string
enumerated string
Possible values are
futureThe Subscription is scheduled to start in a future date.in_trialThe subscription is in trial.activeThe subscription is in active state and will be charged at start of each term based on the recurring items(plan & addons etc.,).non_renewingThe subscription will be cancelled at end of the current term.pausedThe subscription is paused. No new recurring actions will be allowed, but any pending payments will be collected.cancelledThe subscription has been cancelled. No new recurring actions will take place, but any pending payments will be collected.
Applicable only for 'future' subscriptions. The scheduled start time of the 'future' subscription.
optional, timestamp(UTC) in seconds
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 'trial' state when it starts.
optional, timestamp(UTC) in seconds
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 'trial' state when it starts.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
End of the current billing term. Subscription is renewed immediately after this.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
The number of billing cycles this subscription will run.
optional, integer, min=0
optional, integer, min=0
Time at which the subscription got started. Will be null for 'future' subscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Time at which the subscription moved from in_trial state to active state.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Time at which subscription was canceled or is set to be canceled.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Possible reason the subscription might be cancelled.
optional, enumerated string
optional, enumerated string
Possible values are
not_paidNot Paid.no_cardNo Card.fraud_review_failedFraud Review Failed.non_compliant_eu_customerNon Compliant EU Customer.tax_calculation_failedTax Calculation Failed.currency_incompatible_with_gatewayCurrency incompatible with Gateway.non_compliant_customerNon Compliant Customer.
The IP address of the user. Used primarly in refersion integration. Refersion uses this field to track/log affiliate subscription.
optional, string, max chars=50
optional, string, max chars=50
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
optional, long
Timestamp indicating when this subscription was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.
Note: This value does not change when the following attributes are changed: due_invoices_count, due_since, total_dues.
optional, timestamp(UTC) in seconds
Note: This value does not change when the following attributes are changed: due_invoices_count, due_since, total_dues.
optional, timestamp(UTC) in seconds
If true, there are subscription changes scheduled on next renewal.
boolean, default=false
boolean, default=false
Payment source attached to this subscription. If present, customer's payment sources won't be used to collect any payment for this subscripiton.
optional, string, max chars=40
optional, string, max chars=40
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string
optional, enumerated string
Possible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. All payments must be recorded offline.
Total number of invoices that are due for payment. Note: Not supported if consolidated invoicing is enabled.
optional, integer
optional, integer
Time since this subscription has unpaid invoices. Note: Not supported if consolidated invoicing is enabled.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Total invoice due amount for this subscription. Note: Not supported if consolidated invoicing is enabled.
optional, in cents, min=0
optional, in cents, min=0
Monthly recurring revenue for the subscription. Note: This may not return accurate values since updated asynchronously.
optional, in cents, min=1
optional, in cents, min=1
Exchange rate used for base currency conversion.
optional, bigdecimal, min=1E-9, max=999999999.999999999
optional, bigdecimal, min=1E-9, max=999999999.999999999
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
optional, jsonobject
List of addons for this subscription with quantity(if applicable).
optional, list of addon
optional, list of addon
Addon attributes
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
optional, integer, default=1, min=1
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
optional, in cents, min=0
The time at which the trial ends for the addon. In order to use this param please contact support@chargebee.com.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
List of non-recurring addons that will be charged on the occurrence of specified event.
optional, list of event_based_addon
optional, list of event_based_addon
Event based addon attributes
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
integer, min=1
integer, min=1
Event on which this addon will be charged.
enumerated string
enumerated string
Possible values are
subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.
List of event_based_addons that have already been charged.
optional, list of charged_event_based_addon
optional, list of charged_event_based_addon
List of coupons for this subscription.
optional, list of coupon
optional, list of coupon
Coupon attributes
The date till the coupon is to be applied. Applicable for "limited months" coupons.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Shipping address for the subscription.
optional, shipping_address
optional, shipping_address
Shipping addres attributes
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
Referral details if exists for the subscription.
optional, referral_info
optional, referral_info
Referral info attributes
External reference id in referral system for the subscription.
optional, string, max chars=50
optional, string, max chars=50
Reward status for the referral subscription.
optional, enumerated string, default=pending
optional, enumerated string, default=pending
Possible values are
pendingPending.paidPaid.invalidInvalid.Source referral system for the referral subscription.
optional, enumerated string
optional, enumerated string
Possible values are
referral_candyReferral Candy.referral_saasquatchReferral Saasquatch.friendbuyFriendbuy.Friend offer type for the referral camapign.
optional, enumerated string
optional, enumerated string
Possible values are
noneNone.couponCoupon.coupon_codeCoupon Code.Referrer reward type for the referral campaign.
optional, enumerated string
optional, enumerated string
Possible values are
noneNone.referral_direct_rewardReferral Direct Reward.custom_promotional_creditCustom Promotional Credit.custom_revenue_percent_basedCustom Revenue Percent Based.Whether or not to notify the referral purchases to the referral system.
optional, enumerated string
optional, enumerated string
Possible values are
noneNone.first_paid_conversionFirst Paid Conversion.all_invoicesAll Invoices.Create a subscription¶
Creates a new subscription along with the customer. You can attach a plan, plan quantity, one or more addons and coupon while creating this subscription.
Future Subscriptions
If the start_date is specified, the subscription will be created in 'future' state (.ie, instead of starting immediately it will be scheduled to start at the specified 'start_date'). Besides if 'trial' is specified (plan configuration or specified explictly using trial_end), the subscription will go into 'trial' state when it starts. Otherwise it will directly become 'active' when it starts.
Trial Period
If the plan has trial period or if the trial_end is specified explicitly, the subscription will be created in 'in_trial' state.
If the card details are passed, it is not charged until the end of the trial period. Incase you need to verify the card you could enable the 'card verification option' in the gateway settings.
Invoice
If the plan does not have a trial period and if any of the recurring items has charges, then a invoice would be raised immediately. If 'auto_collection' is turned 'on', then card attributes are mandatory and subscription will be created only if the payment was successful.
Card details
Passing card details to this API involves PCI liability at your end as sensitive card information passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable
- If you are using Stripe gateway, you can use Stripe.js with your checkout form. Please refer this tutorial for more details.
- If you are using Braintree gateway, you can use Braintree.js with your checkout form. Please refer this tutorial for more details.
- 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.
Billing Address
The Billing Address is significant especially when EU VAT taxes are involved, for tax calculations will be based on this address. For customers without Billing Address, EU VAT taxes will not be included. Thus ensure to set this properly if you have configured EU VAT Tax.
Note: For the sites created before 1st Mar 2014, customer's billing address and 'vat_number' will be replaced automatically whenever the associated card gets updated. i.e existing values for billing address and 'vat_number' will be cleared and the new values will be set. This behaviour is changed now - The VAT number should always be passed along billing address and not with card address. Both the addresses have to be dealt separately.
Billing Address attributes shall be explicitly passed for customers paying offline(Cash, Check, Bank Transfer etc).
Related Tutorials
- Check out this tutorial to create trial signup with custom fields.
- Learn how to implement a in-app checkout flow that allows your customers to select addons and apply coupons. Estimate API is used to dynamically calculate the order summary shown to the customer.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions \
-u {site_api_key}: \
-d customer[email]="john@user.com" \
-d customer[first_name]="John" \
-d customer[last_name]="Doe" \
-d customer[locale]="fr-CA" \
-d customer[phone]="+1-949-999-9999" \
-d plan_id="basic" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions \
-u {site_api_key}: \
-d customer[email]="john@user.com" \
-d customer[first_name]="John" \
-d customer[last_name]="Doe" \
-d customer[locale]="fr-CA" \
-d customer[phone]="+1-949-999-9999" \
-d plan_id="basic" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
Sample Response [ JSON ]
{
"subscription": {
"id": "5SK0b8q3QtywQmF8t",
"customer_id": "5SK0b8q3QtywQmF8t",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "in_trial",
"trial_start": 1528093937,
"trial_end": 1530685937,
"next_billing_at": 1530685937,
"created_at": 1528093937,
"started_at": 1528093937,
"updated_at": 1528093937,
"has_scheduled_changes": false,
"resource_version": 1528093937000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 0
},
"customer": {
"id": "5SK0b8q3QtywQmF8t",
"first_name": "John",
"last_name": "Doe",
"email": "john@user.com",
"phone": "+1-949-999-9999",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1528093937,
"taxability": "taxable",
"updated_at": 1528093937,
"locale": "fr-CA",
"resource_version": 1528093937000,
"deleted": false,
"object": "customer",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"card_status": "no_card",
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions
Input Parameters
Id for the new subscription. If not given, this will be auto-generated.
optional, string, max chars=50
optional, string, max chars=50
Allows you to specify a future date or a past date on which the subscription starts.Past dates can be entered in case the subscription has already started. Any past date entered must be within the current billing cycle/plan term. The subscription will start immediately if this parameter is not passed.
optional, timestamp(UTC) in seconds
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.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
optional, integer, min=0
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string
optional, enumerated string
Possible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. All payments must be recorded offline.
The number of future renewals for which advance invoicing is done. However, if a new term gets started in this operation, the specified terms_to_charge will be inclusive of this new term.
optional, integer, min=1
optional, integer, min=1
Applicable when calendar billing is enabled and subscription is getting created in active / non_renewing states. Unless specified the configured default value will be used.
optional, enumerated string
optional, enumerated string
Possible values are
immediateSubscription period will be aligned with the configured billing date immediately.delayedSubscription period will be aligned with the configured billing date at a later date (subsequent renewals).
List of addons IDs that are mandatory to the plan and has to be removed from the subscription.
optional, list of string
optional, list of string
Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string
optional, list of string
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
optional, jsonobject
Applicable when charges are added during this operation. If specified as false, these charges will be added to unbilled charges. The default value for this parameter will be as per your site settings.
optional, boolean
optional, boolean
customer
Parameters for customer
pass parameters as customer[<param name>]
pass parameters as customer[<param name>]
Id for the new customer. If not given, this will be same as the subscription id.
optional, string, max chars=50
optional, string, max chars=50
Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70
optional, string, max chars=70
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable
optional, enumerated string, default=taxable
Possible values are
taxableCustomer is taxable.exemptCustomer is exempted from tax.
Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.
optional, string, max chars=50
optional, string, max chars=50
The exemption category of the customer, for the USA and Canada. applicable if you use Chargebee's Avalara integration.
optional, enumerated string
optional, enumerated string
Possible values are
aFederal government (United States).bState government (United States).cTribe/Status Indian/Indian Band (both).dForeign diplomat (United States).eCharitable or benevolent org (United States).fReligious or educational org (United States).gResale (United States).hCommercial agricultural production (United States).iIndustrial production/manufacturer (United States).jDirect pay permit (United States).kDirect mail (United States).lOther (United States).nLocal government (United States).pCommercial aquaculture (Canada).qCommercial Fishery (Canada).rNon-resident (Canada).med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.
Show all values[+]
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable only for Avalara.
optional, string, max chars=100
optional, string, max chars=100
The number of days within which the customer has to make payment for the invoice.
optional, integer, default=0
optional, integer, default=0
Whether payments needs to be collected automatically for this customer.
optional, enumerated string, default=on
optional, enumerated string, default=on
Possible values are
onWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.offAutomatic collection of charges will not be made. All payments must be recorded offline.
Whether the customer can pay via Direct Debit.
optional, boolean, default=false
optional, boolean, default=false
Applicable when consolidated invoicing is enabled. Indicates whether invoice consolidation should happen during subscription renewals. Needs to be set only if this value is different from the defaults configured.
optional, boolean
optional, boolean
Confirms that a customer is registered under GST. This field is available for Australia only.
optional, boolean
optional, boolean
card
Parameters for card
pass parameters as card[<param name>]
pass parameters as card[<param name>]
The gateway account in which this payment source is stored.
optional, string, max chars=50
optional, string, max chars=50
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500
required if card provided, string, max chars=1500
The card verification value. If you are using Braintree.js, you can specify the Braintree encrypted cvv here.
optional, string, max chars=520
optional, string, max chars=520
Address line 1, as available in card billing address.
optional, string, max chars=150
optional, string, max chars=150
Address line 2, as available in card billing address.
optional, string, max chars=150
optional, string, max chars=150
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
optional, string, max chars=20
bank_account
Parameters for bank_account
pass parameters as bank_account[<param name>]
pass parameters as bank_account[<param name>]
The gateway account in which this payment source is stored.
optional, string, max chars=50
optional, string, max chars=50
Account holder’s International Bank Account Number.
optional, string, min chars=10, max chars=50
optional, string, min chars=10, max chars=50
Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150
optional, string, max chars=150
Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150
optional, string, max chars=150
Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=250
optional, string, max chars=250
Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
optional, string, max chars=70
optional, string, max chars=70
Account holder’s bank account number.
optional, string, min chars=5, max chars=17
optional, string, min chars=5, max chars=17
For Authorize.net ACH users only. Indicates the type of account.
optional, enumerated string
optional, enumerated string
Possible values are
checkingChecking Account.savingsSavings Account.
For Stripe ACH users only. Indicates the account holder type.
optional, enumerated string
optional, enumerated string
Possible values are
individualIndividual.companyCompany.
For Authorize.net ACH users only. Indicates the type of eCheck.
optional, enumerated string
optional, enumerated string
Possible values are
webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.
2-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
optional, string, max chars=50
optional, string, max chars=50
For GoCardless Autogiro users only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
optional, string, min chars=10, max chars=12
optional, string, min chars=10, max chars=12
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
pass parameters as payment_method[<param name>]
The type of payment method. For more details refer
Update payment method for a customer API under Customer resource.
optional, enumerated string
optional, enumerated string
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.
Show all values[+]
The gateway account in which this payment source is stored.
optional, string, max chars=50
optional, string, max chars=50
The reference id. In the case of Amazon and PayPal this will be the
billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=50
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=50
Single-use token created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet or card details. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k
required if reference_id not provided, string, max chars=65k
2-letter (alpha2) ISO country code. Indicates your customer's payment method country of issuance. Applicable for PayPal via Braintree.
optional, string, max chars=50
optional, string, max chars=50
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
pass parameters as billing_address[<param name>]
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
The address verification status.
optional, enumerated string, default=not_validated
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
pass parameters as shipping_address[<param name>]
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
The address verification status.
optional, enumerated string, default=not_validated
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
pass parameters as addons[<param name>][<idx:0..n>]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
optional, integer, default=1, min=1
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
optional, in cents, min=0
Number of billing cycles the addon will be charged for.
optional, integer, min=1
optional, integer, min=1
The time at which the trial ends for the addon. In order to use this param please contact support@chargebee.com.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
event_based_addons
Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.
pass parameters as event_based_addons[<param name>][<idx:0..n>]
pass parameters as event_based_addons[<param name>][<idx:0..n>]
A unique 'id' used to identify the addon.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
optional, integer, min=1
Amount that will override the Addon's default price.
optional, in cents, min=0
optional, in cents, min=0
Event on which this addon will be charged.
optional, enumerated string
optional, enumerated string
Possible values are
subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true
optional, boolean, default=true
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Resource object representing unbilled_charge.
optional
optional
Create subscription for customer¶
Creates a new subscription for an existing customer. You can attach a plan, plan quantity, one or more addons and coupon while creating this subscription.
If the plan does not have a trial period and if any of the recurring-item has charges, then the customer is charged immediately if auto_collection is turned 'on'. In that case, subscription is created only if the customer has a payment method on file and attempted payment is successful.
Notes
If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/8avVGOkx8U1MX/subscriptions \
-u {site_api_key}: \
-d plan_id="basic"
copy
curl https://{site}.chargebee.com/api/v2/customers/8avVGOkx8U1MX/subscriptions \
-u {site_api_key}: \
-d plan_id="basic"
Sample Response [ JSON ]
{
"subscription": {
"id": "5SK0b8q3QtywQrg8x",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "in_trial",
"trial_start": 1528093937,
"trial_end": 1530685937,
"next_billing_at": 1530685937,
"created_at": 1528093937,
"started_at": 1528093937,
"updated_at": 1528093937,
"has_scheduled_changes": false,
"resource_version": 1528093937000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 0
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093934,
"resource_version": 1528093934000,
"deleted": false,
"object": "customer",
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/subscriptions
Input Parameters
Id for the new subscription. If not given, this will be auto-generated.
optional, string, max chars=50
optional, string, max chars=50
Allows you to specify a future date or a past date on which the subscription starts.Past dates can be entered in case the subscription has already started. Any past date entered must be within the current billing cycle/plan term. The subscription will start immediately if this parameter is not passed.
optional, timestamp(UTC) in seconds
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.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
optional, integer, min=0
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string
optional, enumerated string
Possible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. All payments must be recorded offline.
The number of future renewals for which advance invoicing is done. However, if a new term gets started in this operation, the specified terms_to_charge will be inclusive of this new term.
optional, integer, min=1
optional, integer, min=1
Applicable when calendar billing is enabled and subscription is getting created in active / non_renewing states. Unless specified the configured default value will be used.
optional, enumerated string
optional, enumerated string
Possible values are
immediateSubscription period will be aligned with the configured billing date immediately.delayedSubscription period will be aligned with the configured billing date at a later date (subsequent renewals).
List of addons IDs that are mandatory to the plan and has to be removed from the subscription.
optional, list of string
optional, list of string
Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string
optional, list of string
Unique identifier of the payment source to be attached to this subscription.
optional, string, max chars=40
optional, string, max chars=40
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
optional, jsonobject
Applicable when charges are added during this operation. If specified as false, these charges will be added to unbilled charges. The default value for this parameter will be as per your site settings.
optional, boolean
optional, boolean
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
pass parameters as shipping_address[<param name>]
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
The address verification status.
optional, enumerated string, default=not_validated
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
pass parameters as addons[<param name>][<idx:0..n>]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
optional, integer, default=1, min=1
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
optional, in cents, min=0
Number of billing cycles the addon will be charged for.
optional, integer, min=1
optional, integer, min=1
The time at which the trial ends for the addon. In order to use this param please contact support@chargebee.com.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
event_based_addons
Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.
pass parameters as event_based_addons[<param name>][<idx:0..n>]
pass parameters as event_based_addons[<param name>][<idx:0..n>]
A unique 'id' used to identify the addon.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
optional, integer, min=1
Amount that will override the Addon's default price.
optional, in cents, min=0
optional, in cents, min=0
Event on which this addon will be charged.
optional, enumerated string
optional, enumerated string
Possible values are
subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true
optional, boolean, default=true
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Resource object representing unbilled_charge.
optional
optional
List subscriptions¶
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions \
-G \
-u {site_api_key}: \
--data-urlencode limit="5" \
--data-urlencode plan_id[is_not]="basic" \
--data-urlencode status[is]="active" \
--data-urlencode sort_by[asc]="created_at"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions \
-G \
-u {site_api_key}: \
--data-urlencode limit="5" \
--data-urlencode plan_id[is]="basic" \
--data-urlencode status[is_not]="active" \
--data-urlencode sort_by[asc]="created_at"
Sample Response [ JSON ]
{
"list": [
{
"subscription": {
"id": "5SK0b8q3QtywQrg8x",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "in_trial",
"trial_start": 1528093937,
"trial_end": 1530685937,
"next_billing_at": 1530685937,
"created_at": 1528093937,
"started_at": 1528093937,
"updated_at": 1528093937,
"has_scheduled_changes": false,
"resource_version": 1528093937000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 0
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093934,
"resource_version": 1528093934000,
"deleted": false,
"object": "customer",
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
},
{..}
],
"next_offset": "[\"1528093937000\",\"168000000105\"]"
}
URL Format GET
https://{site}.chargebee.com/api/v2/subscriptions
Input Parameters
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
optional, string, max chars=1000
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
optional, boolean, default=false
optional, boolean, default=false
Sorts based on the specified attribute.
Supported attributes : created_at
Supported sort-orders : asc, desc
Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
optional, string filter
Supported attributes : created_at
Supported sort-orders : asc, desc
Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
optional, string filter
Filter Params
For operator usages, see the Pagination and Filtering section.
To filter based on Subscription Id.
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "8gsnbYfsMLds"
optional, string filter
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "8gsnbYfsMLds"
optional, string filter
To filter based on Subscription Customer Id.
Supported operators : is, is_not, starts_with, in, not_in
Example → customer_id[is] = "8gsnbYfsMLds"
optional, string filter
Supported operators : is, is_not, starts_with, in, not_in
Example → customer_id[is] = "8gsnbYfsMLds"
optional, string filter
To filter based on Subscription Plan Id.
Supported operators : is, is_not, starts_with, in, not_in
Example → plan_id[is] = "basic"
optional, string filter
Supported operators : is, is_not, starts_with, in, not_in
Example → plan_id[is] = "basic"
optional, string filter
To filter based on Subscription State. Possible values are : future, in_trial, active, non_renewing, paused, cancelled.
Supported operators : is, is_not, in, not_in
Example → status[is] = "active"
optional, enumerated string filter
Supported operators : is, is_not, in, not_in
Example → status[is] = "active"
optional, enumerated string filter
To filter based on Subscription Cancel Reason. Possible values are : not_paid, no_card, fraud_review_failed, non_compliant_eu_customer, tax_calculation_failed, currency_incompatible_with_gateway, non_compliant_customer.
Supported operators : is, is_not, in, not_in, is_present
Example → cancel_reason[is] = "not_paid"
optional, enumerated string filter
Supported operators : is, is_not, in, not_in, is_present
Example → cancel_reason[is] = "not_paid"
optional, enumerated string filter
To filter based on Subscription Remaining Billing Cycles.
Supported operators : is, is_not, lt, lte, gt, gte, between, is_present
Example → remaining_billing_cycles[is] = "3"
optional, integer filter
Supported operators : is, is_not, lt, lte, gt, gte, between, is_present
Example → remaining_billing_cycles[is] = "3"
optional, integer filter
To filter based on Subscription Created At.
Supported operators : after, before, on, between
Example → created_at[before] = "1435054328"
optional, timestamp(UTC) in seconds filter
Supported operators : after, before, on, between
Example → created_at[before] = "1435054328"
optional, timestamp(UTC) in seconds filter
To filter based on Subscription Activated At.
Supported operators : after, before, on, between, is_present
Example → activated_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter
Supported operators : after, before, on, between, is_present
Example → activated_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter
To filter based on Subscription Next Billing At.
Supported operators : after, before, on, between
Example → next_billing_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter
Supported operators : after, before, on, between
Example → next_billing_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter
To filter based on Subscription Cancelled At.
Supported operators : after, before, on, between
Example → cancelled_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter
Supported operators : after, before, on, between
Example → cancelled_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter
To filter based on Subscription Has Scheduled Changes. Possible values are : true, false
Supported operators : is
Example → has_scheduled_changes[is] = "true"
optional, boolean filter
Supported operators : is
Example → has_scheduled_changes[is] = "true"
optional, boolean filter
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
next_offset
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000
optional, string, max chars=1000
Retrieve a subscription¶
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "non_renewing",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1527791442,
"current_term_end": 1530383442,
"remaining_billing_cycles": 0,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1414780242,
"cancelled_at": 1530383442,
"updated_at": 1528093748,
"has_scheduled_changes": false,
"resource_version": 1528093748000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093934,
"resource_version": 1528093934000,
"deleted": false,
"object": "customer",
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
}
URL Format GET
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Sample admin console URL
https://{site}.chargebee.com/admin-console/subscriptions/8avVGOkx8U1MX
Retrieve with scheduled changes¶
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
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/retrieve_with_scheduled_changes \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/retrieve_with_scheduled_changes \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "no_trial",
"plan_quantity": 7,
"plan_unit_price": 1000,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "non_renewing",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1527791442,
"current_term_end": 1530383442,
"remaining_billing_cycles": 4,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1414780242,
"cancelled_at": 1530383442,
"updated_at": 1528093748,
"has_scheduled_changes": false,
"resource_version": 1528093748000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093934,
"resource_version": 1528093934000,
"deleted": false,
"object": "customer",
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
}
URL Format GET
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/retrieve_with_scheduled_changes
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Remove scheduled changes¶
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_scheduled_changes \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_scheduled_changes \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "non_renewing",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1527791442,
"current_term_end": 1530383442,
"remaining_billing_cycles": 0,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1414780242,
"cancelled_at": 1530383442,
"updated_at": 1528093937,
"has_scheduled_changes": false,
"resource_version": 1528093937000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093934,
"resource_version": 1528093934000,
"deleted": false,
"object": "customer",
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_changes
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing credit_note.
optional
optional
Remove scheduled cancellation¶
If the subscription is in Non Renewing or In Trial state and is also scheduled to cancel at the end of current term, then this API can be used to remove the scheduled cancellation. When a scheduled cancellation is removed, the subscription will revert to Active or In Trial state, whichever is the state before cancellation was scheduled.
While removing the scheduled cancellation, you may specify the number of billing cycles. If the billing cycle is not specified, the default billing cycle from the plan will be applied on the subscription.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_scheduled_cancellation \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_scheduled_cancellation \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1527791442,
"current_term_end": 1530383442,
"next_billing_at": 1530383442,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1414780242,
"updated_at": 1528093937,
"has_scheduled_changes": false,
"resource_version": 1528093937000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093934,
"resource_version": 1528093934000,
"deleted": false,
"object": "customer",
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_cancellation
Input Parameters
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Remove coupons¶
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_coupons \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_coupons \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "RtSlqIzN6qkgFw",
"customer_id": "RtSlqIzN6qkgFw",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "in_trial",
"trial_start": 1528093639,
"trial_end": 1530685639,
"next_billing_at": 1530685639,
"created_at": 1528093639,
"started_at": 1528093639,
"updated_at": 1528093937,
"has_scheduled_changes": false,
"resource_version": 1528093937000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 0
},
"customer": {
"id": "RtSlqIzN6qkgFw",
"first_name": "Steve",
"last_name": "Smith",
"email": "Steve@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1528093639,
"taxability": "taxable",
"updated_at": 1528093639,
"resource_version": 1528093639000,
"deleted": false,
"object": "customer",
"card_status": "valid",
"primary_payment_source_id": "pm_5SK0b8vNQtyvBRv7t",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "tok_5SK0b8vNQtyvBRq7s",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"iin": "411111",
"last4": "1111",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 1,
"expiry_year": 2022,
"object": "card",
"masked_number": "************1111",
"customer_id": "RtSlqIzN6qkgFw",
"payment_source_id": "pm_5SK0b8vNQtyvBRv7t"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_coupons
Input Parameters
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Update a subscription¶
You can modify the plan, plan quantity and add or remove addons for the subscription. By default the changes are applied immediately and the charges (/credits) are prorated and adjusted with the next billing term. You may also choose to effect the changes at the end of the current term by passing end_of_term as "true". In this case proration will not be done.
Only the parameters that are passed are modified for the subscription. Rest will reflect the existing values.
By default, the addons passed are appended to the existing list of addons for this subscription. In case a passed addon already exists for this subscription, quantity value is replaced. If you want to completely replace the addons for this subscription, pass replace_addon_list as "true".
Card and 'vat_number' attributes can also be passed during subscription update. If they are passed, corresponding Billing Info attributes - the Billing Address and 'vat_number' - will be replaced automatically.
Passing credit card details to this API involves PCI liability at your end as sensitive card info passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable
- If you are using Stripe gateway, you can use Stripe.js with your checkout form. Please refer this tutorial for more details.
- If you are using Braintree gateway, you can use Braintree.js with your checkout form. 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
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX \
-u {site_api_key}: \
-d plan_id="basic" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX \
-u {site_api_key}: \
-d plan_id="basic" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1527791442,
"current_term_end": 1530383442,
"next_billing_at": 1530383442,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1414780242,
"updated_at": 1528093938,
"has_scheduled_changes": false,
"resource_version": 1528093938000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093938,
"resource_version": 1528093938000,
"deleted": false,
"object": "customer",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
},
"credit_notes": []
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}
Input Parameters
Applicable only for 'future' subscriptions. The new start date of the 'future' subscription.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
The time at which the trial should end for this subscription. Can be specified to override the default trial period defined in plan. If '0' is passed, the subscription will be activated immediately.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
optional, integer, min=0
Should be true if the existing addons should be replaced with the ones that are being passed.
optional, boolean
optional, boolean
List of addons IDs that are mandatory to the plan and has to be removed from the subscription.
optional, list of string
optional, list of string
The number of future renewals for which advance invoicing is done. However, if a new term gets started in this operation, the specified terms_to_charge will be inclusive of this new term.
optional, integer, min=1
optional, integer, min=1
The time from which this subscription should be reactivated.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Applicable when calendar billing is enabled and a new term gets started during this operation. Unless specified the configured default value will be used.
optional, enumerated string
optional, enumerated string
Possible values are
immediateSubscription period will be aligned with the configured billing date immediately.delayedSubscription period will be aligned with the configured billing date at a later date (subsequent renewals).
Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string
optional, list of string
Should be true if the existing coupons should be replaced with the ones that are being passed.
optional, boolean
optional, boolean
Add Prorated Credits and Charges, if applicable, while updating the subscription. If this parameter is not passed, the default value set in the Site Settings will be used. Else, it will be assumed as true.
optional, boolean
optional, boolean
Applicable for 'Active' & 'Non Renewing' states alone. Generally, subscription's term will be reset (i.e current term is ended and a new term starts immediately) when a new plan having different billing frequency is specified in the input. For all the other cases, the subscription's term will remain intact. Now for this later scenario, if you want to force a term reset you can specify this param as 'true'. Note: Specifying this value as 'false' has no impact on the default behaviour.
optional, boolean, default=false
optional, boolean, default=false
Applicable only for canceled subscriptions. Once this is passed as true, canceled subscription will become active; otherwise subscription changes will be made but the the subscription state will remain canceled. If not passed, subscription will be activated only if there is any change in subscription data.
optional, boolean
optional, boolean
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
optional, jsonobject
Applicable when charges are added during this operation. If specified as false, these charges will be added to unbilled charges. The default value for this parameter will be as per your site settings.
optional, boolean
optional, boolean
card
Parameters for card
pass parameters as card[<param name>]
pass parameters as card[<param name>]
The gateway account in which this payment source is stored.
optional, string, max chars=50
optional, string, max chars=50
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500
required if card provided, string, max chars=1500
The card verification value. If you are using Braintree.js, you can specify the Braintree encrypted cvv here.
optional, string, max chars=520
optional, string, max chars=520
Address line 1, as available in card billing address.
optional, string, max chars=150
optional, string, max chars=150
Address line 2, as available in card billing address.
optional, string, max chars=150
optional, string, max chars=150
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
optional, string, max chars=20
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
pass parameters as payment_method[<param name>]
The type of payment method. For more details refer
Update payment method for a customer API under Customer resource.
optional, enumerated string
optional, enumerated string
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.
Show all values[+]
The gateway account in which this payment source is stored.
optional, string, max chars=50
optional, string, max chars=50
The reference id. In the case of Amazon and PayPal this will be the
billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=50
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=50
Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k
required if reference_id not provided, string, max chars=65k
2-letter (alpha2) ISO country code. Indicates your customer's payment method country of issuance. Applicable for PayPal via Braintree.
optional, string, max chars=50
optional, string, max chars=50
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
pass parameters as billing_address[<param name>]
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
The address verification status.
optional, enumerated string
optional, enumerated string
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
pass parameters as shipping_address[<param name>]
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
The address verification status.
optional, enumerated string
optional, enumerated string
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.customer
Parameters for customer
pass parameters as customer[<param name>]
pass parameters as customer[<param name>]
Confirms that a customer is registered under GST. This field is available for Australia only.
optional, boolean
optional, boolean
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
pass parameters as addons[<param name>][<idx:0..n>]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
optional, integer, min=1
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
optional, in cents, min=0
Number of billing cycles the addon will be charged for.
optional, integer, min=1
optional, integer, min=1
The time at which the trial ends for the addon. Trial end cannot be updated for addons which are attached to subscriptions. In order to use this param please contact support@chargebee.com.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
event_based_addons
Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.
pass parameters as event_based_addons[<param name>][<idx:0..n>]
pass parameters as event_based_addons[<param name>][<idx:0..n>]
A unique 'id' used to identify the addon.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
optional, integer, min=1
Amount that will override the Addon's default price.
optional, in cents, min=0
optional, in cents, min=0
Indicates when the non-recurring addon will be charged.
optional, enumerated string
optional, enumerated string
Possible values are
immediatelyCharges for the addon will be applied immediately.on_eventCharge for the addon will be applied on the occurrence of a specified event.
Event on which this addon will be charged.
optional, enumerated string
optional, enumerated string
Possible values are
subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Resource object representing unbilled_charge.
optional
optional
Resource object representing credit_note.
optional
optional
Change term end¶
Changes the subscription's current term end date. Depending on the "status" of the subscription, "term end date" has different effects.
- If the Subscription is in trial, it affects trial end date.
- If the Subscription is active, it affects the next billing date.
- If the Subscription's status is non_renewing, this affects the upcoming cancellation date.
Tip: To cycle through a couple of billing cycles and test webhooks, you may use this API.
Notes
- When changing the term_end for active / non_renewing subscriptions, by default no additional charges (when term gets extended) will be added or credits (when term gets reduced) will be issued. However you can specify prorate param as true for adding prorated charges / issuing prorated credits. Further for the charges that got added, you can specify invoice_immediately as false to add them to unbilled charges and invoice them later.
- Advance charges, if any will be credited back during this operation.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/change_term_end \
-u {site_api_key}: \
-d term_ends_at="1609459199"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/change_term_end \
-u {site_api_key}: \
-d term_ends_at="1609459199"
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1527791442,
"current_term_end": 1609459199,
"next_billing_at": 1609459199,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1414780242,
"updated_at": 1528093938,
"has_scheduled_changes": false,
"resource_version": 1528093938000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093938,
"resource_version": 1528093938000,
"deleted": false,
"object": "customer",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/change_term_end
Input Parameters
The time at which the current term should end for this subscription.
required, timestamp(UTC) in seconds
required, timestamp(UTC) in seconds
Applicable for active / non_renewing subscriptions. If specified as true prorated charges / credits will be added during this operation.
optional, boolean
optional, boolean
Applicable when charges are added during this operation. If specified as false, these charges will be added to unbilled charges. The default value for this parameter will be as per your site settings.
optional, boolean
optional, boolean
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Resource object representing unbilled_charge.
optional
optional
Resource object representing credit_note.
optional
optional
Cancel a subscription¶
Cancelling a subscription will move the subscription from its current state to Cancelled, and will stop all recurring actions.
You could schedule the cancellation by passing end_of_term parameter as true. If scheduled, the subscription status will be set to non_renewing if it is in active state, until the end of term, and then cancelled. A subscription's state will not change if it is in in_trial state. However, cancellation will be scheduled at the end of the trial.
CREDIT OPTION
On subscription cancellation, credits can be issued against current term charges of the subscription by using credit_option_for_current_term_charges. You can choose to either provide no credits, prorate credits for the unused period or issue full credits for the current term charges.
UNBILLED CHARGES
Any unbilled charges present in the subscription can either be invoiced or deleted by specifying unbilled_charges_option. Note that automatic charge will be attempted on the payment method available if the customer has enabled auto-collection. If not, the invoice will be closed as unpaid.
ACCOUNT RECEIVABLES
Specifying account_receivables_handling allows you to close invoices of the subscription which have amounts due. The invoices are chosen for payment collection or for writing off the due amount after applying the available credits and excess payments.
If specified as schedule_payment_collection, payment collection for the amount due of past invoices will be attempted. The payment method available will be charged if auto-collection is enabled for the customer, and appropriate payment collection(payment succeeded or payment failed) events will be triggered. If the payment collection fails, no further retries will be made on the invoices. Note: If the invoices of the subscription are consolidated, and any of the subscriptions in the consolidated invoice are cancelled, these invoices will not be selected for collection.
If specified as write_off, the amount due of past invoices will be written-off. Note: If the invoices of the subscription are consolidated, and any of the subscriptions in the consolidated invoice are still active(future, in-trial, active, and non-renewing), these invoices will not be selected for the write-off operation.
ACCOUNT PAYABLES
Specifying refundable_credits_handling allows you to provide refunds for refundable credits remaining, after they are applied to a subscription’s due invoices. The refund initiated will be asynchronous and the payment refunded event will be triggered on refund success. Note: Consolidated credit notes of the subscription will not be selected for refund.
Notes
Advance charges, if any, will be refunded as credits.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/cancel \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/cancel \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "cancelled",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1527791442,
"current_term_end": 1528093938,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1414780242,
"cancelled_at": 1528093938,
"updated_at": 1528093938,
"has_scheduled_changes": false,
"resource_version": 1528093938000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 0,
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093938,
"resource_version": 1528093938000,
"deleted": false,
"object": "customer",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/cancel
Input Parameters
You can specify when you want to cancel the subscription.
optional, boolean, default=false
optional, boolean, default=false
Specify this if you want to issue credits against the current term charges. Not applicable when 'end_of_term' is true.
optional, enumerated string
optional, enumerated string
Possible values are
noneNo credits will be issued against current term charges.prorateProrated credits for the unused period will be issued against current term charges.fullCredits will be issued for all the current term charges.
Applicable when unbilled charges are present for this subscription. If specified as delete, these charges will be deleted instead of getting invoiced immediately. Note: On the invoice raised, an automatic charge will be attempted on the payment method available if customer's auto-collection property is ‘ON’. Not applicable when 'end_of_term' is true.
optional, enumerated string
optional, enumerated string
Possible values are
invoiceUnbilled charges will be raised as an invoice. An attempt to collect payment will be made.deleteUnbilled charges will be deleted.
Applicable when the subscription has past due invoices. Specify this if you want to close the due invoices of the subscription. If specified as schedule_payment_collection/write_off, the due invoices of the subscription will be qualified for the selected operation after the remaining refundable credits and excess payments are applied.
Note: The payment collection attempt will be asynchronous. Not applicable when 'end_of_term' is true.
optional, enumerated string
optional, enumerated string
Possible values are
no_actionNo action is taken.schedule_payment_collectionAn automatic charge for the due amount of the past invoices will be attempted on the payment method available, if customer's auto-collection property is ‘ON’.write_offThe amount due in the invoices will be written-off. Credit notes created due to write-off will not be sent in the response.
Applicable when the customer has remaining refundable credits(issued against online payments). If specified as schedule_refund, the refund will be initiated for these credits after they are applied against the subscription’s past due invoices if any.
Note: The refunds initiated will be asynchronous. Not applicable when 'end_of_term' is true.
optional, enumerated string
optional, enumerated string
Possible values are
no_actionNo action is taken. .schedule_refundInitiates refund of the remaining credits.Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Resource object representing unbilled_charge.
optional
optional
Resource object representing credit_note.
optional
optional
Reactivate a subscription¶
This API is used to reactivate a cancelled subscription. You may also optionally specify a trial end date, to move the subscription to In Trial state. If trial end is not specified, the subscription will be activated and any applicable charges will be initiated.
Unless the billing cycle is specified, it will be set to plan's default billing cycle.
During an in-term reactivation++, unless the billing cycle is specified, the subscription's remaining billing cycles will be restored. If a trial end date is specified, then the plan's default billing cycle is used.
++What is an "in-term reactivation"?
An "in-term reactivation" happens when the billing term of the subscription is retained upon cancellation and reactivation is initiated within that term.
When is the ‘billing term’ retained for a cancelled subscription?
When dunning (payment failure retry settings) is configured with the last retry configured as
- cancel subscription and mark invoice as ‘Not Paid’, or
- cancel subscription and mark the invoice as ‘Voided’ and the case if any of the current term invoices is partially or fully paid, the invoice is not voided but instead Chargebee marks the invoices as ‘Not Paid’.
Note : In both cases, the billing term is retained and upon reactivation the subscription will be moved to active state (if the plan does not have a trial period) and no invoice will be generated. Ensure that you collect any unpaid invoices.
Example : A Subscription was billed from 1st to 31st of a month and it was canceled on the 20th due to one of the above cases (billing term is not reset). If the reactivation happens on 25th then it is considered an in-term reactivation.
Notes
Reactivation of a subscription in non_renewing state has been deprecated. To remove a scheduled cancellation of a non_renewing Subscription, use Remove Scheduled Cancellation API.
However, if you use reactivate API to remove scheduled cancellation for a non_renewing Subscription, then the status will be set to active and the billing cycle will be set to forever. If any value is passed for trial_end or billing cycle, an error will be thrown.
If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.
Additional Error Scenarios: If there is a need to create an immediate charge and the collection fails, an error will be thrown.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/reactivate \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/reactivate \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1528093938,
"current_term_end": 1530685938,
"next_billing_at": 1530685938,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1528093938,
"updated_at": 1528093941,
"has_scheduled_changes": false,
"resource_version": 1528093941000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093938,
"resource_version": 1528093938000,
"deleted": false,
"object": "customer",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
},
"invoice": {
"id": "82",
"customer_id": "8avVGOkx8U1MX",
"subscription_id": "8avVGOkx8U1MX",
"recurring": true,
"status": "paid",
"price_type": "tax_exclusive",
"date": 1528093938,
"due_date": 1528093938,
"net_term_days": 0,
"exchange_rate": 1.0,
"total": 900,
"amount_paid": 900,
"amount_adjusted": 0,
"write_off_amount": 0,
"credits_applied": 0,
"amount_due": 0,
"paid_at": 1528093939,
"updated_at": 1528093941,
"resource_version": 1528093941000,
"deleted": false,
"object": "invoice",
"first_invoice": false,
"amount_to_collect": 0,
"round_off_amount": 0,
"has_advance_charges": false,
"currency_code": "USD",
"base_currency_code": "USD",
"tax": 0,
"line_items": [
{
"id": "li_5SK0b8q3QtywRDX98",
"date_from": 1528093938,
"date_to": 1530685938,
"unit_amount": 900,
"quantity": 1,
"is_taxed": false,
"tax_amount": 0,
"object": "line_item",
"subscription_id": "8avVGOkx8U1MX",
"amount": 900,
"description": "sample plan",
"entity_type": "plan",
"entity_id": "basic",
"tax_exempt_reason": "tax_not_configured",
"discount_amount": 0,
"item_level_discount_amount": 0
},
{..}
],
"sub_total": 900,
"linked_payments": [
{
"txn_id": "txn_5SK0b8q3QtywREe99",
"applied_amount": 900,
"applied_at": 1528093941,
"txn_status": "success",
"txn_date": 1528093939,
"txn_amount": 900
},
{..}
],
"applied_credits": [],
"adjustment_credit_notes": [],
"issued_credit_notes": [],
"linked_orders": [],
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/reactivate
Input Parameters
The time at which the trial should end for this subscription.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
optional, integer, min=0
The time from which this subscription should be reactivated.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Applicable when charges are added during this operation. If specified as false, these charges will be added to unbilled charges. The default value for this parameter will be as per your site settings.
optional, boolean
optional, boolean
Applicable when calendar billing is enabled and a new active term gets started during this operation. Unless specified the configured default value will be used.
optional, enumerated string
optional, enumerated string
Possible values are
immediateSubscription period will be aligned with the configured billing date immediately.delayedSubscription period will be aligned with the configured billing date at a later date (subsequent renewals).Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Resource object representing unbilled_charge.
optional
optional
Add charge at term end¶
Adds a one time charge to the subscription which will be added to the invoice generated at the end of the current term. If there are any applicable coupons in the subscription, an appropriate discount will be applied.
To collect a charge immediately, use this API.
Notes
If any subscription changes happen before the end of the current term, these charges will be collected along with it.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/add_charge_at_term_end \
-u {site_api_key}: \
-d amount="1000" \
-d description="Support charge"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/add_charge_at_term_end \
-u {site_api_key}: \
-d amount="1000" \
-d description="Support charge"
Sample Response [ JSON ]
{"estimate": {
"created_at": 1528093941,
"object": "estimate",
"subscription_estimate": {
"id": "8avVGOkx8U1MX",
"status": "active",
"next_billing_at": 1530685938,
"object": "subscription_estimate",
"currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"invoice_estimate": {
"recurring": true,
"price_type": "tax_exclusive",
"sub_total": 1900,
"total": 1900,
"credits_applied": 0,
"amount_paid": 0,
"amount_due": 1900,
"object": "invoice_estimate",
"line_items": [
{
"id": "li_5SK0b8q3QtywRso9E",
"date_from": 1528093941,
"date_to": 1528093941,
"unit_amount": 1000,
"quantity": 1,
"is_taxed": false,
"tax_amount": 0,
"object": "line_item",
"subscription_id": "8avVGOkx8U1MX",
"amount": 1000,
"description": "Support charge",
"entity_type": "adhoc",
"discount_amount": 0,
"item_level_discount_amount": 0
},
{..}
],
"taxes": [],
"line_item_taxes": [],
"currency_code": "USD",
"line_item_discounts": []
}
}}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/add_charge_at_term_end
Input Parameters
Returns
Resource object representing estimate.
always returned
always returned
Charge addon at term end¶
Adds a "non-recurring addon" charge to a subscription which will be added to the invoice generated at the end of the current term. If there are any applicable coupons in the subscription, an appropriate discount will be applied.
To collect the charges for the non-recurring addon immediately, use this API.
Notes
If any subscription changes happen before the end of the current term, these charges will be collected along with it.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/charge_addon_at_term_end \
-u {site_api_key}: \
-d addon_id="ssl"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/charge_addon_at_term_end \
-u {site_api_key}: \
-d addon_id="ssl"
Sample Response [ JSON ]
{"estimate": {
"created_at": 1528093941,
"object": "estimate",
"subscription_estimate": {
"id": "8avVGOkx8U1MX",
"status": "active",
"next_billing_at": 1530685938,
"object": "subscription_estimate",
"currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"invoice_estimate": {
"recurring": true,
"price_type": "tax_exclusive",
"sub_total": 2395,
"total": 2395,
"credits_applied": 0,
"amount_paid": 0,
"amount_due": 2395,
"object": "invoice_estimate",
"line_items": [
{
"id": "li_5SK0b8q3QtywRv59I",
"date_from": 1528093941,
"date_to": 1528093941,
"unit_amount": 495,
"quantity": 1,
"is_taxed": false,
"tax_amount": 0,
"object": "line_item",
"subscription_id": "8avVGOkx8U1MX",
"amount": 495,
"description": "Support Charge",
"entity_type": "addon",
"entity_id": "support_charge",
"discount_amount": 0,
"item_level_discount_amount": 0
},
{..}
],
"taxes": [],
"line_item_taxes": [],
"currency_code": "USD",
"line_item_discounts": []
}
}}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/charge_addon_at_term_end
Input Parameters
The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1
optional, integer, min=1
Returns
Resource object representing estimate.
always returned
always returned
Charge Future Renewals¶
Use this API to create an advance invoice for the future renewals of a subscription. This operation will charge your customer if they have a payment method and Auto Collection is turned on. Any changes scheduled for the subscription will be considered while generating an advance invoice. Read More.
Notes
This operation is not supported for non-renewing and canceled subscriptions.
This operation is not supported if an advance invoice is already present. You could void/delete that invoice and try creating another advance invoice.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/charge_future_renewals \
-u {site_api_key}: \
-d terms_to_charge="1"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/charge_future_renewals \
-u {site_api_key}: \
-d terms_to_charge="1"
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1528093938,
"current_term_end": 1530685938,
"next_billing_at": 1533364338,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1528093938,
"updated_at": 1528093941,
"has_scheduled_changes": false,
"resource_version": 1528093941000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093942,
"resource_version": 1528093942000,
"deleted": false,
"object": "customer",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
},
"invoice": {
"id": "83",
"customer_id": "8avVGOkx8U1MX",
"subscription_id": "8avVGOkx8U1MX",
"recurring": true,
"status": "paid",
"price_type": "tax_exclusive",
"date": 1528093941,
"due_date": 1528093941,
"net_term_days": 0,
"exchange_rate": 1.0,
"total": 2395,
"amount_paid": 2395,
"amount_adjusted": 0,
"write_off_amount": 0,
"credits_applied": 0,
"amount_due": 0,
"paid_at": 1528093941,
"updated_at": 1528093942,
"resource_version": 1528093942000,
"deleted": false,
"object": "invoice",
"first_invoice": false,
"amount_to_collect": 0,
"round_off_amount": 0,
"has_advance_charges": true,
"currency_code": "USD",
"base_currency_code": "USD",
"tax": 0,
"line_items": [
{
"id": "li_5SK0b8q3QtywRso9E",
"date_from": 1528093941,
"date_to": 1528093941,
"unit_amount": 1000,
"quantity": 1,
"is_taxed": false,
"tax_amount": 0,
"object": "line_item",
"subscription_id": "8avVGOkx8U1MX",
"amount": 1000,
"description": "Support charge",
"entity_type": "adhoc",
"tax_exempt_reason": "tax_not_configured",
"discount_amount": 0,
"item_level_discount_amount": 0
},
{..}
],
"sub_total": 2395,
"linked_payments": [
{
"txn_id": "txn_5SK0b8q3QtywRyd9N",
"applied_amount": 2395,
"applied_at": 1528093942,
"txn_status": "success",
"txn_date": 1528093941,
"txn_amount": 2395
},
{..}
],
"applied_credits": [],
"adjustment_credit_notes": [],
"issued_credit_notes": [],
"linked_orders": [],
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/charge_future_renewals
Input Parameters
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
always returned
always returned
Import a subscription¶
This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/import_subscription \
-u {site_api_key}: \
-d customer[email]="john@user.com" \
-d customer[first_name]="John" \
-d customer[last_name]="Doe" \
-d customer[locale]="fr-CA" \
-d customer[phone]="+1-949-999-9999" \
-d plan_id="basic" \
-d status="active" \
-d current_term_end="1530383442" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/import_subscription \
-u {site_api_key}: \
-d customer[email]="john@user.com" \
-d customer[first_name]="John" \
-d customer[last_name]="Doe" \
-d customer[locale]="fr-CA" \
-d customer[phone]="+1-949-999-9999" \
-d plan_id="basic" \
-d status="active" \
-d current_term_end="1530383442" \
-d billing_address[first_name]="John" \
-d billing_address[last_name]="Doe" \
-d billing_address[line1]="PO Box 9999" \
-d billing_address[city]="Walnut" \
-d billing_address[state]="California" \
-d billing_address[zip]="91789" \
-d billing_address[country]="US"
Sample Response [ JSON ]
{
"subscription": {
"id": "5SK0b8q3QtywSKP9T",
"customer_id": "5SK0b8q3QtywSKP9T",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"current_term_start": 1528093943,
"current_term_end": 1530383442,
"next_billing_at": 1530383442,
"created_at": 1528093943,
"started_at": 1528093943,
"activated_at": 1528093943,
"updated_at": 1528093943,
"has_scheduled_changes": false,
"resource_version": 1528093943000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 0,
"mrr": 0
},
"customer": {
"id": "5SK0b8q3QtywSKP9T",
"first_name": "John",
"last_name": "Doe",
"email": "john@user.com",
"phone": "+1-949-999-9999",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1528093943,
"taxability": "taxable",
"updated_at": 1528093943,
"locale": "fr-CA",
"resource_version": 1528093943000,
"deleted": false,
"object": "customer",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"card_status": "no_card",
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/import_subscription
Input Parameters
Id for the new subscription. If not given, this will be auto-generated.
optional, string, max chars=50
optional, string, max chars=50
Allows you to specify a future date or a past date on which the subscription starts.Past dates can be entered in case the subscription has already started. Any past date entered must be within the current billing cycle/plan term. The subscription will start immediately if this parameter is not passed.
optional, timestamp(UTC) in seconds
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.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
optional, integer, min=0
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string
optional, enumerated string
Possible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. All payments must be recorded offline.
Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string
optional, list of string
Current state of the subscription.
required, enumerated string
required, enumerated string
Possible values are
futureThe Subscription is scheduled to start in a future date.in_trialThe subscription is in trial.activeThe subscription is in active state and will be charged at start of each term based on the recurring items(plan & addons etc.,).non_renewingThe subscription will be cancelled at end of the current term.pausedThe subscription is paused. No new recurring actions will be allowed, but any pending payments will be collected.cancelledThe subscription has been cancelled. No new recurring actions will take place, but any pending payments will be collected.
End of the current billing term. Subscription is renewed immediately after this. If not given, this will be calculated based on plan billing cycle.
optional, timestamp(UTC) in seconds
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 'trial' state when it starts.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Time at which subscription was canceled or is set to be canceled.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Time at which the subscription got started. Will be null for 'future' subscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Set as TRUE if you want Chargebee to create an invoice for the subscription.
- Invoice will be created for subscriptions with ACTIVE or NON_RENEWING status only.
- Invoice will be created for the period mentioned in the current_term_start and current_term_end attributes.
- Invoice will not be generated if subscription amount is zero dollars (for that period) and 'Hide Zero Value Line Items' option is enabled in Settings.
- Invoice will not be generated if the given quantity is not greater than free quantity (If free quantity is configured in the plan/addon).
optional, boolean, default=false
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
optional, jsonobject
customer
Parameters for customer
pass parameters as customer[<param name>]
pass parameters as customer[<param name>]
Id for the new customer. If not given, this will be same as the subscription id.
optional, string, max chars=50
optional, string, max chars=50
Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70
optional, string, max chars=70
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable
optional, enumerated string, default=taxable
Possible values are
taxableCustomer is taxable.exemptCustomer is exempted from tax.
Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.
optional, string, max chars=50
optional, string, max chars=50
The exemption category of the customer, for the USA and Canada. applicable if you use Chargebee's Avalara integration.
optional, enumerated string
optional, enumerated string
Possible values are
aFederal government (United States).bState government (United States).cTribe/Status Indian/Indian Band (both).dForeign diplomat (United States).eCharitable or benevolent org (United States).fReligious or educational org (United States).gResale (United States).hCommercial agricultural production (United States).iIndustrial production/manufacturer (United States).jDirect pay permit (United States).kDirect mail (United States).lOther (United States).nLocal government (United States).pCommercial aquaculture (Canada).qCommercial Fishery (Canada).rNon-resident (Canada).med1US Medical Device Excise Tax with exempt sales tax.med2US Medical Device Excise Tax with taxable sales tax.
Show all values[+]
Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable only for Avalara.
optional, string, max chars=100
optional, string, max chars=100
The number of days within which the customer has to make payment for the invoice.
optional, integer, default=0
optional, integer, default=0
Whether payments needs to be collected automatically for this customer.
optional, enumerated string, default=on
optional, enumerated string, default=on
Possible values are
onWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.offAutomatic collection of charges will not be made. All payments must be recorded offline.
Whether the customer can pay via Direct Debit.
optional, boolean, default=false
optional, boolean, default=false
card
Parameters for card
pass parameters as card[<param name>]
pass parameters as card[<param name>]
The gateway account in which this payment source is stored.
optional, string, max chars=50
optional, string, max chars=50
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500
required if card provided, string, max chars=1500
The card verification value. If you are using Braintree.js, you can specify the Braintree encrypted cvv here.
optional, string, max chars=520
optional, string, max chars=520
Address line 1, as available in card billing address.
optional, string, max chars=150
optional, string, max chars=150
Address line 2, as available in card billing address.
optional, string, max chars=150
optional, string, max chars=150
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
optional, string, max chars=20
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
pass parameters as payment_method[<param name>]
The type of payment method. For more details refer
Update payment method for a customer API under Customer resource.
optional, enumerated string
optional, enumerated string
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.
Show all values[+]
The gateway account in which this payment source is stored.
optional, string, max chars=50
optional, string, max chars=50
The reference id. In the case of Amazon and PayPal this will be the
billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=50
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=50
2-letter (alpha2) ISO country code. Indicates your customer's payment method country of issuance. Applicable for PayPal via Braintree.
optional, string, max chars=50
optional, string, max chars=50
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
pass parameters as billing_address[<param name>]
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
The address verification status.
optional, enumerated string, default=not_validated
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
pass parameters as shipping_address[<param name>]
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
The address verification status.
optional, enumerated string, default=not_validated
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.transaction
Parameters for transaction
pass parameters as transaction[<param name>]
pass parameters as transaction[<param name>]
The payment transaction amount. This param should be passed only if the invoice is created for current term.
optional, in cents, min=1
optional, in cents, min=1
The Payment Method of this transaction. This param should be passed only if the invoice is created for current term.
optional, enumerated string, default=card
optional, enumerated string, default=card
Possible values are
cashCash.checkCheck.bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
The reference number for this transaction. e.g check number in case of 'check' payment. This param should be passed only if the invoice is created for current term.
optional, string, max chars=100
optional, string, max chars=100
Indicates when this transaction occurred. This param should be passed only if the invoice is created for current term.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
pass parameters as addons[<param name>][<idx:0..n>]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
optional, integer, default=1, min=1
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
optional, in cents, min=0
Number of billing cycles the addon will be charged for.
optional, integer, min=1
optional, integer, min=1
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>]
pass parameters as event_based_addons[<param name>][<idx:0..n>]
A unique 'id' used to identify the addon.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
optional, integer, min=1
Amount that will override the Addon's default price.
optional, in cents, min=0
optional, in cents, min=0
Event on which this addon will be charged.
optional, enumerated string
optional, enumerated string
Possible values are
subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true
optional, boolean, default=true
charged_event_based_addons
Parameters for charged_event_based_addons. Multiple charged_event_based_addons can be passed by specifying unique indices.
pass parameters as charged_event_based_addons[<param name>][<idx:0..n>]
pass parameters as charged_event_based_addons[<param name>][<idx:0..n>]
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Import subscription for customer¶
This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.
Sample Request
curl https://{site}.chargebee.com/api/v2/customers/8avVGOkx8U1MX/import_subscription \
-u {site_api_key}: \
-d plan_id="basic" \
-d status="active" \
-d current_term_end="1530383442"
copy
curl https://{site}.chargebee.com/api/v2/customers/8avVGOkx8U1MX/import_subscription \
-u {site_api_key}: \
-d plan_id="basic" \
-d status="active" \
-d current_term_end="1530383442"
Sample Response [ JSON ]
{
"subscription": {
"id": "5SK0b8q3QtywSRg9X",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"current_term_start": 1528093943,
"current_term_end": 1530383442,
"next_billing_at": 1530383442,
"created_at": 1528093943,
"started_at": 1528093943,
"activated_at": 1528093943,
"updated_at": 1528093943,
"has_scheduled_changes": false,
"resource_version": 1528093943000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 0,
"mrr": 0
},
"customer": {
"id": "8avVGOkx8U1MX",
"first_name": "Benjamin",
"last_name": "Ross",
"email": "Benjamin@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1412101843,
"taxability": "taxable",
"updated_at": 1528093942,
"resource_version": 1528093942000,
"deleted": false,
"object": "customer",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "billing_address"
},
"card_status": "valid",
"contacts": [
{
"id": "d334f4g45",
"first_name": "aasca",
"last_name": "asas",
"email": "sss@wss.asc",
"label": "ascasc",
"enabled": true,
"send_account_email": true,
"send_billing_email": false,
"object": "contact"
},
{..}
],
"primary_payment_source_id": "pm_5SK0b8q3QtywPvB8O",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "cus_CzAZAU4W3aghnt/card_1CZCEiJv9j0DyntJPjirexdQ",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "stripe",
"gateway_account_id": "gw_5SK0b8vNQtyvEg38O",
"first_name": "Richard",
"last_name": "Fox",
"iin": "401288",
"last4": "1881",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 10,
"expiry_year": 2022,
"issuing_country": "CA",
"object": "card",
"masked_number": "************1881",
"customer_id": "8avVGOkx8U1MX",
"payment_source_id": "pm_5SK0b8q3QtywPvB8O"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/import_subscription
Input Parameters
Id for the new subscription. If not given, this will be auto-generated.
optional, string, max chars=50
optional, string, max chars=50
Allows you to specify a future date or a past date on which the subscription starts.Past dates can be entered in case the subscription has already started. Any past date entered must be within the current billing cycle/plan term. The subscription will start immediately if this parameter is not passed.
optional, timestamp(UTC) in seconds
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.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
optional, integer, min=0
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string
optional, enumerated string
Possible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. All payments must be recorded offline.
Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string
optional, list of string
Unique identifier of the payment source to be attached to this subscription.
optional, string, max chars=40
optional, string, max chars=40
Current state of the subscription.
required, enumerated string
required, enumerated string
Possible values are
futureThe Subscription is scheduled to start in a future date.in_trialThe subscription is in trial.activeThe subscription is in active state and will be charged at start of each term based on the recurring items(plan & addons etc.,).non_renewingThe subscription will be cancelled at end of the current term.pausedThe subscription is paused. No new recurring actions will be allowed, but any pending payments will be collected.cancelledThe subscription has been cancelled. No new recurring actions will take place, but any pending payments will be collected.
End of the current billing term. Subscription is renewed immediately after this. If not given, this will be calculated based on plan billing cycle.
optional, timestamp(UTC) in seconds
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 'trial' state when it starts.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Time at which subscription was canceled or is set to be canceled.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Time at which the subscription got started. Will be null for 'future' subscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Set as TRUE if you want Chargebee to create an invoice for the subscription.
- Invoice will be created for subscriptions with ACTIVE or NON_RENEWING status only.
- Invoice will be created for the period mentioned in the current_term_start and current_term_end attributes.
- Invoice will not be generated if subscription amount is zero dollars (for that period) and 'Hide Zero Value Line Items' option is enabled in Settings.
- Invoice will not be generated if the given quantity is not greater than free quantity (If free quantity is configured in the plan/addon).
optional, boolean, default=false
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
optional, jsonobject
transaction
Parameters for transaction
pass parameters as transaction[<param name>]
pass parameters as transaction[<param name>]
The payment transaction amount. This param should be passed only if the invoice is created for current term.
optional, in cents, min=1
optional, in cents, min=1
The Payment Method of this transaction. This param should be passed only if the invoice is created for current term.
optional, enumerated string, default=card
optional, enumerated string, default=card
Possible values are
cashCash.checkCheck.bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
The reference number for this transaction. e.g check number in case of 'check' payment. This param should be passed only if the invoice is created for current term.
optional, string, max chars=100
optional, string, max chars=100
Indicates when this transaction occurred. This param should be passed only if the invoice is created for current term.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
pass parameters as shipping_address[<param name>]
The ISO 3166-2 state/province code without the country prefix.
Currently supported for USA, Canada and India.
For instance, for Arizona (USA), set the state_code as AZ (not US-AZ).
or, for Tamil Nadu (India), set the state_code as TN (not IN-TN).
or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
optional, string, max chars=50
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
optional, string, max chars=50
The address verification status.
optional, enumerated string, default=not_validated
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
pass parameters as addons[<param name>][<idx:0..n>]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
optional, integer, default=1, min=1
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
optional, in cents, min=0
Number of billing cycles the addon will be charged for.
optional, integer, min=1
optional, integer, min=1
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>]
pass parameters as event_based_addons[<param name>][<idx:0..n>]
A unique 'id' used to identify the addon.
optional, string, max chars=100
optional, string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
optional, integer, min=1
Amount that will override the Addon's default price.
optional, in cents, min=0
optional, in cents, min=0
Event on which this addon will be charged.
optional, enumerated string
optional, enumerated string
Possible values are
subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true
optional, boolean, default=true
charged_event_based_addons
Parameters for charged_event_based_addons. Multiple charged_event_based_addons can be passed by specifying unique indices.
pass parameters as charged_event_based_addons[<param name>][<idx:0..n>]
pass parameters as charged_event_based_addons[<param name>][<idx:0..n>]
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Override Billing Profile¶
Assigns the payment source and sets auto collection state for the subscription.
Notes
When you don't pass any input param for this API, payment source and auto collection for the subscription will be the same as the customer's default settings.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/override_billing_profile \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/override_billing_profile \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "8avVGOkx8U1MX",
"customer_id": "8avVGOkx8U1MX",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"trial_start": 1412101842,
"trial_end": 1414780242,
"current_term_start": 1528093938,
"current_term_end": 1530685938,
"next_billing_at": 1533364338,
"created_at": 1412101842,
"started_at": 1412101842,
"activated_at": 1528093938,
"updated_at": 1528093943,
"has_scheduled_changes": false,
"payment_source_id": "pm_XpbBroXQF5m78F6",
"resource_version": 1528093943000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 3,
"due_since": 1394532759,
"total_dues": 6700,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD",
"shipping_address": {
"first_name": "Benjamin",
"last_name": "Ross",
"line1": "PO Box 9999",
"city": "Walnut",
"state_code": "CA",
"state": "California",
"country": "US",
"zip": "91789",
"validation_status": "not_validated",
"object": "shipping_address"
}
},
"payment_source": {
"id": "pm_XpbBroXQF5m78F6",
"deleted": false,
"object": "payment_source",
"customer_id": "8avVGOkx8U1MX",
"type": "card",
"reference_id": "tok_5SK0b8vNQtyv2JdG",
"status": "valid",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"card": {
"iin": "385200",
"last4": "3237",
"funding_type": "not_known",
"expiry_month": 12,
"expiry_year": 2022,
"masked_number": "************3237",
"object": "card",
"brand": "diners_club"
}
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/override_billing_profile
Input Parameters
Unique identifier of the payment source to be attached to this subscription.
optional, string, max chars=40
optional, string, max chars=40
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string
optional, enumerated string
Possible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. All payments must be recorded offline.Returns
Resource object representing subscription.
always returned
always returned
Resource object representing payment_source.
optional
optional
Delete a subscription¶
Deletes the subscription resource.
Notes
This operation is irreversible - all data related to the subscription, such as invoices, transactions, and reports, will be deleted.
Note: This operation schedules the subscription resource for deletion. It will be deleted in a few minutes.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/5cDfREwp3I5lJ/delete \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/5cDfREwp3I5lJ/delete \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"subscription": {
"id": "5cDfREwp3I5lJ",
"customer_id": "5cDfREwp3I5lJ",
"plan_id": "basic",
"plan_quantity": 1,
"plan_unit_price": 900,
"billing_period": 1,
"billing_period_unit": "month",
"plan_free_quantity": 0,
"status": "active",
"trial_start": 1528093635,
"trial_end": 1527928035,
"current_term_start": 1527928035,
"current_term_end": 1530520035,
"next_billing_at": 1530520035,
"created_at": 1528093635,
"started_at": 1528093635,
"activated_at": 1527928035,
"updated_at": 1528093636,
"has_scheduled_changes": false,
"resource_version": 1528093636000,
"deleted": false,
"object": "subscription",
"currency_code": "USD",
"due_invoices_count": 1,
"due_since": 1527928035,
"total_dues": 900,
"mrr": 900,
"exchange_rate": 1.0,
"base_currency_code": "USD"
},
"customer": {
"id": "5cDfREwp3I5lJ",
"first_name": "David",
"last_name": "White",
"email": "David@test.com",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1528093635,
"taxability": "taxable",
"updated_at": 1527920835,
"resource_version": 1527920835000,
"deleted": false,
"object": "customer",
"card_status": "valid",
"primary_payment_source_id": "pm_5SK0b8vNQtyvANp7N",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "tok_5SK0b8vNQtyvANf7M",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"status": "valid"
},
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "USD"
},
"card": {
"status": "valid",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"iin": "400551",
"last4": "0004",
"card_type": "visa",
"funding_type": "not_known",
"expiry_month": 12,
"expiry_year": 2022,
"object": "card",
"masked_number": "************0004",
"customer_id": "5cDfREwp3I5lJ",
"payment_source_id": "pm_5SK0b8vNQtyvANp7N"
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/delete
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Pause a subscription¶
Pausing a subscription will move the subscription from its current state to Paused state, and will stop all recurring actions.
You could schedule the pause by passing specific_date/end_of_term parameter in pause_option. If scheduled, the subscription will not be paused until the specific_date/end_of_term is reached.
UNBILLED CHARGES
Any unbilled charges present in the subscription can be invoiced by specifying invoice or no_action. If invoice is chosen, automatic charge will be attempted on the payment method available if the customer has enabled auto-collection. If payment collection fails or when auto-collection is not enabled, the invoice will be closed as unpaid.
If no_action is chosen, charges will be added to the resumption invoice.
INVOICE DUNNING HANDLING
If invoice is in the dunning cycle, invoice_dunning_handing allows you to stop or continue dunning.
Note:
- Applicable only for active/non-renewing subscriptions.
- For non-renewing subscriptions, pause_date and resume_date should be before the cancellation date. If paused indefinitely, the subscription will be cancelled on the cancelled_at date.
- Advance charges, if any, will be refunded as credits.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/pause \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/pause \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"card": {
"card_type": "visa",
"customer_id": "5SK0b8vNQtyvbqG8o",
"expiry_month": 1,
"expiry_year": 2032,
"funding_type": "credit",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"iin": "411111",
"last4": "1111",
"masked_number": "************1111",
"object": "card",
"payment_source_id": "pm_5SK0b8vNQtyvbqz8q",
"status": "valid"
},
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1528093741,
"deleted": false,
"email": "joe@user.com",
"excess_payments": 0,
"first_name": "Joe",
"id": "5SK0b8vNQtyvbqG8o",
"last_name": "D",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"object": "payment_method",
"reference_id": "tok_5SK0b8vNQtyvbqt8p",
"status": "valid",
"type": "card"
},
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm_5SK0b8vNQtyvbqz8q",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1528093742000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1528093742
},
"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 0,
"amount_paid": 1000,
"amount_to_collect": 0,
"applied_credits": [],
"base_currency_code": "USD",
"billing_address": {
"first_name": "Joe",
"last_name": "D",
"object": "billing_address",
"validation_status": "not_validated"
},
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "5SK0b8vNQtyvbqG8o",
"date": 1528093741,
"deleted": false,
"due_date": 1528093741,
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "51",
"issued_credit_notes": [],
"line_items": [
{
"amount": 1000,
"date_from": 1528093741,
"date_to": 1528093741,
"description": "unbilled_charges",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li_5SK0b8q3Qtyvbx23U",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"quantity": 1,
"subscription_id": "5SK0b8vNQtyvbqG8o",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 1000
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 1000,
"applied_at": 1528093742,
"txn_amount": 1000,
"txn_date": 1528093742,
"txn_id": "txn_5SK0b8q3Qtyvc4I3Z",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 1000,
"object": "invoice",
"paid_at": 1528093742,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1528093742000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 1000,
"subscription_id": "5SK0b8vNQtyvbqG8o",
"tax": 0,
"total": 1000,
"updated_at": 1528093742,
"write_off_amount": 0
},
"subscription": {
"activated_at": 1528093741,
"addons": [
{
"id": "data_usage",
"object": "addon",
"quantity": 2,
"unit_price": 95
},
{..}
],
"billing_period": 1,
"billing_period_unit": "month",
"created_at": 1528093741,
"currency_code": "USD",
"current_term_end": 1530685741,
"current_term_start": 1528093741,
"customer_id": "5SK0b8vNQtyvbqG8o",
"deleted": false,
"due_invoices_count": 0,
"has_scheduled_changes": false,
"id": "5SK0b8vNQtyvbqG8o",
"mrr": 0,
"object": "subscription",
"pause_date": 1528093741,
"plan_free_quantity": 0,
"plan_id": "no_trial",
"plan_quantity": 3,
"plan_unit_price": 1000,
"resource_version": 1528093742000,
"resume_date": 1530685741,
"started_at": 1528093741,
"status": "paused",
"updated_at": 1528093742
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/pause
Input Parameters
List of options to pause the subscription.
optional, enumerated string
optional, enumerated string
Possible values are
immediatelyPause immediately.end_of_termPause at the end of current term.specific_datePause on a specific date.
Date on which the subscription will be paused. Applicable when 'specific_date' option is chosen in the pause_option field.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Applicable when unbilled charges are present for the subscription and pause_option is set as 'immediately'. Note: On the invoice raised, an automatic charge will be attempted on the payment method available, if customer's auto-collection property is ‘ON’.
optional, enumerated string
optional, enumerated string
Possible values are
no_actionRetain as unbilled.invoiceInvoice charges.
Handles dunning for invoices already in the dunning cycle, when subscription is paused. Applicable when pause_option is set as 'immediately'.
optional, enumerated string
optional, enumerated string
Possible values are
continueContinue dunning.stopStop dunning.Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Resource object representing unbilled_charge.
optional
optional
Resource object representing credit_note.
optional
optional
Resume a subscription¶
This API is used to resume a paused subscription. On resumption the subscription will be activated and any applicable charges will be initiated.
You could schedule the resumption by passing specific_date parameter in resume_option. If scheduled, the subscription will be resumed on the specific_date and moved to Active state.
For in-term resumption ++, unless there are scheduled changes, unbilled charges will not be charged.
++What is an "in-term resumption"?
An “in-term resumption” is when the pause and resumption happens within the billing term of the subscription.
Example : A subscription was billed from 1st to 31st of a month. It was paused on the 20th and resumed before 31st. This is an in-term resumption.
UNPAID INVOICES
Specifying unpaid_invoices allows you to close invoices of the subscription which have amounts due. The invoices are chosen for payment collection after applying the available credits and excess payments.
If specified as schedule_payment_collection, payment collection for the amount due of past invoices will be attempted. The payment method available will be charged if auto-collection is enabled for the customer, and appropriate payment collection(payment succeeded or payment failed) events will be triggered. If the payment collection fails, no further retries will be made on the invoices.
Note: If the invoices of the subscription are consolidated, and any of the subscriptions in the consolidated invoice are cancelled, these invoices will not be selected for collection.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/resume \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/resume \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"card": {
"card_type": "visa",
"customer_id": "5SK0b8vNQtyvbqG8o",
"expiry_month": 1,
"expiry_year": 2032,
"funding_type": "credit",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"iin": "411111",
"last4": "1111",
"masked_number": "************1111",
"object": "card",
"payment_source_id": "pm_5SK0b8vNQtyvbqz8q",
"status": "valid"
},
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1528093741,
"deleted": false,
"email": "joe@user.com",
"excess_payments": 0,
"first_name": "Joe",
"id": "5SK0b8vNQtyvbqG8o",
"last_name": "D",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"object": "payment_method",
"reference_id": "tok_5SK0b8vNQtyvbqt8p",
"status": "valid",
"type": "card"
},
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm_5SK0b8vNQtyvbqz8q",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1528093742000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1528093742
},
"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 0,
"amount_paid": 3190,
"amount_to_collect": 0,
"applied_credits": [],
"base_currency_code": "USD",
"billing_address": {
"first_name": "Joe",
"last_name": "D",
"object": "billing_address",
"validation_status": "not_validated"
},
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "5SK0b8vNQtyvbqG8o",
"date": 1528093742,
"deleted": false,
"due_date": 1528093742,
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "52",
"issued_credit_notes": [],
"line_items": [
{
"amount": 3000,
"date_from": 1528093742,
"date_to": 1530685742,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li_5SK0b8q3QtyvcD53h",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"quantity": 3,
"subscription_id": "5SK0b8vNQtyvbqG8o",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 1000
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 3190,
"applied_at": 1528093742,
"txn_amount": 3190,
"txn_date": 1528093742,
"txn_id": "txn_5SK0b8q3QtyvcE63j",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"object": "invoice",
"paid_at": 1528093742,
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1528093742000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 3190,
"subscription_id": "5SK0b8vNQtyvbqG8o",
"tax": 0,
"total": 3190,
"updated_at": 1528093742,
"write_off_amount": 0
},
"subscription": {
"activated_at": 1528093741,
"addons": [
{
"id": "data_usage",
"object": "addon",
"quantity": 2,
"unit_price": 95
},
{..}
],
"billing_period": 1,
"billing_period_unit": "month",
"created_at": 1528093741,
"currency_code": "USD",
"current_term_end": 1530685742,
"current_term_start": 1528093742,
"customer_id": "5SK0b8vNQtyvbqG8o",
"deleted": false,
"due_invoices_count": 0,
"has_scheduled_changes": false,
"id": "5SK0b8vNQtyvbqG8o",
"mrr": 0,
"next_billing_at": 1530685742,
"object": "subscription",
"plan_free_quantity": 0,
"plan_id": "no_trial",
"plan_quantity": 3,
"plan_unit_price": 1000,
"resource_version": 1528093742000,
"started_at": 1528093741,
"status": "active",
"updated_at": 1528093742
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/resume
Input Parameters
List of options to resume the subscription.
optional, enumerated string
optional, enumerated string
Possible values are
immediatelyResume immediately.specific_dateResume on a specific date.
Date on which the subscription will be resumed. Applicable when resume_option is set as 'specific_date'.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds
Applicable when charges get added during this operation and resume_option is set as 'immediately'. Allows to raise invoice immediately or add them to unbilled charges.
optional, enumerated string
optional, enumerated string
Possible values are
invoice_immediatelyInvoice immediately.add_to_unbilled_chargesAdd to unbilled charges.
Applicable when the subscription has past due invoices and resume_option is set as 'immediately'. Allows to collect past due invoices or retain them as unpaid. If 'schedule_payment_collection' option is chosen in this field, remaining refundable credits and excess payments are applied.
Note: The payment collection attempt will be asynchronous.
optional, enumerated string
optional, enumerated string
Possible values are
no_actionRetain as unpaid.schedule_payment_collectionCollect payment.Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Resource object representing invoice.
optional
optional
Resource object representing unbilled_charge.
optional
optional
Remove scheduled pause¶
If the subscription is in Active or Non Renewing state and is also scheduled to pause at the end_of_term/specific_date, this API can be used to remove the scheduled pause.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_scheduled_pause \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_scheduled_pause \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"card": {
"card_type": "visa",
"customer_id": "5SK0b8vNQtyvbqG8o",
"expiry_month": 1,
"expiry_year": 2032,
"funding_type": "credit",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"iin": "411111",
"last4": "1111",
"masked_number": "************1111",
"object": "card",
"payment_source_id": "pm_5SK0b8vNQtyvbqz8q",
"status": "valid"
},
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1528093741,
"deleted": false,
"email": "joe@user.com",
"excess_payments": 0,
"first_name": "Joe",
"id": "5SK0b8vNQtyvbqG8o",
"last_name": "D",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"object": "payment_method",
"reference_id": "tok_5SK0b8vNQtyvbqt8p",
"status": "valid",
"type": "card"
},
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm_5SK0b8vNQtyvbqz8q",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1528093742000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1528093742
},
"subscription": {
"activated_at": 1528093741,
"addons": [
{
"id": "data_usage",
"object": "addon",
"quantity": 2,
"unit_price": 95
},
{..}
],
"billing_period": 1,
"billing_period_unit": "month",
"created_at": 1528093741,
"currency_code": "USD",
"current_term_end": 1530685742,
"current_term_start": 1528093742,
"customer_id": "5SK0b8vNQtyvbqG8o",
"deleted": false,
"due_invoices_count": 0,
"has_scheduled_changes": false,
"id": "5SK0b8vNQtyvbqG8o",
"mrr": 0,
"next_billing_at": 1530685742,
"object": "subscription",
"plan_free_quantity": 0,
"plan_id": "no_trial",
"plan_quantity": 3,
"plan_unit_price": 1000,
"resource_version": 1528093743000,
"started_at": 1528093741,
"status": "active",
"updated_at": 1528093743
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_pause
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional
Remove scheduled resumption¶
If the subscription is in Paused state and is scheduled to resume on a specific_date, this API can be used to remove the scheduled resumption. When the scheduled resumption is removed, the subscription will remain Paused.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_scheduled_resumption \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/8avVGOkx8U1MX/remove_scheduled_resumption \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
{
"card": {
"card_type": "visa",
"customer_id": "5SK0b8vNQtyvbqG8o",
"expiry_month": 1,
"expiry_year": 2032,
"funding_type": "credit",
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"iin": "411111",
"last4": "1111",
"masked_number": "************1111",
"object": "card",
"payment_source_id": "pm_5SK0b8vNQtyvbqz8q",
"status": "valid"
},
"customer": {
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "valid",
"created_at": 1528093741,
"deleted": false,
"email": "joe@user.com",
"excess_payments": 0,
"first_name": "Joe",
"id": "5SK0b8vNQtyvbqG8o",
"last_name": "D",
"net_term_days": 0,
"object": "customer",
"payment_method": {
"gateway": "chargebee",
"gateway_account_id": "gw_5SK0b8vNQtyuzY32",
"object": "payment_method",
"reference_id": "tok_5SK0b8vNQtyvbqt8p",
"status": "valid",
"type": "card"
},
"preferred_currency_code": "USD",
"primary_payment_source_id": "pm_5SK0b8vNQtyvbqz8q",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1528093742000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1528093742
},
"subscription": {
"activated_at": 1528093741,
"addons": [
{
"id": "data_usage",
"object": "addon",
"quantity": 2,
"unit_price": 95
},
{..}
],
"billing_period": 1,
"billing_period_unit": "month",
"created_at": 1528093741,
"currency_code": "USD",
"current_term_end": 1530685742,
"current_term_start": 1528093742,
"customer_id": "5SK0b8vNQtyvbqG8o",
"deleted": false,
"due_invoices_count": 0,
"has_scheduled_changes": false,
"id": "5SK0b8vNQtyvbqG8o",
"mrr": 0,
"next_billing_at": 1530685743,
"object": "subscription",
"pause_date": 1528093743,
"plan_free_quantity": 0,
"plan_id": "no_trial",
"plan_quantity": 3,
"plan_unit_price": 1000,
"resource_version": 1528093743000,
"started_at": 1528093741,
"status": "paused",
"updated_at": 1528093743
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_resumption
Returns
Resource object representing subscription.
always returned
always returned
Resource object representing customer.
always returned
always returned
Resource object representing card.
optional
optional