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'.
{
"activated_at": 1517505643,
"auto_collection": "off",
"billing_period": 1,
"billing_period_unit": "month",
"created_at": 1517505643,
"currency_code": "USD",
"current_term_end": 1519924843,
"current_term_start": 1517505643,
"customer_id": "__test__KyVnHhSBWkkwI2Tn",
"deleted": false,
"due_invoices_count": 1,
"due_since": 1517505643,
"has_scheduled_changes": false,
"id": "__test__KyVnHhSBWkkwI2Tn",
"mrr": 0,
"next_billing_at": 1519924843,
"object": "subscription",
"plan_amount": 895,
"plan_free_quantity": 0,
"plan_id": "no_trial",
"plan_quantity": 1,
"plan_unit_price": 895,
"resource_version": 1517505643000,
"started_at": 1517505643,
"status": "active",
"total_dues": 895,
"updated_at": 1517505643
}
future
subscription implies the subscription will go into in_trial
state when it starts.current_term_end
unless multiple subscription terms were invoiced in advance using the terms_to_charge
parameter.null
for future
subscriptions as it is yet to be started.status
last changed to
active
. For example, this value is updated when an in_trial
or
cancelled
subscription activates.billing_cycles
or a custom value depending on the site configuration.true
, ignores the hierarchy relationship and uses customer as payment and invoice owner.paused
state, it is the date/time when the subscription was paused.true
, there are subscription changes scheduled on next renewal.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:
Applicable only when Metered Billing is enabled for the site
.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.active
or non-renewing
status. Once set, the value can't be changed. (Addon trial periods must be enabled by Chargebee Support.).limited_period
coupons only.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
).contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to cancel
.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
.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.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.
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.
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.
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.
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
billing_address
and vat_number
of the customer are deleted and replaced by the values passed with this request. Ensure that you pass the billing address parameters and the vat_number
parameter (now deprecated), each time you make this request to avoid losing the same information at the customer-level. billing_address
and vat_number
of the customer.
# creates a subscription with customer information and billing details. curl https://{site}.chargebee.com/api/v2/subscriptions \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d auto_collection="off" \ -d customer[first_name]="John" \ -d customer[last_name]="Doe" \ -d customer[email]="john@user.com" \ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US"
billing_cycles
or a custom value depending on the site configuration.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.true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.device_session_id
and fraud_merchant_id
as an input to fingerprint
. Here’s a sample to it.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.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.period
. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.active
or non-renewing
status. Once set, the value can't be changed. (Addon trial periods must be enabled by Chargebee Support.).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.
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWkmi22UR/subscriptions \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d shipping_address[first_name]="Mark" \ -d shipping_address[last_name]="Henry" \ -d shipping_address[company]="chargebee" \ -d start_date=1600968050
true
, ignores the hierarchy relationship and uses customer as payment and invoice owner.billing_cycles
or a custom value depending on the site configuration.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.device_session_id
and fraud_merchant_id
as an input to fingerprint
. Here’s a sample to it.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.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.period
. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.active
or non-renewing
status. Once set, the value can't be changed. (Addon trial periods must be enabled by Chargebee Support.).curl https://{site}.chargebee.com/api/v2/subscriptions \ -G \ -u {site_api_key}:\ --data-urlencode limit=2 \ --data-urlencode plan_id[in]="["basic","no_trial"]"
curl https://{site}.chargebee.com/api/v2/subscriptions \ -G \ -u {site_api_key}:\ --data-urlencode limit=2 \ --data-urlencode plan_id[in]="["basic","no_trial"]"
offset
to the value of next_offset
obtained in the previous iteration of the API call.deleted
as true
.status
last changed to
active
. For example, this value is updated when an in_trial
or
cancelled
subscription activates.current_term_end
unless multiple subscription terms were invoiced in advance using the terms_to_charge
parameter.true
, there are subscription changes scheduled on next renewal. Possible values are : true, falseupdated_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.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, falseIndicates 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:
Applicable only when Metered Billing is enabled for the site
. Possible values are : true, falsetrue
, ignores the hierarchy relationship and uses customer as payment and invoice owner. Possible values are : true, falsecurl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkgjr2SI/contract_terms \ -G \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkv9J2YH \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkv9J2YH \ -u {site_api_key}:
Retrieves a subscription with the scheduled changes applied.
Note: Only the following attributes are changed
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkvUM2YO/retrieve_with_scheduled_changes \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkvUM2YO/retrieve_with_scheduled_changes \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkt5V2XR/remove_scheduled_changes \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkt5V2XR/remove_scheduled_changes \ -X POST \ -u {site_api_key}:
Note: Cannot be called when the subscription is on a contract term. (That is, when the contract_term.status attribute
is active
.)
If the subscription is in Non Renewing or In Trial state and is also scheduled to cancel at the end of current term, then this API can be used to remove the scheduled cancellation. When a scheduled cancellation is removed, the subscription will revert to Active or In Trial state, whichever is the state before cancellation was scheduled.
While removing the scheduled cancellation, you may specify the number of billing cycles. If the billing cycle is not specified, the default billing cycle from the plan will be applied on the subscription.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWksgR2XI/remove_scheduled_cancellation \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWksgR2XI/remove_scheduled_cancellation \ -X POST \ -u {site_api_key}:
# removes the listed coupons associated with the subscription. curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkrtw2X0/remove_coupons \ -X POST \ -u {site_api_key}:\ -d coupon_ids[0]="plan_only_coupon"
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
Proration Scenario: A customer changes from a $15 plan to $30 plan after 15 days of a monthly term. He will be charged for $7.50 immediately. The following Credit Note and Invoice will be generated
Credit Note | |
Prorated credits for Old Plan | $7.50 |
Invoice | |
Prorated charges for New Plan | $15.00 |
Total | $15.00 |
Credits | ($7.50) |
Amount Due | $7.50 |
Meanwhile downgrading will result in net credits being created which will be applied when the subscription is charged on start of the next term. Learn more about our proration scenarios here.
Billing Cycle: The billing period for a subscription does not change if the plans intervals of both old and new are same. However, if a customer changes to a plan that has different billing interval(say monthly to yearly), the billing period is reset. Customer is charged immediately for the modified subscription after applying credit for the unused period for the old subscription.
Card and VAT number Input: If they are passed, corresponding Billing Address attributes and vat_number will be replaced. i.e existing values for Billing Address and 'vat_number' will be cleared and the new values will be set.
If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.
Advance charges, if any, will be refunded as credits and a new invoice will be generated on renewal.
# updates the subscription's plan and replaces the addons associated with # it .The changes made will be effective from current end # of term. curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkvzp2Yd \ -u {site_api_key}:\ -d plan_id="plan1" \ -d addons[id][0]="sub_ssl" \ -d addons[id][1]="sub_monitor" \ -d addons[quantity][1]=2 \ -d end_of_term="true"
future
subscription. Applicable only for future
subscriptions.0
to have no trial period.terms_to_charge
is inclusive of this new term. See description for the force_term_reset
parameter to learn more about when a subscription term is reset.reactivate
parameter, this is the date/time at which the subscription should be reactivated.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
.true
will have the subscription reset its term to the current date (provided end_of_term
is false). cancelled
subscriptions. When passed as true, the canceled subscription is activated; otherwise subscription changes are made without changing its status
. If not passed, subscription will be activated only if subscription_items
is passed.true
, ignores the hierarchy relationship and uses customer as payment and invoice owner.billing_cycles
or a custom value depending on the site configuration.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.device_session_id
and fraud_merchant_id
as an input to fingerprint
. Here’s a sample to it.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.true
then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to cancel
.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.period
. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.replace_addon_list
. (Addon trial periods must be enabled by Chargebee Support.).Changes the subscription's current term end date. Depending on the "status" of the subscription, "term end date" has different effects.
Tip: To cycle through a couple of billing cycles and test webhooks, you may use this API.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkfbN2Rf/change_term_end \ -u {site_api_key}:\ -d term_ends_at=1601490600
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkfbN2Rf/change_term_end \ -u {site_api_key}:\ -d term_ends_at=1601490600
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
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.
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.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkrVS2Wn/reactivate \ -X POST \ -u {site_api_key}:\ -d invoice_immediately="true" \ -d billing_cycles=4
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkrVS2Wn/reactivate \ -X POST \ -u {site_api_key}:\ -d invoice_immediately="true" \ -d billing_cycles=4
reactivate
parameter, this is the date/time at which the subscription should be reactivated.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.billing_cycles
or a custom value depending on the site configuration.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.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.device_session_id
and fraud_merchant_id
as an input to fingerprint
. Here’s a sample to it.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.
If any subscription changes happen before the end of the current term, these charges will be collected along with it.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkeIw2R1/add_charge_at_term_end \ -u {site_api_key}:\ -d amount=300 \ -d description="Service Charge"
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkeIw2R1/add_charge_at_term_end \ -u {site_api_key}:\ -d amount=300 \ -d description="Service Charge"
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.
If any subscription changes happen before the end of the current term, these charges will be collected along with it.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkfvE2Rn/charge_addon_at_term_end \ -u {site_api_key}:\ -d addon_id="non_recurring_addon" \ -d addon_quantity=3 \ -d addon_unit_price=100
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkfvE2Rn/charge_addon_at_term_end \ -u {site_api_key}:\ -d addon_id="non_recurring_addon" \ -d addon_quantity=3 \ -d addon_unit_price=100
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.
non_renewing
and cancelled
subscriptions.curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2uew22/charge_future_renewals \ -u {site_api_key}:
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
.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.unbilled_charges
. Applicable only when schedule_type
is immediate
.terms_to_charge
.specific_datesCharge on specific dates. For each date, specify the number of billing cycles to charge for. Up to 5 dates can be configured.fixed_intervalsCharge at fixed intervals of time. Specify the number of billing cycles that constitute an interval and the number of days before each interval that the invoice should be generated. Also specify when the schedule should end.remaining_billing_cycles
of the subscription. This parameter is applicable only when fixed_interval_schedule[end_schedule_on]
= after_number_of_intervals
.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_schedule_on]
= specific_date
.schedule_type
is specific_dates.schedule_type
is specific_dates
.Modifies the advance invoicing schedule for a subscription.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2vpB3C/edit_advance_invoice_schedule \ -X POST \ -u {site_api_key}:\ -d schedule_type="specific_dates" \ -d specific_dates_schedule[id][0]="__test__KyVkmQSCX2vwe3Q" \ -d specific_dates_schedule[terms_to_charge][0]=1
remaining_billing_cycles
of the subscription. This parameter is applicable only when fixed_interval_schedule[end_schedule_on]
= after_number_of_intervals
.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_schedule_on]
= specific_date
.schedule_type
is specific_dates.schedule_type
is specific_dates
.Retrieves the advance_invoice_schedule for a subscription. Note that this endpoint is only applicable for schedule_type = specific_dates or fixed_intervals.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2wPg43/retrieve_advance_invoice_schedule \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2wPg43/retrieve_advance_invoice_schedule \ -u {site_api_key}:
Deletes an advance invoicing schedule. When schedule_type = specific_dates, you also have the option of deleting a part of the schedule.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2wFs3l/remove_advance_invoice_schedule \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2wFs3l/remove_advance_invoice_schedule \ -X POST \ -u {site_api_key}:
Regenerates the invoice for the current term of the subscription. The subscription must have status
as active
or non_renewing
. This operation is not allowed when any of the following conditions hold true for the subscription:
status
is not voided
. Returns one of the following depending on the value of invoice_immediately
:
true
: an invoice
object that corresponds to the regenerated invoice. false
: a list of unbilled_charge
objects corresponding to all the unbilled charges created for the current term of the subscription. curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnOuSHufd0ih/regenerate_invoice \ -X POST \ -u {site_api_key}:\ -d invoice_immediately="true"
date_from
and date_to
. Should not be passed without date_from
and date_to
.false
to leave the current term charge for the subscription as unbilled. Once you have done this for all suitable subscriptions of the customer, call Create an invoice for unbilled charges to invoice them.curl https://{site}.chargebee.com/api/v2/subscriptions/import_subscription \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d status="active" \ -d current_term_end=1602095400 \ -d customer[first_name]="John" \ -d customer[last_name]="Doe" \ -d customer[locale]="fr-CA" \ -d customer[phone]="+1-949-999-9999" \ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US" \ -d billing_cycles=5 \ -d addons[id][0]="ssl" \ -d contract_term[action_at_term_end]="renew" \ -d contract_term_billing_cycle_on_renewal=3 \ -d contract_term[contract_start]=1509511210 \ -d contract_term[cancellation_cutoff_period]=3 \ -d contract_term[created_at]=1509511210 \ -d contract_term[total_amount_raised]="900" \ -d contract_term[billing_cycle]=5
curl https://{site}.chargebee.com/api/v2/subscriptions/import_subscription \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d status="active" \ -d current_term_end=1602095400 \ -d customer[first_name]="John" \ -d customer[last_name]="Doe" \ -d customer[locale]="fr-CA" \ -d customer[phone]="+1-949-999-9999" \ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US" \ -d billing_cycles=5 \ -d addons[id][0]="ssl" \ -d contract_term[action_at_term_end]="renew" \ -d contract_term_billing_cycle_on_renewal=3 \ -d contract_term[contract_start]=1509511210 \ -d contract_term[cancellation_cutoff_period]=3 \ -d contract_term[created_at]=1509511210 \ -d contract_term[total_amount_raised]="900" \ -d contract_term[billing_cycle]=5
billing_cycles
or a custom value depending on the site configuration.future
subscription implies the subscription will go into in_trial
state when it starts.null
for future
subscriptions as it is yet to be started.paused
state, it is the date/time when the subscription was paused.true
if you want an invoice to be created for the subscription.active
or non_renewing
status.current_term_start
to current_term_end
.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.total_contract_value
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to cancel
.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.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.check
payment_method
. This parameter should be passed only if the invoice is created for current term.period
. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWkp5t2VV/import_subscription \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d status="in_trial" \ -d trial_end=1602095400 \ -d billing_cycles=5 \ -d addons[id][0]="ssl" \ -d contract_term[action_at_term_end]="renew" \ -d contract_term_billing_cycle_on_renewal=3 \ -d contract_term[contract_start]=1509511210 \ -d contract_term[cancellation_cutoff_period]=3 \ -d contract_term[created_at]=1509511210 \ -d contract_term[total_amount_raised]="900" \ -d contract_term[billing_cycle]=5
curl https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWkp5t2VV/import_subscription \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d status="in_trial" \ -d trial_end=1602095400 \ -d billing_cycles=5 \ -d addons[id][0]="ssl" \ -d contract_term[action_at_term_end]="renew" \ -d contract_term_billing_cycle_on_renewal=3 \ -d contract_term[contract_start]=1509511210 \ -d contract_term[cancellation_cutoff_period]=3 \ -d contract_term[created_at]=1509511210 \ -d contract_term[total_amount_raised]="900" \ -d contract_term[billing_cycle]=5
future
subscription implies the subscription will go into in_trial
state when it starts.null
for future
subscriptions as it is yet to be started.paused
state, it is the date/time when the subscription was paused.billing_cycles
or a custom value depending on the site configuration.true
if you want an invoice to be created for the subscription.active
or non_renewing
status.current_term_start
to current_term_end
.total_contract_value
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to cancel
.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.check
payment_method
. This parameter should be passed only if the invoice is created for current term.state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).state_code
is provided.period
. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.subscription_id
.
For contract terms in active
state, import is only allowed if the associated subscription is active
, in_trial
, future
or non-renewing
.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkogZ2VF/import_contract_term \ -X POST \ -u {site_api_key}:\ -d contract_term[action_at_term_end]="cancel" \ -d contract_term[billing_cycle]=5 \ -d contract_term[contract_start]=1483245610 \ -d contract_term[contract_end]=1493613610 \ -d contract_term[status]="terminated" \ -d contract_term[total_contract_value]="1000"
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkogZ2VF/import_contract_term \ -X POST \ -u {site_api_key}:\ -d contract_term[action_at_term_end]="cancel" \ -d contract_term[billing_cycle]=5 \ -d contract_term[contract_start]=1483245610 \ -d contract_term[contract_end]=1493613610 \ -d contract_term[status]="terminated" \ -d contract_term[total_contract_value]="1000"
billing_cycles
or a custom value depending on the site configuration.total_contract_value
.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
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to renew
.contract_billing_cycle_on_renewal
.action_at_term_end
for the new contract term is set to cancel
.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.Assigns the payment source and sets auto collection state for the subscription.
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.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkqEX2W6/override_billing_profile \ -X POST \ -u {site_api_key}:\ -d payment_source_id="pm___test__KyVnHhSBWkqIK2WD" \ -d auto_collection="on"
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkqEX2W6/override_billing_profile \ -X POST \ -u {site_api_key}:\ -d payment_source_id="pm___test__KyVnHhSBWkqIK2WD" \ -d auto_collection="on"
Deletes the subscription resource.
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.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWknaq2Ui/delete \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWknaq2Ui/delete \ -X POST \ -u {site_api_key}:
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.
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.
If invoice is in the dunning cycle, invoice_dunning_handing allows you to stop or continue dunning.
# pauses the subscription on end of term. curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkqkc2WM/pause \ -X POST \ -u {site_api_key}:\ -d pause_option="end_of_term"
Cancelling a subscription will move the subscription from its current state to Cancelled, and will stop all recurring actions.
You could schedule the cancellation by passing end_of_term parameter as true. If scheduled, the subscription status will be set to non_renewing if it is in active state, until the end of term, and then cancelled. A subscription's state will not change if it is in in_trial state. However, cancellation will be scheduled at the end of the trial.
On subscription cancellation, credits can be issued against current term charges of the subscription by using credit_option_for_current_term_charges. You can choose to either provide no credits, prorate credits for the unused period or issue full credits for the current term charges.
Any unbilled charges present in the subscription can either be invoiced or deleted by specifying unbilled_charges_option. Note that automatic charge will be attempted on the payment method available if the customer has enabled auto-collection. If not, the invoice will be closed as unpaid.
Specifying account_receivables_handling allows you to close invoices of the subscription which have amounts due. The invoices are chosen for payment collection or for writing off the due amount after applying the available credits and excess payments.
If specified as schedule_payment_collection, payment collection for the amount due of past invoices will be attempted. The payment method available will be charged if auto-collection is enabled for the customer, and appropriate payment collection(payment succeeded or payment failed) events will be triggered. If the payment collection fails, no further retries will be made on the invoices. Note: If the invoices of the subscription are consolidated, and any of the subscriptions in the consolidated invoice are cancelled, these invoices will not be selected for collection.
If specified as write_off, the amount due of past invoices will be written-off. Note: If the invoices of the subscription are consolidated, and any of the subscriptions in the consolidated invoice are still active(future, in-trial, active, and non-renewing), these invoices will not be selected for the write-off operation.
Specifying refundable_credits_handling allows you to provide refunds for refundable credits remaining, after they are applied to a subscription’s due invoices. The refund initiated will be asynchronous and the payment refunded event will be triggered on refund success. Note: Consolidated credit notes of the subscription will not be selected for refund.
credit_option_for_current_term_charges
unbilled_charges_option
account_receivables_handling
refundable_credits_handling
end_of_term
or cancel_at
should not be passed when using contract terms; use contract_term_cancel_option
instead. event_based_addons
parameter is used when canceling contract terms 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
.on_event
parameter set to contract_term_termination
Advance charges, if any, will be refunded as credits.
# cancels the subscription after the term ends. curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkekU2RC/cancel \ -X POST \ -u {site_api_key}:\ -d end_of_term="true"
true
if you want to cancel the subscription at the end of the current subscription billing cycle. The subscription status
changes to non_renewing
.end_of_term
is passed as true
.end_of_term
= false
), specify how to provide credits for current term charges. When not provided, the site default is considered.end_of_term
= false
), specify how to handle any unbilled charges. When not provided, the site default is considered.terminate_immediately
immediately does the following:status
to terminated
.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.id
of the event-based addon that represents the termination fee.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.
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.
# resumes a subscription immediately by scheduling payment collection for unpaid # invoices. curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkuL42Xz/resume \ -X POST \ -u {site_api_key}:\ -d resume_option="immediately" \ -d unpaid_invoices_handling="schedule_payment_collection"
device_session_id
and fraud_merchant_id
as an input to fingerprint
. Here’s a sample to it.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.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWktUL2Xh/remove_scheduled_pause \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWktUL2Xh/remove_scheduled_pause \ -X POST \ -u {site_api_key}:
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.
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkty42Xq/remove_scheduled_resumption \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnHhSBWkty42Xq/remove_scheduled_resumption \ -X POST \ -u {site_api_key}: