Subscription represents the recurring items a customer has subscribed to. The recurring items can be - plan, addons. It may also contain the discount items like coupons.
Subscriptions are invoiced at the start of every term based on the recurring items and charged immediately against the customer's credit card if 'auto_collection' is turned 'on', otherwise the resulting invoice will be created as 'Payment Due'.
Note: The maximum number of subscriptions for any given customer (active
or not) is 900.
{
"activated_at": 1517506669,
"created_at": 1517506669,
"current_term_end": 1519925869,
"current_term_start": 1517506669,
"due_invoices_count": 1,
"due_since": 1517506669,
"has_scheduled_changes": false,
"id": "__test__5SK0bLNFRFuBv6r6j",
"object": "subscription",
"plan_id": "no_trial",
"plan_quantity": 1,
"started_at": 1517506669,
"status": "active",
"total_dues": 895
}
due_invoices_count
. total_dues
. 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 explicitly 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
Note: For the sites created before 1st Mar 2014, customer's billing address and 'vat_number' will be replaced automatically whenever the associated card gets updated. i.e existing values for billing address and 'vat_number' will be cleared and the new values will be set. This behaviour is changed now - The VAT number should always be passed along billing address and not with card address. Both the addresses have to be dealt separately.
Billing Address attributes shall be explicitly passed for customers paying offline(Cash, Check, Bank Transfer etc).
The Shipping Address is significant for the Customized Tax option, because tax calculations will be based on this address. For customers without Shipping Address, Billing Address details will be used to calculate taxes. If neither of the addresses are available for a customer, taxes will not be calculated for him/her.
# creates a subscription with customer information and billing details. curl https://{site}.chargebee.com/api/v1/subscriptions \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d customer[first_name]="John" \ -d customer[last_name]="Doe" \ -d customer[email]="john@user.com" \ -d customer[auto_collection]="OFF" \ -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"
start_date
cannot be earlier than 14th February.The id of the coupon. For validating the coupon code provided by the user , use the following codes in combination with the param attribute in the error response.
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/v1/customers/__test__5SK0bLNFRFuBvDL6q/subscriptions \ -u {site_api_key}:\ -d plan_id="no_trial" \ -d start_date=1548178669 \ -d shipping_address[first_name]="Mark" \ -d shipping_address[last_name]="Henry" \ -d shipping_address[company]="chargebee"
start_date
cannot be earlier than 14th February.The id of the coupon. For validating the coupon code provided by the user , use the following codes in combination with the param attribute in the error response.
curl https://{site}.chargebee.com/api/v1/subscriptions \ -G \ -u {site_api_key}:\ --data-urlencode limit=2
curl https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuBvQU7D/subscriptions \ -G \ -u {site_api_key}:\ --data-urlencode limit=3
curl https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBwQA9L \ -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/v1/subscriptions/__test__5SK0bLNFRFuBwSh9S/retrieve_with_scheduled_changes \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBw1g8Z/remove_scheduled_changes \ -X POST \ -u {site_api_key}:
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/v1/subscriptions/__test__5SK0bLNFRFuBvxO8Q/remove_scheduled_cancellation \ -X POST \ -u {site_api_key}:
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 billed a total of $7.50 immediately. Calculation will be as follows:
Prorated Charge(New Plan) | $15.00 |
Prorated Credit(Old Plan) for unused period | ($7.50) |
Total prorated amount | $7.50 |
Downgrading will result in credit being created which will be applied when the subscription is charged on start of the next term.
Billing Cycle: The billing period for a subscription does not change if the plans intervals of both old and new are same. However, if a customer changes to a plan that has different billing interval(say monthly to yearly), the billing period is reset. Customer is charged immediately for the modified subscription after applying credit for the unused period for the old subscription.
Card and VAT number Input: If they are passed, corresponding Billing Address attributes and vat_number will be replaced. i.e existing values for Billing Address and 'vat_number' will be cleared and the new values will be set.
If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.
Advance charges, if any, will be refunded as credits and a new invoice will be generated on renewal.
# 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/v1/subscriptions/__test__5SK0bLNFRFuBwXZ9h \ -u {site_api_key}:\ -d plan_id="plan1" \ -d end_of_term=true \ -d addons[id][0]="sub_ssl" \ -d addons[id][1]="sub_monitor" \ -d addons[quantity][1]=2
status
is future
, in_trial
, or cancelled
. Also, the value must not be earlier than changes_scheduled_at
or start_date
. Note: This parameter can be backdated (set to a value in the past) only when the subscription is in cancelled
or in_trial
status
. Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end
is backdated, the subscription immediately goes into active
or non_renewing
status. Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
Note:
When the coupon ID contains a special character; for example: #
, the API returns an error.
Make sure that you encode the coupon ID in the path parameter before making an API call.
true
: Prorated credits or charges are created as applicable for this change.false
: The subscription is changed without creating any credits or charges.For further changes within the same billing term, when prorate
is set to true
, credits are not created when all the conditions below hold true:
An immediate previous change was made
prorate
set to false
andChanges the subscription's current term end date. Depending on the "status" of the subscription, "term end date" has different effects.
When changing the current term there won't be any prorations calculated. All future renewals(if applicable) of the subscription will be shifted based on the new date.
Tip: To cycle through a couple of billing cycles and test webhooks, you may use this API.
Advance charges, if any, will be refunded as credits and a new invoice will be generated on renewal.
curl https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBuqE6C/change_term_end \ -u {site_api_key}:\ -d term_ends_at=1548700200
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/v1/subscriptions/__test__5SK0bLNFRFuBvia7x/reactivate \ -u {site_api_key}:\ -d billing_cycles=4
in_trial
status
and the trial period ends at the date provided. The value must not be earlier than reactivate_from
. Note: This parameter can be backdated (set to a value in the past) only when reactivate_from
has been backdated. Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end
is backdated, the subscription immediately goes into active
or non_renewing
status. 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/v1/subscriptions/__test__5SK0bLNFRFuBuUd5f/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/v1/subscriptions/__test__5SK0bLNFRFuBuwc6K/charge_addon_at_term_end \ -u {site_api_key}:\ -d addon_id="non_recurring_addon" \ -d addon_quantity=3
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/v1/subscriptions/__test__5SK0bLNFRFuBvJV6x/delete \ -X POST \ -u {site_api_key}:
Cancelling a subscription will move the current state of the subscription to the cancelled state and will stop all recurring actions.
You could schedule the cancellation by passing end_of_term parameter as true. If scheduled, the subscription status will be set to non_renewing if it is in active state until the end of term and then cancelled. Subscription's state will not change if it is in in_trial state. However, cancellation will be scheduled at the trial end date.
While cancelling a subscription, we try to collect all pending amount against the current and old invoices. No refund for the unused period is processed (let us know if you need have specific refund scenarios).
If the collection of pending charges fails while cancelling, it will still be moved to cancelled status. We will continue to retry collecting the payment based on the configured retry settings until it is manually overridden.
Advance charges, if any, will be refunded as credits.
# cancels the subscription after the term ends. curl https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuBucK5q/cancel \ -u {site_api_key}:\ -d end_of_term=true