POST /customers/{customer-id}/subscriptions

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 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.

Servers

{protocol}://{site}.{environment}:{port}/api/v1
{protocol}://{site}-test.{environment}:{port}/api/v1

Path parameters

Name	Type	Required	Description
`customer-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Possible values: `"all-disabled"`
`chargebee-event-actions`	String	No	skip all actions to be done on the events Possible values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header `chargebee-request-origin-user` is ignored.
`chargebee-event-email`	String	No	skip only emails Possible values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`shipping_address`	Object	No	Parameters for shipping_address
`shipping_address.first_name`	String	No	The first name of the contact.
`shipping_address.state`	String	No	The state/province name. Is set by Chargebee automatically for US, Canada and India If `state_code` is provided.
`shipping_address.city`	String	No	The name of the city.
`shipping_address.line2`	String	No	Address line 2
`shipping_address.line1`	String	No	Address line 1
`shipping_address.email`	String	No	The email address.
`shipping_address.last_name`	String	No	The last name of the contact.
`shipping_address.company`	String	No	The company name.
`shipping_address.line3`	String	No	Address line 3
`shipping_address.state_code`	String	No	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`).
`shipping_address.zip`	String	No	Zip or postal code. The number of characters is validated according to the rules specified here.
`shipping_address.phone`	String	No	The phone number.
`shipping_address.country`	String	No	The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code. Note : If you enter an invalid country code, the system will return an error. Brexit If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then `XI` (the code for United Kingdom -- Northern Ireland) is available as an option.
`po_number`	String	No	Purchase order number for this subscription.
`meta_data`	Object	No	A set of key-value pairs stored as additional information for the subscription. [Learn more](./#meta_data).
`payment_intent`	Object	No	Parameters for payment_intent
`payment_intent.id`	String	No	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.
`payment_intent.gateway_account_id`	String	No	The gateway account used for performing the 3DS flow.
`payment_intent.gw_token`	String	No	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.
`payment_intent.reference_id`	String	No	Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
`plan_id`	String	Yes	Identifier of the plan for this subscription.
`invoice_notes`	String	No	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.
`billing_cycles`	Integer	No	Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
`id`	String	No	A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
`start_date`	Integer	No	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_date` cannot be earlier than 14th February. .
`coupon`	String	No	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.
`trial_end`	Integer	No	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.
`plan_quantity`	Integer	No	Plan quantity for this subscription. Default value: 1
`addons`	Object	No	Parameters for addons
`addons.id[]`	Array	No	Identifier of the addon. Multiple addons can be passed.
`addons.quantity[]`	Array	No	Quantity of the addon. Applicable for addons with `pricing_model` other than `flat_fee`.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.