the conditions specified in the filter parameters below.
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset
to the value of next_offset
obtained in the previous iteration of the API call.
optional, string, max chars=1000
Indicates whether to include deleted objects in the list. The deleted objects have the attribute deleted
as true
.
optional, boolean, default=false
Sorts based on the specified attribute.
Supported attributes : created_at, updated_at
Supported sort-orders : asc, desc
Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
optional, string filter
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "8gsnbYfsMLds"
optional, string filter
Identifier of the customer with whom this subscription is associated.
Supported operators : is, is_not, starts_with, in, not_in
Example → customer_id[is] = "8gsnbYfsMLds"
optional, string filter
The plan item code.
Supported operators : is, is_not, starts_with, in, not_in
Example → item_id[is_not] = "silver"
optional, string filter
item_price_id[<operator>]
The plan item price code.
Supported operators : is, is_not, starts_with, in, not_in
Example → item_price_id[is] = "silver-USD-monthly"
optional, string filter
Current state of the subscription. Possible values are : future, in_trial, active, non_renewing, paused, cancelled.
Supported operators : is, is_not, in, not_in
Example → status[is_not] = "active"
optional, enumerated string filter
cancel_reason[<operator>]
The reason for canceling the subscription. Set by Chargebee automatically. Possible values are : not_paid, no_card, fraud_review_failed, non_compliant_eu_customer, tax_calculation_failed, currency_incompatible_with_gateway, non_compliant_customer.
Supported operators : is, is_not, in, not_in, is_present
Example → cancel_reason[is] = "not_paid"
optional, enumerated string filter
cancel_reason_code[<operator>]
Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation. Must be passed if set as mandatory in the app. The codes are case-sensitive.
Supported operators : is, is_not, starts_with, in, not_in
Example → cancel_reason_code[is] = "Not Paid"
optional, string filter
remaining_billing_cycles[<operator>]
- When the subscription is not on a contract term: this value is the number of billing cycles remaining after the current cycle, at the end of which, the subscription cancels.
- When the subscription is on a contract term: this value is the number of billing cycles remaining in the contract term after the current billing cycle.
.
Supported operators : is, is_not, lt, lte, gt, gte, between, is_present
Example → remaining_billing_cycles[gt] = "3"optional, integer filter
The time at which the subscription was created.
Supported operators : after, before, on, between
Example → created_at[before] = "1435054328"
optional, timestamp(UTC) in seconds filter
Time at which the subscription status
last changed to
active
. For example, this value is updated when an in_trial
or
cancelled
subscription activates.
Supported operators : after, before, on, between, is_present
Example → activated_at[on] = "1435054328"
optional, timestamp(UTC) in seconds filter
next_billing_at[<operator>]
The date/time at which the next billing for the subscription happens. This is usually right after current_term_end
unless multiple subscription terms were invoiced in advance using the terms_to_charge
parameter.
Supported operators : after, before, on, between
Example → next_billing_at[on] = "1435054328"
optional, timestamp(UTC) in seconds filter
Time at which subscription was cancelled or is set to be cancelled.
Supported operators : after, before, on, between
Example → cancelled_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter
has_scheduled_changes[<operator>]
If true
, there are subscription changes scheduled on next renewal. Possible values are : true, false
Supported operators : is
Example → has_scheduled_changes[is] = "true"
optional, boolean filter
To filter based on updated_at
. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by
input parameter as updated_at
for a faster response.
Supported operators : after, before, on, between
Example → updated_at[after] = "1243545465"
optional, timestamp(UTC) in seconds filter
offline_payment_method[<operator>]
The preferred offline payment method for the subscription. Possible values are : no_preference, cash, check, bank_transfer, ach_credit, sepa_credit.
Supported operators : is, is_not, in, not_in
Example → offline_payment_method[is] = "cash"
optional, enumerated string filter
auto_close_invoices[<operator>]
Set to
false
to override for this subscription, the
site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute has a higher precedence than the same attribute at the
customer level. Possible values are :
true, falseSupported operators : is
Example → auto_close_invoices[is] = "true"optional, boolean filter
create_pending_invoices[<operator>]
Indicates whether the invoices for this subscription are generated with a pending
status
. This attribute is set to true
automatically when the subscription has item prices that belong to metered
items.
You can also set this to true
explicitly using the create/update subscription operations. This is useful in the following scenarios:
- When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
- When you need to inspect all charges before closing invoices for this subscription.
Applicable only when Metered Billing is enabled for the site
. Possible values are :
true, falseSupported operators : is
Example → create_pending_invoices[is] = "true"optional, boolean filter
override_relationship[<operator>]
If
true
, ignores the
hierarchy relationship and uses customer as payment and invoice owner. Possible values are :
true, falseSupported operators : is
Example → override_relationship[is] = "false"optional, boolean filter
Retrieves a list of contract term resources for the subscription specified in the path.
Retrieves a subscription.
Retrieves a subscription with the scheduled changes applied.
Note: Only the following attributes are changed
are not changed and will reflect the current subscription values.
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.
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.
Removes Coupons associated with the Subscription. If the param 'coupon_ids' is not specified, all the Coupons linked to the Subscription will be removed.
Updates the specified subscription by setting the parameters passed. Any parameters not provided are left unmodified. If an invoice is generated for this operation, any available credits and excess payments for the customer are automatically applied.
Sample Request
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__8asrKRrLKtirr/update_for_items \
-u {site_api_key}:\
-d subscription_items[item_price_id][0]="basic-USD" \
-d subscription_items[quantity][0]=4 \
-d subscription_items[unit_price][0]=1000 \
-d invoice_immediately="true"
copy
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__8asrKRrLKtirr/update_for_items \
-u {site_api_key}:\
-d subscription_items[item_price_id][0]="basic-USD" \
-d subscription_items[quantity][0]=4 \
-d subscription_items[unit_price][0]=1000 \
-d invoice_immediately="true"
Sample Response [ JSON ]
Show more...
{
"credit_notes": [],
"customer": {
"allow_direct_debit": false,
"auto_collection": "off",
"card_status": "no_card",
"created_at": 1582476684,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__8asrKRrLKthXp",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1582476684000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1582476684
},
"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 3000,
"amount_paid": 0,
"amount_to_collect": 3000,
"applied_credits": [],
"base_currency_code": "USD",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"object": "billing_address",
"validation_status": "not_validated"
},
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__8asrKRrLKthXp",
"date": 1582476685,
"deleted": false,
"due_date": 1582476685,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__3",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 3000,
"customer_id": "__test__8asrKRrLKthXp",
"date_from": 1582476685,
"date_to": 1584982284,
"description": "basic USD - Prorated Charges",
"discount_amount": 0,
"entity_id": "basic-USD",
"entity_type": "plan_price",
"id": "li___test__8asrKRrLKtyIy",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 3,
"subscription_id": "__test__8asrKRrLKtirr",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 1000
},
{..}
],
"linked_orders": [],
"linked_payments": [],
"net_term_days": 0,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1582476685000,
"round_off_amount": 0,
"status": "payment_due",
"sub_total": 3000,
"subscription_id": "__test__8asrKRrLKtirr",
"tax": 0,
"term_finalized": true,
"total": 3000,
"updated_at": 1582476685,
"write_off_amount": 0
},
"subscription": {
"activated_at": 1582476684,
"billing_period": 1,
"billing_period_unit": "month",
"created_at": 1582476684,
"currency_code": "USD",
"current_term_end": 1584982284,
"current_term_start": 1582476684,
"customer_id": "__test__8asrKRrLKthXp",
"deleted": false,
"due_invoices_count": 2,
"due_since": 1582476684,
"has_scheduled_changes": false,
"id": "__test__8asrKRrLKtirr",
"mrr": 0,
"next_billing_at": 1584982284,
"object": "subscription",
"remaining_billing_cycles": 1,
"resource_version": 1582476685000,
"started_at": 1582476684,
"status": "active",
"subscription_items": [
{
"amount": 4000,
"billing_cycles": 1,
"item_free_quantity": 0,
"item_price_id": "basic-USD",
"object": "subscription_item",
"quantity": 4,
"unit_price": 1000
},
{..}
],
"total_dues": 4100,
"updated_at": 1582476685
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/update_for_items
mandatory_items_to_remove[0..n]
If true
then the existing subscription_items
list for the subscription is replaced by the one provided. If false
then the provided subscription_items
list gets added to the existing list.
optional, boolean
The new start date of a future
subscription. Applicable only for future
subscriptions.
optional, timestamp(UTC) in seconds
End of the trial period for the subscription. This overrides the trial period set for the plan. In Product Catalog v2 this overrides trial period set for the plan-item. Set it to 0
to have no trial period.
optional, timestamp(UTC) in seconds
The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan is used. For Product Catalog v2, billing cycles set for plan-item price is used by default.
optional, integer, min=0
The number of subscription billing cycles to
invoice in advance. If a new term is started for the subscription due to this API call, then
terms_to_charge
is inclusive of this new term. See description for the
force_term_reset
parameter to learn more about when a subscription term is reset.
optional, integer, min=1
When the subscription is reactivated as described under the reactivate
parameter, this is the date/time at which the subscription should be reactivated.
optional, timestamp(UTC) in seconds
Override the
billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing.
optional, enumerated stringPossible values are
immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated stringPossible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
The preferred offline payment method for the subscription.
optional, enumerated stringPossible values are
no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.
Purchase order number for this subscription.
optional, string, max chars=100
List of coupons to be applied to this subscription. You can provide coupon ids or
coupon codes.
optional, list of string
If true
then the existing coupon_ids
list for the subscription is replaced by the one provided. If false
then the provided list gets added to the existing coupon_ids
.
optional, boolean
Set this to true if you want the update to be applied at the end of the current subscription billing cycle.
optional, boolean
Say the subscription has the renewal date as 28th of every month. When the plan-item price of the subscription is set to one that has the same billing period as the current plan-item price, the subscription change does not change the term. In other words, the subscription still renews on the 28th. Passing this parameter as true
will have the subscription reset its term to the current date (provided end_of_term
is false).
Note: When the new plan-item price has a billing period different from the current plan-item price of the subscription, the term is always reset, regardless of the value passed for this parameter.
optional, boolean, default=false
-
Product Catalog 2.0: When the
status
of the subscription is cancelled
, this parameter determines whether the subscription is reactivated upon making this API request. Unless passed explicitly as false
, this parameter is implied as true
when you provide the subscription_items
parameter.
-
Product Catalog 1.0: When the
status
of the subscription is cancelled
, this parameter determines whether the subscription is reactivated upon making this API request. Unless passed explicitly as false
, this parameter is implied as true
when you provide plan_id
or addons[id]
.
optional, boolean
The Chargebee payment token generated by Chargebee JS.
optional, string, max chars=40
A customer-facing note added to all invoices associated with this subscription. This note is one among
all the notes displayed on the invoice PDF.
optional, string, max chars=2000
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to
unbilled charges. The default value is as per the
site settings.
optional, boolean
contract_term_billing_cycle_on_renewal
Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as
billing_cycles
or a custom value depending on the
site configuration.
optional, integer, min=1, max=100
The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit.
optional, integer, min=1
The unit of time in multiples of which the free_period parameter is expressed. The value must be equal to or lower than the
period_unit attribute of the
plan chosen.
optional, enumerated stringPossible values are
dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).
Indicates whether the invoices for this subscription are generated with a pending
status
. This attribute is set to true
automatically when the subscription has item prices that belong to metered
items.
You can also set this to true
explicitly using the create/update subscription operations. This is useful in the following scenarios:
- When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
- When you need to inspect all charges before closing invoices for this subscription.
Applicable only when Metered Billing is enabled for the site
.
optional, boolean
Set to
false
to override for this subscription, the
site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute has a higher precedence than the same attribute at the
customer level.
optional, boolean
Parameters for card
pass parameters as card[<param name>]
The gateway account in which this payment source is stored.
optional, string, max chars=50
Cardholder's first name.
optional, string, max chars=50
Cardholder's last name.
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
Card expiry month.
required if card provided, integer, min=1, max=12
Card expiry year.
required if card provided, integer
The card verification value (CVV). If you are using
Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520
Address line 1, as available in card billing address.
optional, string, max chars=150
Address line 2, as available in card billing address.
optional, string, max chars=150
City, as available in card billing address.
optional, string, max chars=50
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
Parameters for payment_method
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 stringPossible 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.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.
Show all values[+]
payment_method[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
payment_method[reference_id]
The reference id. In the case of Amazon and PayPal this will be the
billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer
Update payment method for a customer API under Customer resource.
optional, string, max chars=200
payment_method[tmp_token]
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
payment_method[issuing_country]
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
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
payment_intent[gateway_account_id]
The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50
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
payment_intent[reference_id]
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k
payment_intent[additional_info]
Applicable only for Braintree gateway. Can be used only for Braintree’s
Advance Fraud Management feature. Pass a stringified JSON containing the
device_session_id
and
fraud_merchant_id
as an input to
fingerprint
. Here’s a
sample to it.
optional, jsonobject
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
The first name of the billing contact.
optional, string, max chars=150
billing_address[last_name]
The last name of the billing contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=150
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
billing_address[state_code]
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
billing_address[validation_status]
The address verification status.
optional, enumerated stringPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
The first name of the contact.
optional, string, max chars=150
shipping_address[last_name]
The last name of the contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
shipping_address[company]
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=180
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
shipping_address[state_code]
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
shipping_address[validation_status]
The address verification status.
optional, enumerated stringPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Parameters for customer
pass parameters as customer[<param name>]
VAT/ Tax registration number of the customer.
Learn more.
optional, string, max chars=20
customer[business_customer_without_vat_number]
Confirms that a customer is a valid business without an EU/UK VAT number.
optional, boolean
customer[registered_for_gst]
Confirms that a customer is registered under GST. If set to
true
then the
Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.
optional, boolean
Parameters for contract_term
pass parameters as contract_term[<param name>]
contract_term[action_at_term_end]
Action to be taken when the contract term completes.
optional, enumerated stringPossible values are
renewContract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal
.The action_at_term_end
for the new contract term is set to renew
.evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following: Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal
.The action_at_term_end
for the new contract term is set to cancel
..
contract_term[cancellation_cutoff_period]
The number of days before
contract_end
, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.
optional, integer
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]
subscription_items[item_price_id][0..n]
The unique identifier of the item price.
required, string, max chars=100
subscription_items[quantity][0..n]
The quantity of the item purchased.
optional, integer, min=1
subscription_items[quantity_in_decimal][0..n]
The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when
multi-decimal pricing is enabled.
optional, string, max chars=33
subscription_items[unit_price][0..n]
The price/per unit price of the item. When not provided,
the value set for the item price is used. This is only applicable when the
pricing_model
of the item price is
flat_fee
or
per_unit
. Also, it is only allowed when
price overriding is enabled for the site. The value depends on the
type of currency.
optional, in cents, min=0
subscription_items[unit_price_in_decimal][0..n]
subscription_items[billing_cycles][0..n]
subscription_items[trial_end][0..n]
The date/time when the trial period of the item ends. Applies to plan-items and—-when
enabled-—addon-items as well.
optional, timestamp(UTC) in seconds
subscription_items[service_period_days][0..n]
The service period of the item in days from the day of charge.
optional, integer, min=1, max=730
subscription_items[charge_on_event][0..n]
When
charge_on_option
option is set to
on_event
, this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items.
optional, enumerated stringPossible values are
subscription_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active
or non-renewing
state. Also includes reactivations of canceled subscriptions.contract_terminationwhen a contract term is terminated.
subscription_items[charge_once][0..n]
Indicates if the charge-item is to be charged only once or each time the charge_on_event
occurs. This parameter only applies to charge-items.
optional, boolean
subscription_items[charge_on_option][0..n]
Indicates when the charge-item is to be charged. This parameter only applies to charge-items.
optional, enumerated stringPossible values are
immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event
.
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
item_tiers[item_price_id][0..n]
The id of the item price for which the tier price is being overridden.
optional, string, max chars=100
item_tiers[starting_unit][0..n]
The lowest value in the quantity tier.
optional, integer, min=1
item_tiers[ending_unit][0..n]
The highest value in the quantity tier.
optional, integer
The overridden price of the tier. The value depends on the
type of currency.
optional, in cents, min=0
item_tiers[starting_unit_in_decimal][0..n]
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as
ending_unit_in_decimal
of the next lower tier. Returned only when the pricing_model is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled.
optional, string, max chars=33
item_tiers[ending_unit_in_decimal][0..n]
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the
starting_unit_in_decimal
of the next higher tier. Returned only when the pricing_model is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled.
optional, string, max chars=33
item_tiers[price_in_decimal][0..n]
The decimal representation of the per-unit price for the tier when the
pricing_model
is
tiered
or
volume
. When the
pricing_model
is
stairstep
, it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Resource object representing unbilled_charge.
optional
Resource object representing credit_note.
optional
Changes the subscription's current term end date. Depending on the "status" of the subscription, "term end date" has different effects.
- If the Subscription is in trial, it affects trial end date.
- If the Subscription is active, it affects the next billing date.
- If the Subscription's status is non_renewing, this affects the upcoming cancellation date.
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.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/change_term_end
The time at which the current term should end for this subscription.
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
If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to
unbilled charges. The default value is as per the
site settings.
optional, boolean
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Resource object representing unbilled_charge.
optional
Resource object representing credit_note.
optional
This operation supports 3DS verification flow. To achieve the same, create the
Payment Intent and pass it as input parameter to this API.
This API is used to reactivate a cancelled subscription. You may also optionally specify a trial end date, to move the subscription to In Trial state. If trial end is not specified, the subscription will be activated and any applicable charges will be initiated.
Unless the billing cycle is specified, it will be set to plan's default billing cycle.
During an in-term reactivation++, unless the billing cycle is specified, the subscription's remaining billing cycles will be restored. If a trial end date is specified, then the plan's default billing cycle is used.
++What is an "in-term reactivation"?
An "in-term reactivation" happens when the billing term of the subscription is retained upon cancellation and reactivation is initiated within that term.
When is the ‘billing term’ retained for a cancelled subscription?
When dunning (payment failure retry settings) is configured with the last retry configured as
- cancel subscription and mark invoice as ‘Not Paid’, or
- cancel subscription and mark the invoice as ‘Voided’ and the case if any of the current term invoices is partially or fully paid, the invoice is not voided but instead Chargebee marks the invoices as ‘Not Paid’.
Note : In both cases, the billing term is retained and upon reactivation the subscription will be moved to active state (if the plan does not have a trial period) and no invoice will be generated. Ensure that you collect any unpaid invoices.
Example : A Subscription was billed from 1st to 31st of a month and it was cancelled on the 20th due to one of the above cases (billing term is not reset). If the reactivation happens on 25th then it is considered an in-term reactivation.
Notes
Reactivation of a subscription in non_renewing state has been deprecated. To remove a scheduled cancellation of a non_renewing Subscription, use Remove Scheduled Cancellation API.
However, if you use reactivate API to remove scheduled cancellation for a non_renewing Subscription, then the status will be set to active and the billing cycle will be set to forever. If any value is passed for trial_end or billing cycle, an error will be thrown.
If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.
Additional Error Scenarios: If there is a need to create an immediate charge and the collection fails, an error will be thrown.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/reactivate
The time at which the trial should end for this subscription.
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
When the subscription is reactivated as described under the reactivate
parameter, this is the date/time at which the subscription should be reactivated.
optional, timestamp(UTC) in seconds
If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to
unbilled charges. The default value is as per the
site settings.
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 stringPossible values are
immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
The number of subscription billing cycles to
invoice in advance. If a new term is started for the subscription due to this API call, then
terms_to_charge
is inclusive of this new term. See description for the
force_term_reset
parameter to learn more about when a subscription term is reset.
optional, integer, min=1
contract_term_billing_cycle_on_renewal
Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as
billing_cycles
or a custom value depending on the
site configuration.
optional, integer, min=1, max=100
Parameters for contract_term
pass parameters as contract_term[<param name>]
contract_term[action_at_term_end]
Action to be taken when the contract term completes.
optional, enumerated string, default=cancelPossible values are
renewContract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal
.The action_at_term_end
for the new contract term is set to renew
.evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.
contract_term[cancellation_cutoff_period]
The number of days before
contract_end
, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.
optional, integer, default=0
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
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
payment_intent[gateway_account_id]
The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50
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
payment_intent[reference_id]
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k
payment_intent[additional_info]
Applicable only for Braintree gateway. Can be used only for Braintree’s
Advance Fraud Management feature. Pass a stringified JSON containing the
device_session_id
and
fraud_merchant_id
as an input to
fingerprint
. Here’s a
sample to it.
optional, jsonobject
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Resource object representing unbilled_charge.
optional
Adds a one time charge to the subscription which will be added to the invoice generated at the end of the current term. If there are any applicable coupons in the subscription, an appropriate discount will be applied.
To collect a charge immediately, use this API.
Notes
If any subscription changes happen before the end of the current term, these charges will be collected along with it.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/add_charge_at_term_end
The amount to be charged. The unit depends on the
type of currency.
optional, in cents, min=1
Description for this charge.
required, string, max chars=250
The decimal representation of the amount for the
one-time charge. Provide the value in major units of the currency. Can be provided only when
multi-decimal pricing is enabled.
optional, string, max chars=33
Indicates the type of sale carried out. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, enumerated stringPossible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction is for an item that is subject to vendor use tax.
Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, integer
Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, integer
The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds
The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds
Resource object representing estimate.
always returned
Creates an advance invoice or an advance invoicing schedule. When an advance invoice is generated, and auto_collection
is on
for the subscription, the payment_source
associated with the subscription is charged. Any changes scheduled for the subscription are taken into account automatically while generating an advance invoice. Advance invoices are not generated for a subscription when it is in the paused
status. Advance invoices are generated only for non-metered
items in a subscription.
Notes
- This operation is supported only on select plans. To know more, take a look at our plans and pricing page.
- This operation is not supported for
non_renewing
and cancelled
subscriptions.
- This operation is not supported if an advance invoice is already present. You could void/delete that invoice and try creating another advance invoice.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/charge_future_renewals
- For
schedule_type = immediate
: the number of future billing cycles to be invoiced in advance. The invoicing is done for the remaining_billing_cycles
of the subscription if that is less than terms_to_charge
. - For
schedule_type = fixed_intervals
: The number of future billing cycles in one interval. The schedule is created such that the total number of billing cycles in the schedule does not exceed the remaining_billing_cycles of the subscription.
.
optional, integer, default=1, min=1
Whether the charge should be invoiced immediately or added to
unbilled_charges
. Applicable only when
schedule_type
is
immediate
.
optional, boolean
The type of advance invoice or advance invoicing schedule.
optional, enumerated string
+
fixed_interval_schedule
Parameters for fixed_interval_schedule
pass parameters as fixed_interval_schedule[<param name>]
fixed_interval_schedule[number_of_occurrences]
The number of advance invoices to generate. The schedule is created such that the total number of billing cycles in the schedule does not exceed the
remaining_billing_cycles
of the subscription. This parameter is applicable only when
fixed_interval_schedule[end_schedule_on]
=
after_number_of_intervals
.
optional, integer, min=1
fixed_interval_schedule[days_before_renewal]
The number of days before each interval that advance invoices are generated.
optional, integer, min=1
fixed_interval_schedule[end_schedule_on]
Specifies when the schedule should end.
optional, enumerated stringPossible values are
after_number_of_intervalsAdvance invoices are generated a specified number of times
.specific_dateEnd the advance invoicing schedule on a specific date
.subscription_endAdvance invoices are generated for as long as the subscription is active.
fixed_interval_schedule[end_date]
The date when the schedule should end. Advance invoices are not generated beyond this date. It must be at least 1 day before the start of the last billing cycle of the subscription and also within 5 years from the current date. This parameter is only applicable when
fixed_interval_schedule[end_schedule_on]
=
specific_date
.
optional, timestamp(UTC) in seconds
+
specific_dates_schedule
Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]
specific_dates_schedule[terms_to_charge][0..n]
The number of billing cycles to charge for, on the date specified. Applicable only when
schedule_type
is specific_dates.
optional, integer
specific_dates_schedule[date][0..n]
The unique id of the member of the advance_invoice_schedule array which corresponds to the specific_dates_schedule that you intend to modify. Only applicable when
schedule_type
is
specific_dates
.
optional, timestamp(UTC) in seconds
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Resource object representing advance_invoice_schedule.
optional
Modifies the advance invoicing schedule for a subscription.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/edit_advance_invoice_schedule
The number of billing cycles in one interval.
optional, integer, min=1
The type of advance invoice or advance invoicing schedule.
optional, enumerated string
+
fixed_interval_schedule
Parameters for fixed_interval_schedule
pass parameters as fixed_interval_schedule[<param name>]
fixed_interval_schedule[number_of_occurrences]
The number of advance invoices to generate. The schedule is created such that the total number of billing cycles in the schedule does not exceed the
remaining_billing_cycles
of the subscription. This parameter is applicable only when
fixed_interval_schedule[end_schedule_on]
=
after_number_of_intervals
.
optional, integer, min=1
fixed_interval_schedule[days_before_renewal]
The number of days before each interval that advance invoices are generated.
optional, integer, min=1
fixed_interval_schedule[end_schedule_on]
Specifies when the schedule should end.
optional, enumerated stringPossible values are
after_number_of_intervalsAdvance invoices are generated a specified number of times
.specific_dateEnd the advance invoicing schedule on a specific date
.subscription_endAdvance invoices are generated for as long as the subscription is active.
fixed_interval_schedule[end_date]
The date when the schedule should end. Advance invoices are not generated beyond this date. It must be at least 1 day before the start of the last billing cycle of the subscription and also within 5 years from the current date. This parameter is only applicable when
fixed_interval_schedule[end_schedule_on]
=
specific_date
.
optional, timestamp(UTC) in seconds
+
specific_dates_schedule
Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]
specific_dates_schedule[id][0..n]
specific_dates_schedule[terms_to_charge][0..n]
The number of billing cycles to charge for, on the date specified. Applicable only when
schedule_type
is specific_dates.
optional, integer
specific_dates_schedule[date][0..n]
The unique id of the member of the advance_invoice_schedule array which corresponds to the specific_dates_schedule that you intend to modify. Only applicable when
schedule_type
is
specific_dates
.
optional, timestamp(UTC) in seconds
Resource object representing advance_invoice_schedule.
always returned
Retrieves the advance_invoice_schedule for a subscription. Note that this endpoint is only applicable for schedule_type = specific_dates or fixed_intervals.
URL Format GET
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/retrieve_advance_invoice_schedule
Resource object representing advance_invoice_schedule.
always returned
Deletes an advance invoicing schedule. When schedule_type = specific_dates, you also have the option of deleting a part of the schedule.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_advance_invoice_schedule
+
specific_dates_schedule
Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]
specific_dates_schedule[id][0..n]
When
schedule_type = specific_dates, pass the id of the
specific_dates_schedule that you want to remove. If not passed, the entire advance_invoice_schedule is removed.
optional, string, max chars=50
Resource object representing subscription.
always returned
Resource object representing advance_invoice_schedule.
optional
Regenerates the current invoice for the subscription. The current invoice is that which includes non-metered
items from the current term and metered
items from the previous term of the subscription.
deleting an invoice
Usages are also deleted when an invoice is deleted. Therefore, if the invoice was deleted, you may add or bulk import usages before regenerating an invoice.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/regenerate_invoice
The start date of the period being invoiced. The default value is
current_term_start.
optional, timestamp(UTC) in seconds
The end date of the period being invoiced. The default value is
current_term_end.
optional, timestamp(UTC) in seconds
Whether the charges should be prorated according to the term specified by date_from
and date_to
. Should not be passed without date_from
and date_to
.
optional, boolean
Resource object representing invoice.
optional
Resource object representing unbilled_charge.
optional
Import previous and active
contract terms.
For contract terms in
active
state, import is allowed only if the associated subscription is
active
,
in_trial
,
future
or
non-renewing
.
.
This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/import_contract_term
contract_term_billing_cycle_on_renewal
Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as
billing_cycles
or a custom value depending on the
site configuration.
optional, integer, min=1, max=100
Parameters for contract_term
pass parameters as contract_term[<param name>]
Id that uniquely identifies the contract term in the site.
optional, string, max chars=50
contract_term[created_at]
The date when the contract term was created.
optional, timestamp(UTC) in seconds
contract_term[contract_start]
The start date of the contract term.
optional, timestamp(UTC) in seconds
contract_term[contract_end]
The end date of the contract term.
optional, timestamp(UTC) in seconds
Current status of contract.
optional, enumerated stringPossible values are
activeAn actively running contract term.completedThe contract term has run its full duration.cancelledThe contract term was ended because: .terminatedThe contract term was terminated ahead of completion.
contract_term[total_amount_raised]
The amount raised for the contract term till the time of importing the subscription. This amount is added to the
total_contract_value
.
optional, in cents, default=0, min=0
contract_term[total_contract_value]
The sum of the
totals of all the invoices raised as part of the contract term. For
active
contract terms, this is a predicted value. The value depends on the
type of currency. If the subscription was
imported with the contract term, then this value includes the value passed for
total_amount_raised
.
optional, in cents, default=0, min=0
contract_term[billing_cycle]
The number of billing cycles of the subscription that the contract term is for.
optional, integer, min=0
contract_term[action_at_term_end]
Action to be taken when the contract term completes.
optional, enumerated string, default=renewPossible values are
renewContract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal
.The action_at_term_end
for the new contract term is set to renew
.evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following: Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal
.The action_at_term_end
for the new contract term is set to cancel
..
contract_term[cancellation_cutoff_period]
The number of days before
contract_end
, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.
optional, integer
Resource object representing contract_term.
always returned
Imports a subscription into Chargebee.
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/__test__8at19S2Bx82rKy/import_for_items \
-u {site_api_key}:\
-d subscription_items[item_price_id][0]="basic-USD" \
-d subscription_items[quantity][0]=1 \
-d status="active" \
-d charged_items[item_price_id][0]="ssl-charge-USD" \
-d charged_items[last_charged_at][0]=1516297094 \
-d current_term_end=1593541800
copy
curl https://{site}.chargebee.com/api/v2/customers/__test__8at19S2Bx82rKy/import_for_items \
-u {site_api_key}:\
-d subscription_items[item_price_id][0]="basic-USD" \
-d subscription_items[quantity][0]=1 \
-d status="active" \
-d charged_items[item_price_id][0]="ssl-charge-USD" \
-d charged_items[last_charged_at][0]=1516297094 \
-d current_term_end=1593541800
Sample Response [ JSON ]
Show more...
{
"customer": {
"allow_direct_debit": false,
"auto_collection": "off",
"card_status": "no_card",
"created_at": 1517506693,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__8at19S2Bx82rKy",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1517506693000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1517506693
},
"subscription": {
"activated_at": 1517506694,
"billing_period": 1,
"billing_period_unit": "month",
"charged_items": [
{
"item_price_id": "ssl-charge-USD",
"last_charged_at": 1516297094,
"object": "charged_item"
},
{..}
],
"created_at": 1517506694,
"currency_code": "USD",
"current_term_end": 1593541800,
"current_term_start": 1517506694,
"customer_id": "__test__8at19S2Bx82rKy",
"deleted": false,
"due_invoices_count": 0,
"has_scheduled_changes": false,
"id": "__test__8at19S2Bx84NL0",
"item_tiers": [],
"mrr": 0,
"next_billing_at": 1593541800,
"object": "subscription",
"resource_version": 1517506694000,
"started_at": 1517506694,
"status": "active",
"subscription_items": [
{
"amount": 1000,
"item_free_quantity": 0,
"item_price_id": "basic-USD",
"item_type": "plan",
"object": "subscription_item",
"quantity": 1,
"unit_price": 1000
},
{..}
],
"updated_at": 1517506694
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/customers/{customer_id}/import_for_items
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
optional, string, max chars=50
End of the trial period for the subscription. This overrides the trial period set for the plan-item. The value must be later than start_date
. Set it to 0
to have no trial period.
optional, timestamp(UTC) in seconds
The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles
set for the plan-item price is used.
optional, integer, min=0
The date/time at which the subscription is to start or has started. If not provided, the subscription starts immediately. If set to a value in the past then that date/time should not be more than a plan billing period into the past.
optional, timestamp(UTC) in seconds
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated stringPossible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
Purchase order number for this subscription.
optional, string, max chars=100
List of coupons to be applied to this subscription. You can provide coupon ids or
coupon codes.
optional, list of string
Id of the payment source to be attached to this subscription.
optional, string, max chars=40
Current state of the subscription.
required, enumerated stringPossible values are
futureThe subscription is scheduled to start at a future date.in_trialThe subscription is in trial.activeThe subscription is active and will be charged for automatically based on the items in it.non_renewingThe subscription will be canceled at the end of the current term.pausedThe subscription is paused. The subscription will not renew while in this state.cancelledThe subscription has been canceled and is no longer in service.
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
Start of the current billing period of the subscription.
optional, timestamp(UTC) in seconds
Start of the trial period for the subscription. Presence of this value for future
subscription implies the subscription will go into in_trial
state when it starts.
optional, timestamp(UTC) in seconds
Time at which subscription was cancelled or is set to be cancelled.
optional, timestamp(UTC) in seconds
Time at which the subscription was started. Is null
for future
subscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds
When a pause has been scheduled, it is the date/time of scheduled pause. When the subscription is in the paused
state, it is the date/time when the subscription was paused.
optional, timestamp(UTC) in seconds
For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.
optional, timestamp(UTC) in seconds
contract_term_billing_cycle_on_renewal
Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as
billing_cycles
or a custom value depending on the
site configuration.
optional, integer, min=1, max=100
create_current_term_invoice
Set as
true
if you want an invoice to be created for the subscription.
- The invoice will be created for the subscription only if it has an
active
or non_renewing
status. - The period of the invoice is from
current_term_start
to current_term_end
. - The invoice will not be generated if the subscription amount is zero dollars (for that period) and 'Hide Zero Value Line Items' option is enabled in site settings.
optional, boolean, default=false
A customer-facing note added to all invoices associated with this subscription. This note is one among
all the notes displayed on the invoice PDF.
optional, string, max chars=2000
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
Indicates whether the invoices for this subscription are generated with a pending
status
. This attribute is set to true
automatically when the subscription has item prices that belong to metered
items.
You can also set this to true
explicitly using the create/update subscription operations. This is useful in the following scenarios:
- When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
- When you need to inspect all charges before closing invoices for this subscription.
Applicable only when Metered Billing is enabled for the site
.
optional, boolean
Set to
false
to override for this subscription, the
site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute has a higher precedence than the same attribute at the
customer level.
optional, boolean
Parameters for contract_term
pass parameters as contract_term[<param name>]
Id that uniquely identifies the contract term in the site.
optional, string, max chars=50
contract_term[created_at]
The date when the contract term was created.
optional, timestamp(UTC) in seconds
contract_term[contract_start]
The start date of the contract term.
optional, timestamp(UTC) in seconds
contract_term[billing_cycle]
The number of billing cycles of the subscription that the contract term is for.
optional, integer, min=0
contract_term[total_amount_raised]
The amount raised for the contract term till the time of importing the subscription. This amount is added to the
total_contract_value
.
optional, in cents, default=0, min=0
contract_term[action_at_term_end]
Action to be taken when the contract term completes.
optional, enumerated string, default=renewPossible values are
renewContract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal
.The action_at_term_end
for the new contract term is set to renew
.evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed when you want to renew the contract term just once. Does the following: Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal
.The action_at_term_end
for the new contract term is set to cancel
..
contract_term[cancellation_cutoff_period]
The number of days before
contract_end
, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.
optional, integer, default=0
Parameters for transaction
pass parameters as transaction[<param name>]
The payment transaction amount. This parameter should be passed only if the invoice is created for current term.
optional, in cents, min=1
transaction[payment_method]
The payment method of this transaction. This parameter should be passed only if the invoice is created for current term.
optional, enumerated string, default=cardPossible values are
cashCash.checkCheck.bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
transaction[reference_number]
The reference number for this transaction. For example, check number in case of check
payment_method
. This parameter should be passed only if the invoice is created for current term.
optional, string, max chars=100
The date of occurence of the transaction. This parameter should be passed only if the invoice is created for current term.
optional, timestamp(UTC) in seconds
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
The first name of the contact.
optional, string, max chars=150
shipping_address[last_name]
The last name of the contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
shipping_address[company]
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=180
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
shipping_address[state_code]
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]
subscription_items[item_price_id][0..n]
The unique identifier of the item price.
required, string, max chars=100
subscription_items[quantity][0..n]
The quantity of the item purchased.
optional, integer, min=1
subscription_items[quantity_in_decimal][0..n]
The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when
multi-decimal pricing is enabled.
optional, string, max chars=33
subscription_items[unit_price][0..n]
The price/per unit price of the item. When not provided,
the value set for the item price is used. This is only applicable when the
pricing_model
of the item price is
flat_fee
or
per_unit
. Also, it is only allowed when
price overriding is enabled for the site. The value depends on the
type of currency.
optional, in cents, min=0
subscription_items[unit_price_in_decimal][0..n]
subscription_items[billing_cycles][0..n]
subscription_items[trial_end][0..n]
The date/time when the trial period of the item ends. Applies to plan-items and—-when
enabled-—addon-items as well.
optional, timestamp(UTC) in seconds
subscription_items[service_period_days][0..n]
The service period of the item in days from the day of charge.
optional, integer, min=1, max=730
subscription_items[charge_on_event][0..n]
When
charge_on_option
option is set to
on_event
, this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items.
optional, enumerated stringPossible values are
subscription_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active
or non-renewing
state. Also includes reactivations of canceled subscriptions.contract_terminationwhen a contract term is terminated.
subscription_items[charge_once][0..n]
Indicates if the charge-item is to be charged only once or each time the charge_on_event
occurs. This parameter only applies to charge-items.
optional, boolean
Parameters for charged_items. Multiple charged_items can be passed by specifying unique indices.
pass parameters as charged_items[<param name>][<idx:0..n>]
charged_items[item_price_id][0..n]
A unique ID for your system to identify the item price.
optional, string, max chars=100
charged_items[last_charged_at][0..n]
Timestamp indicating when this charge item_price was last charged for this subscription.
optional, timestamp(UTC) in seconds
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
item_tiers[item_price_id][0..n]
The id of the item price for which the tier price is being overridden.
optional, string, max chars=100
item_tiers[starting_unit][0..n]
The lowest value in the quantity tier.
optional, integer, min=1
item_tiers[ending_unit][0..n]
The highest value in the quantity tier.
optional, integer
The overridden price of the tier. The value depends on the
type of currency.
optional, in cents, default=0, min=0
item_tiers[starting_unit_in_decimal][0..n]
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as
ending_unit_in_decimal
of the next lower tier. Returned only when the pricing_model is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled.
optional, string, max chars=33
item_tiers[ending_unit_in_decimal][0..n]
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the
starting_unit_in_decimal
of the next higher tier. Returned only when the pricing_model is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled.
optional, string, max chars=33
item_tiers[price_in_decimal][0..n]
The decimal representation of the per-unit price for the tier when the
pricing_model
is
tiered
or
volume
. When the
pricing_model
is
stairstep
, it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Assigns the payment source and sets auto collection state for the subscription.
Notes
When you don't pass any input param for this API, payment source and auto collection for the subscription will be the same as the customer's default settings.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/override_billing_profile
Unique identifier of the payment source to be attached to this subscription.
optional, string, max chars=40
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated stringPossible values are
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
Resource object representing subscription.
always returned
Resource object representing payment_source.
optional
We're now in the PCV2 description for this endpoint.
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.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/delete
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
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.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/pause
List of options to pause the subscription.
optional, enumerated stringPossible 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
unbilled_charges_handling
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 stringPossible 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 stringPossible values are
continueContinue dunning.stopStop dunning.
For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.
optional, timestamp(UTC) in seconds
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Resource object representing unbilled_charge.
optional
Resource object representing credit_note.
optional
Cancels the subscription.
Canceling contract terms
- Subscriptions with contract terms can only be canceled by terminating the contract term.
- When canceling a contract term, the default value for the following parameters is taken from the site settings for contract terms instead of the site settings for subscription cancellation.
credit_option_for_current_term_charges
unbilled_charges_option
account_receivables_handling
refundable_credits_handling
- From among the parameters for this request,
end_of_term
or cancel_at
should not be passed when using contract terms; use contract_term_cancel_option
instead.
- The
subscription_items
parameter is used to override price or quantity for the termination fee. To use this parameter, the following two conditions must be met:
contract_term_cancel_option
must be set to terminate_now
.
- the subscription must have a
subscription_items
attribute with charge_on_event
set to contract_term_termination
.
Sample Request
# cancels the subscription after the term ends.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y28bL9/cancel_for_items \
-X POST \
-u {site_api_key}:\
-d end_of_term="true"
copy
# cancels the subscription after the term ends.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y28bL9/cancel_for_items \
-X POST \
-u {site_api_key}:\
-d end_of_term="true"
# cancels the subscription immediately with proration credits issued.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y29FDJ/cancel_for_items \
-X POST \
-u {site_api_key}:\
-d credit_option_for_current_term_charges="prorate" \
-d end_of_term="false"
Sample Response [ JSON ]
Show more...
{
"customer": {
"allow_direct_debit": false,
"auto_collection": "off",
"card_status": "no_card",
"created_at": 1595874348,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnZKS5y288z7",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1595874348000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1595874348
},
"subscription": {
"activated_at": 1595874350,
"billing_period": 1,
"billing_period_unit": "month",
"cancelled_at": 1598552750,
"created_at": 1595874350,
"currency_code": "USD",
"current_term_end": 1598552750,
"current_term_start": 1595874350,
"customer_id": "__test__KyVnZKS5y288z7",
"deleted": false,
"due_invoices_count": 1,
"due_since": 1595874350,
"has_scheduled_changes": false,
"id": "__test__KyVnZKS5y28bL9",
"mrr": 0,
"object": "subscription",
"remaining_billing_cycles": 0,
"resource_version": 1595874352000,
"started_at": 1595874350,
"status": "non_renewing",
"subscription_items": [
{
"amount": 1000,
"billing_cycles": 0,
"item_free_quantity": 0,
"item_price_id": "basic-USD",
"item_type": "plan",
"object": "subscription_item",
"quantity": 1,
"unit_price": 1000
},
{..}
],
"total_dues": 1100,
"updated_at": 1595874352
}
}
Show more...
{
"credit_notes": [
{
"allocations": [
{
"allocated_amount": 1100,
"allocated_at": 1595874353,
"invoice_date": 1595874352,
"invoice_id": "__demo_inv__2",
"invoice_status": "paid"
},
{..}
],
"amount_allocated": 1100,
"amount_available": 0,
"amount_refunded": 0,
"base_currency_code": "USD",
"create_reason_code": "Subscription Cancellation",
"currency_code": "USD",
"customer_id": "__test__KyVnZKS5y29BpH",
"date": 1595874353,
"deleted": false,
"exchange_rate": 1,
"fractional_correction": 0,
"id": "__demo_cn__1",
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__KyVnZKS5y29BpH",
"date_from": 1595874353,
"date_to": 1598552752,
"description": "basic USD - Prorated Credits for 27-Jul-2020 - 27-Aug-2020",
"discount_amount": 0,
"entity_id": "basic-USD",
"entity_type": "plan_item_price",
"id": "li___test__KyVnZKS5y29OfS",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__KyVnZKS5y29FDJ",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 1000
},
{..}
],
"linked_refunds": [],
"object": "credit_note",
"price_type": "tax_exclusive",
"reason_code": "subscription_cancellation",
"reference_invoice_id": "__demo_inv__2",
"refunded_at": 1595874353,
"resource_version": 1595874353000,
"round_off_amount": 0,
"status": "adjusted",
"sub_total": 1100,
"subscription_id": "__test__KyVnZKS5y29FDJ",
"taxes": [],
"total": 1100,
"type": "adjustment",
"updated_at": 1595874353
},
{..}
],
"customer": {
"allow_direct_debit": false,
"auto_collection": "off",
"card_status": "no_card",
"created_at": 1595874352,
"deleted": false,
"excess_payments": 0,
"first_name": "John",
"id": "__test__KyVnZKS5y29BpH",
"last_name": "Doe",
"net_term_days": 0,
"object": "customer",
"pii_cleared": "active",
"preferred_currency_code": "USD",
"promotional_credits": 0,
"refundable_credits": 0,
"resource_version": 1595874352000,
"taxability": "taxable",
"unbilled_charges": 0,
"updated_at": 1595874352
},
"subscription": {
"activated_at": 1595874352,
"billing_period": 1,
"billing_period_unit": "month",
"cancelled_at": 1595874353,
"created_at": 1595874352,
"currency_code": "USD",
"current_term_end": 1595874353,
"current_term_start": 1595874352,
"customer_id": "__test__KyVnZKS5y29BpH",
"deleted": false,
"due_invoices_count": 0,
"has_scheduled_changes": false,
"id": "__test__KyVnZKS5y29FDJ",
"mrr": 0,
"object": "subscription",
"resource_version": 1595874353000,
"started_at": 1595874352,
"status": "cancelled",
"subscription_items": [
{
"amount": 1000,
"item_free_quantity": 0,
"item_price_id": "basic-USD",
"item_type": "plan",
"object": "subscription_item",
"quantity": 1,
"unit_price": 1000
},
{..}
],
"updated_at": 1595874353
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/cancel_for_items
Set this to true
if you want to cancel the subscription at the end of the current subscription billing cycle. The subscription status
changes to non_renewing
.
optional, boolean, default=false
Specify the date at which you want to cancel the subscription. Do not pass if end_of_term
is passed as true
.
optional, timestamp(UTC) in seconds
credit_option_for_current_term_charges
For immediate cancellation (
end_of_term
=
false
), specify how to provide credits for current term charges. When not provided, the
site default is considered.
optional, enumerated stringPossible values are
noneNo credits notes are created.prorateProrated credits are issued.fullCredits are issues for the full value of the current term charges.
For immediate cancellation (
end_of_term
=
false
), specify how to handle any unbilled charges. When not provided, the
site default is considered.
optional, enumerated stringPossible values are
invoiceAn invoice is generated immediately with the unbilled charges.deleteThe unbilled charges are deleted.
account_receivables_handling
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 stringPossible 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.
refundable_credits_handling
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 stringPossible values are
no_actionNo action is taken. .schedule_refundInitiates refund of the remaining credits.
contract_term_cancel_option
Cancels the current contract term.
terminate_immediately
immediately does the following:end_of_contract_term
Sets the contract_term[action_at_term_end]
to cancel
. In other words, the contract term is not renewed and the subscription is canceled at the end of the contract term.
.
optional, enumerated stringPossible values are
terminate_immediatelyTerminate immediately.end_of_contract_termEnd of contract term.
Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation. Must be passed if set as mandatory in the app. The codes are case-sensitive.
optional, string, max chars=100
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]
subscription_items[item_price_id][0..n]
The unique id
of the charge item_price that represents the termination fee.
optional, string, max chars=100
subscription_items[quantity][0..n]
The quantity associated with the termination fee. Applicable only when the item_price for the termination charge is quantity-based.
optional, integer, min=1
subscription_items[quantity_in_decimal][0..n]
The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when
multi-decimal pricing is enabled.
optional, string, max chars=33
subscription_items[unit_price][0..n]
The termination fee. In case it is quantity-based, this is the fee per unit.
optional, in cents, min=0
subscription_items[unit_price_in_decimal][0..n]
subscription_items[service_period_days][0..n]
The service period of the termination fee—expressed in days—starting from the current date.
optional, integer, min=1, max=730
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Resource object representing unbilled_charge.
optional
Resource object representing credit_note.
optional
This operation supports 3DS verification flow. To achieve the same, create the
Payment Intent and pass it as input parameter to this API.
This API is used to 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.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/resume
List of options to resume the subscription.
optional, enumerated stringPossible 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
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 stringPossible 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 stringPossible values are
no_actionRetain as unpaid.schedule_payment_collectionCollect payment.
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
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
payment_intent[gateway_account_id]
The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50
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
payment_intent[reference_id]
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k
payment_intent[additional_info]
Applicable only for Braintree gateway. Can be used only for Braintree’s
Advance Fraud Management feature. Pass a stringified JSON containing the
device_session_id
and
fraud_merchant_id
as an input to
fingerprint
. Here’s a
sample to it.
optional, jsonobject
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
Resource object representing invoice.
optional
Resource object representing unbilled_charge.
optional
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.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_pause
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional
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.
URL Format POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_resumption
Resource object representing subscription.
always returned
Resource object representing customer.
always returned
Resource object representing card.
optional