You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

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

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

Sample subscription [ JSON ]

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

Model Class

com.chargebee.models.Subscription
id
A unique identifier to identify the subscription. You will use this to perform all operations on this subscription.
string, max chars=50
planId
Identifier of the plan for this subscription.
string, max chars=100
planQuantity
Represents the plan quantity for this subscription.
integer, default=1, min=1
status
Current state of the subscription.
enumerated string
Possible values are
FUTUREThe Subscription is scheduled to start in a future date.IN_TRIALThe subscription is in trial.ACTIVEThe subscription is in active state and will be charged at start of each term based on the recurring items(plan & addons etc.,).NON_RENEWINGThe subscription will be cancelled at end of the current term.CANCELLEDThe subscription has been cancelled. No new recurring actions will take place, but any pending payments will be collected.
startDate
Applicable only for 'future' subscriptions. The scheduled start time of the 'future' subscription.
optional, timestamp(UTC) in seconds
trialStart
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
trialEnd
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
currentTermStart
Start of the current billing term.
optional, timestamp(UTC) in seconds
currentTermEnd
End of the current billing term. Subscription is renewed immediately after this.
optional, timestamp(UTC) in seconds
remainingBillingCycles
The number of billing cycles this subscription will run.
optional, integer, min=0
poNumber
Purchase Order Number for this subscription.
optional, string, max chars=100
createdAt
Subscription created time.
optional, timestamp(UTC) in seconds
startedAt
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
activatedAt
Time at which the subscription moved from in_trial state to active state.
optional, timestamp(UTC) in seconds
cancelledAt
Time at which subscription was cancelled or is set to be cancelled.
optional, timestamp(UTC) in seconds
cancelReason
Possible reason the subscription might be cancelled.
optional, enumerated string
Possible values are
NOT_PAIDNot Paid.NO_CARDNo Card.FRAUD_REVIEW_FAILEDFraud Review Failed.NON_COMPLIANT_EU_CUSTOMERNon Compliant EU Customer.
affiliateToken
A unique tracking token.
optional, string, max chars=250
createdFromIp
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
hasScheduledChanges
If true, there are subscription changes scheduled on next renewal.
boolean, default=false
dueInvoicesCount
Total number of invoices that are due for payment.
Note: Not supported if consolidated invoicing is enabled or when the subscription is for the customer who is in hierarchy and the parent of this customer owns and pays for the invoices of the subscription.
optional, integer
dueSince
Time since this subscription has unpaid invoices.
Note: Not supported if consolidated invoicing is enabled or when the subscription is for the customer who is in hierarchy and the parent of this customer owns and pays for the invoices of the subscription.
optional, timestamp(UTC) in seconds
totalDues
Total invoice due amount for this subscription.
Note: Not supported if consolidated invoicing is enabled or when the subscription is for the customer who is in hierarchy and the parent of this customer owns and pays for the invoices of the subscription.
optional, in cents, min=0
invoiceNotes
Invoice Notes for this resource. Read More.
optional, string, max chars=2000
metaData
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
List of addons for this subscription with quantity(if applicable).
optional, list of addon
Addon attributes
id
Identifier of the addon. Multiple addons can be passed.
string, max chars=100
quantity
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
List of coupons for this subscription.
optional, list of coupon
Coupon attributes
couponId
Used to uniquely identify the coupon.
string, max chars=50
applyTill
The date till the coupon is to be applied. Applicable for "limited months" coupons.
optional, timestamp(UTC) in seconds
appliedCount
Number of times this coupon has been applied for this subscription.
integer, default=0
couponCode
The coupon code used to redeem the coupon. Will be present only when associated code for a coupon is used.
optional, string, max chars=50
shippingAddress
Show attributes[+]
Shipping address for the subscription.
optional, shipping_address
Shipping addres attributes
firstName
First name.
optional, string, max chars=150
lastName
Last name.
optional, string, max chars=150
email
Email.
optional, string, max chars=70
company
Company name.
optional, string, max chars=250
phone
Phone number.
optional, string, max chars=50
line1
Address line 1.
optional, string, max chars=180
line2
Address line 2.
optional, string, max chars=150
line3
Address line 3.
optional, string, max chars=150
city
City.
optional, string, max chars=50
stateCode
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
state
The state/province name.
optional, string, max chars=50
country
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
zip
Zip or Postal code.
optional, string, max chars=20
This operation supports 3DS verification flow. To acheive the same, create the Payment Intent and pass it as input parameter to this API.

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

Future Subscriptions

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

Trial Period

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

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

Invoice

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

Card details

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

  • If you are using Stripe gateway, you can use Stripe.js with your checkout form. Please refer this tutorial for more details.
  • If you are using Braintree gateway, you can use Braintree.js with your checkout form. Please refer this tutorial for more details.
You can also use our Hosted Pages based integration.

Billing Address

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

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

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

Shipping Address

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

Related Tutorials

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    
/* 
    creates a subscription with customer information and billing details.
*/

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.create()
	.planId("no_trial")
	.customerFirstName("John")
	.customerLastName("Doe")
	.customerEmail("john@user.com")
	.billingAddressFirstName("John")
	.billingAddressLastName("Doe")
	.billingAddressLine1("PO Box 9999")
	.billingAddressCity("Walnut")
	.billingAddressState("California")
	.billingAddressZip("91789")
	.billingAddressCountry("US")
	.customerAutoCollection(AutoCollection.OFF)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();
    System.out.println(result);
  }
}
copy full code
copy snippet
/* 
    creates a subscription with customer information and billing details.
*/

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.create()
	.planId("no_trial")
	.customerFirstName("John")
	.customerLastName("Doe")
	.customerEmail("john@user.com")
	.billingAddressFirstName("John")
	.billingAddressLastName("Doe")
	.billingAddressLine1("PO Box 9999")
	.billingAddressCity("Walnut")
	.billingAddressState("California")
	.billingAddressZip("91789")
	.billingAddressCountry("US")
	.customerAutoCollection(AutoCollection.OFF)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();

Sample Result [ JSON ]

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

Method

Subscription.create()
id(val)
Id for the new subscription. If not given, this will be auto-generated.
optional, string, max chars=50
planId(val)
Identifier of the plan for this subscription.
required, string, max chars=100
planQuantity(val)
Plan quantity for this subscription.
optional, integer, default=1, min=1
startDate(val)
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
trialEnd(val)
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
billingCycles(val)
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
coupon(val)

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

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

optional, string, max chars=50
poNumber(val)
Purchase Order Number for this subscription.
optional, string, max chars=100
affiliateToken(val)
A unique tracking token.
optional, string, max chars=250
createdFromIp(val)
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
invoiceNotes(val)
Invoice Notes for this resource. Read More.
optional, string, max chars=2000
metaData(val)
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
+
customer
Parameters for customer
methods are prefixed like customer<param name>(val)
customerId(val)
Id for the new customer. If not given, this will be same as the subscription id.
optional, string, max chars=50
customerEmail(val)
Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70
customerFirstName(val)
First name of the customer.
optional, string, max chars=150
customerLastName(val)
Last name of the customer.
optional, string, max chars=150
customerCompany(val)
Company name of the customer.
optional, string, max chars=250
customerTaxability(val)
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable
Possible values are
TAXABLECustomer is taxable.EXEMPT
  • Customer is exempted from tax
  • Optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
.
customerPhone(val)
Phone number of the customer.
optional, string, max chars=50
customerAutoCollection(val)
Whether payments needs to be collected automatically for this customer.
optional, enumerated string, default=on
Possible values are
ONWhenever an invoice is created, an automatic attempt to charge the customer's payment method is made.OFFAutomatic collection of charges will not be made. All payments must be recorded offline.
customerAllowDirectDebit(val)
Whether the customer can pay via Direct Debit.
optional, boolean, default=false
customerVatNumber(val)
VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20
+
card
Parameters for card
methods are prefixed like card<param name>(val)
cardGateway(val)
Name of the gateway this payment source is stored with.
optional, enumerated string
Possible values are
CHARGEBEEChargebee test gateway.STRIPEStripe payment gateway.BRAINTREEBraintree payment gateway.
AUTHORIZE_NETAuthorize.net payment gateway.PAYPAL_PROPaypal Pro Account.PINPin payment gateway.EWAYeWAY Account.EWAY_RAPIDeWAY Rapid gateway.WORLDPAYWorldPay payment gateway.BALANCED_PAYMENTSBalanced payment gateway.BEANSTREAMBambora (formerly Beanstream).BLUEPAYBluePay payment gateway.ELAVONElavon Virtual Merchant.FIRST_DATA_GLOBALFirst Data Global Gateway Virtual Terminal Account.HDFCHDFC Account.MIGSMasterCard Internet Gateway Service.NMINMI gateway.OGONEIngenico ePayments (formerly Ogone).PAYMILLPAYMILL payment gateway.PAYPAL_PAYFLOW_PROPayPal Payflow Pro gateway.SAGE_PAYSage Pay gateway.TCO2Checkout payment gateway.WIRECARDWireCard Account.
Show all values[+]
cardTmpToken(val)
The single-use card token returned by vaults like Stripe/Braintree which act as a substitute for your card details. Before calling this API, you should have submitted your card details to the gateway and gotten this token in return.
Note: Supported only for Stripe, Braintree and Authorize.Net. If this value is specified, there is no need to specify other card details (like number, cvv, etc).
optional, string, max chars=300
cardFirstName(val)
Cardholder's first name.
optional, string, max chars=50
cardLastName(val)
Cardholder's last name.
optional, string, max chars=50
cardNumber(val)
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
cardExpiryMonth(val)
Card expiry month.
required if card provided, integer, min=1, max=12
cardExpiryYear(val)
Card expiry year.
required if card provided, integer
cardCvv(val)
The card verification value. If you are using Braintree.js, you can specify the Braintree encrypted cvv here.
optional, string, max chars=520
cardBillingAddr1(val)
Address line 1, as available in card billing address.
optional, string, max chars=150
cardBillingAddr2(val)
Address line 2, as available in card billing address.
optional, string, max chars=150
cardBillingCity(val)
City, as available in card billing address.
optional, string, max chars=50
cardBillingStateCode(val)
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
cardBillingState(val)
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
cardBillingZip(val)
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
cardBillingCountry(val)
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
cardIpAddress(val)
The IP address from where the payment source is created or updated. Used primarily for EU VAT validation.
optional, string, max chars=50
+
paymentMethod
Parameters for paymentMethod
methods are prefixed like paymentMethod<param name>(val)
paymentMethodType(val)
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
optional, enumerated string
Possible values are
CARDCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.PAYPAL_EXPRESS_CHECKOUTPayments made via PayPal Express Checkout.AMAZON_PAYMENTSPayments made via Amazon Payments.DIRECT_DEBITRepresents bank account for which the direct debit or ACH agreement/mandate is created.
paymentMethodGateway(val)
Name of the gateway the payment method is associated with.
optional, enumerated string
Possible values are
STRIPEStripe payment gateway.BRAINTREEBraintree payment gateway.
AUTHORIZE_NETAuthorize.net payment gateway.PAYPAL_PROPaypal Pro Account.PINPin payment gateway.EWAYeWAY Account.EWAY_RAPIDeWAY Rapid gateway.WORLDPAYWorldPay payment gateway.BALANCED_PAYMENTSBalanced payment gateway.BEANSTREAMBambora (formerly Beanstream).BLUEPAYBluePay payment gateway.ELAVONElavon Virtual Merchant.FIRST_DATA_GLOBALFirst Data Global Gateway Virtual Terminal Account.HDFCHDFC Account.MIGSMasterCard Internet Gateway Service.NMINMI gateway.OGONEIngenico ePayments (formerly Ogone).PAYMILLPAYMILL payment gateway.PAYPAL_PAYFLOW_PROPayPal Payflow Pro gateway.SAGE_PAYSage Pay gateway.TCO2Checkout payment gateway.WIRECARDWireCard Account.
Show all values[+]
paymentMethodReferenceId(val)
The reference id. In the case of Amazon and Paypal this will be the billing agreement id. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=200
+
paymentIntent
Parameters for paymentIntent
methods are prefixed like paymentIntent<param name>(val)
paymentIntentId(val)
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
optional, string, max chars=150
paymentIntentGatewayAccountId(val)
The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50
paymentIntentGwToken(val)
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
optional, string, max chars=65k
paymentIntentReferenceId(val)
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k
+
billingAddress
Parameters for billingAddress
methods are prefixed like billingAddress<param name>(val)
billingAddressFirstName(val)
First name.
optional, string, max chars=150
billingAddressLastName(val)
Last name.
optional, string, max chars=150
billingAddressEmail(val)
Email.
optional, string, max chars=70
billingAddressCompany(val)
Company name.
optional, string, max chars=250
billingAddressPhone(val)
Phone number.
optional, string, max chars=50
billingAddressLine1(val)
Address line 1.
optional, string, max chars=150
billingAddressLine2(val)
Address line 2.
optional, string, max chars=150
billingAddressLine3(val)
Address line 3.
optional, string, max chars=150
billingAddressCity(val)
City.
optional, string, max chars=50
billingAddressStateCode(val)
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
billingAddressState(val)
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
billingAddressZip(val)
Zip or Postal code.
optional, string, max chars=20
billingAddressCountry(val)
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
+
shippingAddress
Parameters for shippingAddress
methods are prefixed like shippingAddress<param name>(val)
shippingAddressFirstName(val)
First name.
optional, string, max chars=150
shippingAddressLastName(val)
Last name.
optional, string, max chars=150
shippingAddressEmail(val)
Email.
optional, string, max chars=70
shippingAddressCompany(val)
Company name.
optional, string, max chars=250
shippingAddressPhone(val)
Phone number.
optional, string, max chars=50
shippingAddressLine1(val)
Address line 1.
optional, string, max chars=180
shippingAddressLine2(val)
Address line 2.
optional, string, max chars=150
shippingAddressLine3(val)
Address line 3.
optional, string, max chars=150
shippingAddressCity(val)
City.
optional, string, max chars=50
shippingAddressStateCode(val)
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
shippingAddressState(val)
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
shippingAddressZip(val)
Zip or Postal code.
optional, string, max chars=20
shippingAddressCountry(val)
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
+
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
methods are prefixed like addons<param name>(idx,val)
addonId(idx,val)
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addonQuantity(idx,val)
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
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
This operation supports 3DS verification flow. To acheive the same, create the Payment Intent and pass it as input parameter to this API.

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

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

