Note: This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.
Creates a new subscription along with the customer. You can attach a plan, plan quantity, one or more addons and coupon while creating this subscription.
Future Subscriptions
If the start_date is specified, the subscription will be created in 'future' state (.ie, instead of starting immediately it will be scheduled to start at the specified 'start_date'). Besides if 'trial' is specified (plan configuration or specified explicitly using trial_end), the subscription will go into 'trial' state when it starts. Otherwise it will directly become 'active' when it starts.
Trial Period
If the plan has trial period or if the trial_end is specified explicitly, the subscription will be created in 'in_trial' state.
If the card details are passed, it is not charged until the end of the trial period. Incase you need to verify the card you could enable the 'card verification option' in the gateway settings.
Invoice
If the plan does not have a trial period and if any of the recurring items has charges, then a invoice would be raised immediately. If 'auto_collection' is turned 'on', then card attributes are mandatory and subscription will be created only if the payment was successful.
Card details
Passing card details to this API involves PCI liability at your end as sensitive card information passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable
- If you are using Stripe gateway, you can use Stripe.js with your checkout form. Take a look at this Stripe tutorial for more details.
- If you are using Braintree gateway, you can use Braintree.js with your checkout form. Please refer this tutorial for more details. You can also use our Hosted Pages based integration.
Billing Address
- The Billing Address is significant especially when EU VAT or Customized Tax options are in use, because tax calculations will be based on this address.
- In the case of EU VAT, for customers without Billing Address, taxes will not be included.
- In the case of Customized Tax option, the billing address will be used to determine tax if shipping address is not available for the customer. If both addresses are not available, tax calculation will not happen.
Note: For the sites created before 1st Mar 2014, customer's billing address and 'vat_number' will be replaced automatically whenever the associated card gets updated. i.e existing values for billing address and 'vat_number' will be cleared and the new values will be set. This behaviour is changed now - The VAT number should always be passed along billing address and not with card address. Both the addresses have to be dealt separately.
Billing Address attributes shall be explicitly passed for customers paying offline(Cash, Check, Bank Transfer etc).
Shipping Address
The Shipping Address is significant for the Customized Tax option, because tax calculations will be based on this address. For customers without Shipping Address, Billing Address details will be used to calculate taxes. If neither of the addresses are available for a customer, taxes will not be calculated for him/her.
Related Tutorials
Sample Request
URL Format
Input Parameters
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
The time at which the trial ends for this subscription. Can be specified to override the default trial period.If '0' is passed, the subscription will be activated immediately.
Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
The date/time at which the subscription is to start. If not provided, the subscription starts immediately. You can provide a value in the past as well. This is called backdating the subscription creation and is done when the subscription has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
- Backdating is enabled for subscription creation operations.
- The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is typically the day of the month by which the accounting for the previous month must be closed.
- The date is not more than duration X into the past, where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April,
start_datecannot 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.
- resource_not_found : Returned if the coupon is not present.
- resource_limit_exhausted : Returned if the coupon has expired or the maximum redemption for the coupon has already been reached.
- invalid_request : Returned if the coupon is not applicable for the particular plan/addon.
The IP address of the user. Used primarly in Refersion integration. Refersion uses this field to track/log affiliate subscription.
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.
A set of key-value pairs stored as additional information for the subscription. Learn more .
Returns
Resource object representing subscription
Resource object representing customer
Resource object representing card
Resource object representing invoice