Notes

If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.createForCustomer("__test__5SK0bLNFRFuBvDL6q")
	.planId("no_trial")
	.shippingAddressFirstName("Mark")
	.shippingAddressLastName("Henry")
	.shippingAddressCompany("chargebee")
	.startDate(1548178669)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.createForCustomer("__test__5SK0bLNFRFuBvDL6q")
	.planId("no_trial")
	.shippingAddressFirstName("Mark")
	.shippingAddressLastName("Henry")
	.shippingAddressCompany("chargebee")
	.startDate(1548178669)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();

Sample Result [ JSON ]

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

Method

Subscription.createForCustomer(<customer_id>)
id(val)
Id for the new subscription. If not given, this will be auto-generated.
optional, string, max chars=50
planId(val)
Identifier of the plan for this subscription.
required, string, max chars=100
planQuantity(val)
Plan quantity for this subscription.
optional, integer, default=1, min=1
startDate(val)
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
trialEnd(val)
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
billingCycles(val)
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
coupon(val)

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

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

optional, string, max chars=50
poNumber(val)
Purchase Order Number for this subscription.
optional, string, max chars=100
invoiceNotes(val)
Invoice Notes for this resource. Read More.
optional, string, max chars=2000
metaData(val)
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
+
shippingAddress
Parameters for shippingAddress
methods are prefixed like shippingAddress<param name>(val)
shippingAddressFirstName(val)
First name.
optional, string, max chars=150
shippingAddressLastName(val)
Last name.
optional, string, max chars=150
shippingAddressEmail(val)
Email.
optional, string, max chars=70
shippingAddressCompany(val)
Company name.
optional, string, max chars=250
shippingAddressPhone(val)
Phone number.
optional, string, max chars=50
shippingAddressLine1(val)
Address line 1.
optional, string, max chars=180
shippingAddressLine2(val)
Address line 2.
optional, string, max chars=150
shippingAddressLine3(val)
Address line 3.
optional, string, max chars=150
shippingAddressCity(val)
City.
optional, string, max chars=50
shippingAddressStateCode(val)
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
shippingAddressState(val)
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
shippingAddressZip(val)
Zip or Postal code.
optional, string, max chars=20
shippingAddressCountry(val)
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
+
paymentIntent
Parameters for paymentIntent
methods are prefixed like paymentIntent<param name>(val)
paymentIntentId(val)
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
optional, string, max chars=150
paymentIntentGatewayAccountId(val)
The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50
paymentIntentGwToken(val)
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
optional, string, max chars=65k
paymentIntentReferenceId(val)
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k
+
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
methods are prefixed like addons<param name>(idx,val)
addonId(idx,val)
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addonQuantity(idx,val)
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
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Retrieves the list of subscriptions.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
ListResult result = Subscription.list()
	.limit(2)
	.request();
for(ListResult.Entry entry:result) {
	Subscription subscription = entry.subscription();
	Customer customer = entry.customer();
	Card card = entry.card();
}
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
ListResult result = Subscription.list()
	.limit(2)
	.request();
for(ListResult.Entry entry:result) {
	Subscription subscription = entry.subscription();
	Customer customer = entry.customer();
	Card card = entry.card();
}

Sample Result [ JSON ]

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

Method

Subscription.list()
limit(val)
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset(val)
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
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
next_offset
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000
Retrieves the list of subscriptions for a customer sorted by recent created ones on top.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
ListResult result = Subscription.subscriptionsForCustomer("__test__5SK0bLNFRFuBvQU7D")
	.limit(3)
	.request();
for(ListResult.Entry entry:result) {
	Subscription subscription = entry.subscription();
}
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
ListResult result = Subscription.subscriptionsForCustomer("__test__5SK0bLNFRFuBvQU7D")
	.limit(3)
	.request();
for(ListResult.Entry entry:result) {
	Subscription subscription = entry.subscription();
}

Sample Result [ JSON ]

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

Method

Subscription.subscriptionsForCustomer(<customer_id>)
limit(val)
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset(val)
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
Resource object representing subscription.
always returned
next_offset
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000
Retrieves the subscription identified by the 'subscription id' specified in the url.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.retrieve("__test__5SK0bLNFRFuBwQA9L").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.retrieve("__test__5SK0bLNFRFuBwQA9L").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();

Sample Result [ JSON ]

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

Method

Subscription.retrieve(<subscription_id>)
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional

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

  • plan_id
  • plan_quantity
  • remaining_billing_cycles
  • addons
  • coupons
Other attributes such as status, next_billing_at are not changed and will reflect the current subscription values.

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.retrieveWithScheduledChanges("__test__5SK0bLNFRFuBwSh9S").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.retrieveWithScheduledChanges("__test__5SK0bLNFRFuBwSh9S").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();

Sample Result [ JSON ]

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

Method

Subscription.retrieveWithScheduledChanges(<subscription_id>)
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Removes the subscription changes scheduled on next renewal. Advance charges, if any, will be refunded as credits and a new invoice will be generated on renewal.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.removeScheduledChanges("__test__5SK0bLNFRFuBw1g8Z").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.removeScheduledChanges("__test__5SK0bLNFRFuBw1g8Z").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();

Sample Result [ JSON ]

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

Method

Subscription.removeScheduledChanges(<subscription_id>)
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional

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

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

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.removeScheduledCancellation("__test__5SK0bLNFRFuBvxO8Q").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.removeScheduledCancellation("__test__5SK0bLNFRFuBvxO8Q").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();

Sample Result [ JSON ]

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

Method

Subscription.removeScheduledCancellation(<subscription_id>)
billingCycles(val)
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
This operation supports 3DS verification flow. To acheive the same, create the Payment Intent and pass it as input parameter to this API.

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

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

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

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

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

  • If you are using Stripe gateway, you can use Stripe.js with your checkout form. Please refer this tutorial for more details.
  • If you are using Braintree gateway, you can use Braintree.js with your checkout form.
  • You can also use our Hosted Pages based integration.

Notes

Proration Scenario: A customer changes from a $15 plan to $30 plan after 15 days of a monthly term. He will be billed a total of $7.50 immediately. Calculation will be as follows:

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

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

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

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

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

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

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    
/* 
    updates the subscription's plan and replaces the addons associated with it .The changes made will be effective from current end of term.
*/

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.update("__test__5SK0bLNFRFuBwXZ9h")
	.planId("plan1")
	.addonId(0,"sub_ssl")
	.addonId(1,"sub_monitor")
	.addonQuantity(1,2)
	.endOfTerm(true)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();
    System.out.println(result);
  }
}
copy full code
copy snippet
/* 
    updates the subscription's plan and replaces the addons associated with it .The changes made will be effective from current end of term.
*/

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.update("__test__5SK0bLNFRFuBwXZ9h")
	.planId("plan1")
	.addonId(0,"sub_ssl")
	.addonId(1,"sub_monitor")
	.addonQuantity(1,2)
	.endOfTerm(true)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();

Sample Result [ JSON ]

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

Method

Subscription.update(<subscription_id>)
planId(val)
Identifier of the plan for this subscription.
optional, string, max chars=100
planQuantity(val)
Represents the plan quantity for this subscription.
optional, integer, min=1
startDate(val)
Applicable only for 'future' subscriptions. The new start date of the 'future' subscription.
optional, timestamp(UTC) in seconds
trialEnd(val)
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
billingCycles(val)
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
replaceAddonList(val)
Should be true if the existing addons should be replaced with the ones that are being passed.
optional, boolean
coupon(val)
Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
optional, string, max chars=50
poNumber(val)
Purchase Order Number for this subscription.
optional, string, max chars=100
prorate(val)
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
endOfTerm(val)
You can specify when you want to update the subscription.
optional, boolean
invoiceNotes(val)
Invoice Notes for this resource. Read More.
optional, string, max chars=2000
metaData(val)
Additional data about this resource can be stored here in the JSON Format. Learn more.
optional, jsonobject
+
card
Parameters for card
methods are prefixed like card<param name>(val)
cardGateway(val)
Name of the gateway this payment source is stored with.
optional, enumerated string
Possible values are
CHARGEBEEChargebee test gateway.STRIPEStripe payment gateway.BRAINTREEBraintree payment gateway.
AUTHORIZE_NETAuthorize.net payment gateway.PAYPAL_PROPaypal Pro Account.PINPin payment gateway.EWAYeWAY Account.EWAY_RAPIDeWAY Rapid gateway.WORLDPAYWorldPay payment gateway.BALANCED_PAYMENTSBalanced payment gateway.BEANSTREAMBambora (formerly Beanstream).BLUEPAYBluePay payment gateway.ELAVONElavon Virtual Merchant.FIRST_DATA_GLOBALFirst Data Global Gateway Virtual Terminal Account.HDFCHDFC Account.MIGSMasterCard Internet Gateway Service.NMINMI gateway.OGONEIngenico ePayments (formerly Ogone).PAYMILLPAYMILL payment gateway.PAYPAL_PAYFLOW_PROPayPal Payflow Pro gateway.SAGE_PAYSage Pay gateway.TCO2Checkout payment gateway.WIRECARDWireCard Account.
Show all values[+]
cardTmpToken(val)
The single-use card token returned by vaults like Stripe/Braintree which act as a substitute for your card details. Before calling this API, you should have submitted your card details to the gateway and gotten this token in return.
Note: Supported only for Stripe, Braintree and Authorize.Net. If this value is specified, there is no need to specify other card details (like number, cvv, etc).
optional, string, max chars=300
cardFirstName(val)
Cardholder's first name.
optional, string, max chars=50
cardLastName(val)
Cardholder's last name.
optional, string, max chars=50
cardNumber(val)
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
cardExpiryMonth(val)
Card expiry month.
required if card provided, integer, min=1, max=12
cardExpiryYear(val)
Card expiry year.
required if card provided, integer
cardCvv(val)
The card verification value. If you are using Braintree.js, you can specify the Braintree encrypted cvv here.
optional, string, max chars=520
cardBillingAddr1(val)
Address line 1, as available in card billing address.
optional, string, max chars=150
cardBillingAddr2(val)
Address line 2, as available in card billing address.
optional, string, max chars=150
cardBillingCity(val)
City, as available in card billing address.
optional, string, max chars=50
cardBillingStateCode(val)
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
cardBillingState(val)
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
cardBillingZip(val)
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
cardBillingCountry(val)
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
cardIpAddress(val)
The IP address from where the payment source is created or updated. Used primarily for EU VAT validation.
optional, string, max chars=50
+
paymentMethod
Parameters for paymentMethod
methods are prefixed like paymentMethod<param name>(val)
paymentMethodType(val)
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
optional, enumerated string
Possible values are
CARDCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.PAYPAL_EXPRESS_CHECKOUTPayments made via PayPal Express Checkout.AMAZON_PAYMENTSPayments made via Amazon Payments.DIRECT_DEBITRepresents bank account for which the direct debit or ACH agreement/mandate is created.
paymentMethodGateway(val)
Name of the gateway the payment method is associated with.
optional, enumerated string
Possible values are
STRIPEStripe payment gateway.BRAINTREEBraintree payment gateway.
AUTHORIZE_NETAuthorize.net payment gateway.PAYPAL_PROPaypal Pro Account.PINPin payment gateway.EWAYeWAY Account.EWAY_RAPIDeWAY Rapid gateway.WORLDPAYWorldPay payment gateway.BALANCED_PAYMENTSBalanced payment gateway.BEANSTREAMBambora (formerly Beanstream).BLUEPAYBluePay payment gateway.ELAVONElavon Virtual Merchant.FIRST_DATA_GLOBALFirst Data Global Gateway Virtual Terminal Account.HDFCHDFC Account.MIGSMasterCard Internet Gateway Service.NMINMI gateway.OGONEIngenico ePayments (formerly Ogone).PAYMILLPAYMILL payment gateway.PAYPAL_PAYFLOW_PROPayPal Payflow Pro gateway.SAGE_PAYSage Pay gateway.TCO2Checkout payment gateway.WIRECARDWireCard Account.
Show all values[+]
paymentMethodReferenceId(val)
The reference id. In the case of Amazon and Paypal this will be the billing agreement id. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=200
+
paymentIntent
Parameters for paymentIntent
methods are prefixed like paymentIntent<param name>(val)
paymentIntentId(val)
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
optional, string, max chars=150
paymentIntentGatewayAccountId(val)
The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50
paymentIntentGwToken(val)
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
optional, string, max chars=65k
paymentIntentReferenceId(val)
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k
+
billingAddress
Parameters for billingAddress
methods are prefixed like billingAddress<param name>(val)
billingAddressFirstName(val)
First name.
optional, string, max chars=150
billingAddressLastName(val)
Last name.
optional, string, max chars=150
billingAddressEmail(val)
Email.
optional, string, max chars=70
billingAddressCompany(val)
Company name.
optional, string, max chars=250
billingAddressPhone(val)
Phone number.
optional, string, max chars=50
billingAddressLine1(val)
Address line 1.
optional, string, max chars=150
billingAddressLine2(val)
Address line 2.
optional, string, max chars=150
billingAddressLine3(val)
Address line 3.
optional, string, max chars=150
billingAddressCity(val)
City.
optional, string, max chars=50
billingAddressStateCode(val)
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
billingAddressState(val)
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
billingAddressZip(val)
Zip or Postal code.
optional, string, max chars=20
billingAddressCountry(val)
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
+
shippingAddress
Parameters for shippingAddress
methods are prefixed like shippingAddress<param name>(val)
shippingAddressFirstName(val)
First name.
optional, string, max chars=150
shippingAddressLastName(val)
Last name.
optional, string, max chars=150
shippingAddressEmail(val)
Email.
optional, string, max chars=70
shippingAddressCompany(val)
Company name.
optional, string, max chars=250
shippingAddressPhone(val)
Phone number.
optional, string, max chars=50
shippingAddressLine1(val)
Address line 1.
optional, string, max chars=180
shippingAddressLine2(val)
Address line 2.
optional, string, max chars=150
shippingAddressLine3(val)
Address line 3.
optional, string, max chars=150
shippingAddressCity(val)
City.
optional, string, max chars=50
shippingAddressStateCode(val)
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
shippingAddressState(val)
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
shippingAddressZip(val)
Zip or Postal code.
optional, string, max chars=20
shippingAddressCountry(val)
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
+
customer
Parameters for customer
methods are prefixed like customer<param name>(val)
customerVatNumber(val)
VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20
+
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
methods are prefixed like addons<param name>(idx,val)
addonId(idx,val)
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addonQuantity(idx,val)
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
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional

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

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

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

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

Notes

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

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.changeTermEnd("__test__5SK0bLNFRFuBuqE6C")
	.termEndsAt(1548700200)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.changeTermEnd("__test__5SK0bLNFRFuBuqE6C")
	.termEndsAt(1548700200)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();

Sample Result [ JSON ]

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

Method

Subscription.changeTermEnd(<subscription_id>)
termEndsAt(val)
The time at which the current term should end for this subscription.
required, timestamp(UTC) in seconds
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
This operation supports 3DS verification flow. To acheive the same, create the Payment Intent and pass it as input parameter to this API.

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

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

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

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

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

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

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

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

Notes

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

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

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

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

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.reactivate("__test__5SK0bLNFRFuBvia7x")
	.billingCycles(4)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.reactivate("__test__5SK0bLNFRFuBvia7x")
	.billingCycles(4)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();

Sample Result [ JSON ]

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

Method

Subscription.reactivate(<subscription_id>)
trialEnd(val)
The time at which the trial should end for this subscription.
optional, timestamp(UTC) in seconds
billingCycles(val)
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0
+
paymentIntent
Parameters for paymentIntent
methods are prefixed like paymentIntent<param name>(val)
paymentIntentId(val)
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
optional, string, max chars=150
paymentIntentGatewayAccountId(val)
The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50
paymentIntentGwToken(val)
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
optional, string, max chars=65k
paymentIntentReferenceId(val)
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional

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

To collect a charge immediately, use this API.

Notes

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

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.addChargeAtTermEnd("__test__5SK0bLNFRFuBuUd5f")
	.amount(300)
	.description("Service Charge")
	.request();
Estimate estimate = result.estimate();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.addChargeAtTermEnd("__test__5SK0bLNFRFuBuUd5f")
	.amount(300)
	.description("Service Charge")
	.request();
Estimate estimate = result.estimate();

Sample Result [ JSON ]

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

Method

Subscription.addChargeAtTermEnd(<subscription_id>)
amount(val)
The amount to be charged.
required, in cents, min=1
description(val)
Description for this charge.
required, string, max chars=250
Resource object representing estimate.
always returned

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

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

Notes

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

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.chargeAddonAtTermEnd("__test__5SK0bLNFRFuBuwc6K")
	.addonId("non_recurring_addon")
	.addonQuantity(3)
	.request();
Estimate estimate = result.estimate();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.chargeAddonAtTermEnd("__test__5SK0bLNFRFuBuwc6K")
	.addonId("non_recurring_addon")
	.addonQuantity(3)
	.request();
Estimate estimate = result.estimate();

Sample Result [ JSON ]

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

Method

Subscription.chargeAddonAtTermEnd(<subscription_id>)
addonId(val)
The ID of the non-recurring addon to be charged.
required, string, max chars=100
addonQuantity(val)
The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1
Resource object representing estimate.
always returned

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 Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.delete("__test__5SK0bLNFRFuBvJV6x").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.delete("__test__5SK0bLNFRFuBvJV6x").request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();

Sample Result [ JSON ]

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

Method

Subscription.delete(<subscription_id>)
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional

Cancelling a subscription will move the current state of the subscription to the cancelled state and will stop all recurring actions.

You could schedule the cancellation by passing end_of_term parameter as true. If scheduled, the subscription status will be set to non_renewing if it is in active state until the end of term and then cancelled. Subscription's state will not change if it is in in_trial state. However, cancellation will be scheduled at the trial end date.

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

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

Notes

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

Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    
/* 
    cancels the subscription after the term ends.
*/

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.cancel("__test__5SK0bLNFRFuBucK5q")
	.endOfTerm(true)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();
    System.out.println(result);
  }
}
copy full code
copy snippet
/* 
    cancels the subscription after the term ends.
*/

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.cancel("__test__5SK0bLNFRFuBucK5q")
	.endOfTerm(true)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();

Sample Result [ JSON ]

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

Method

Subscription.cancel(<subscription_id>)
endOfTerm(val)
You can specify when you want to cancel the subscription.
optional, boolean, default=false
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional