POST /subscriptions/{subscription-id}/import_contract_term

Imports an active or historical contract term for a subscription.

Use this operation to import contract terms when migrating subscriptions from another billing system, or to add historical contract term data for existing subscriptions. You can import both active contract terms (currently running) and historical contract terms (completed, canceled, or terminated).

Prerequisites & Constraints

The Contract Terms feature must be enabled on the site.
The Multi-Frequency Billing feature must not be enabled for the site.
The subscription must have a fixed billing cycle (the remaining_billing_cycles must be set).
The contract term period must not overlap with any existing contract terms for the subscription.

Impacts

Contract term

A new contract_term resource is created and associated with the subscription.
For active contract terms:
the total_contract_value is calculated as the sum of the contract estimate and the total_amount_raised parameter.
The contract_end date is calculated based on the contract_start date and the billing_cycle parameter.

Implementation Notes

Check the subscription's remaining_billing_cycles attribute. If it is not set, the subscription is set to forever renewal. Update the subscription to a fixed billing cycle before importing a contract term.
Check for existing contract terms for the subscription. Ensure that the the contract_start and contract_end dates don't overlap with any existing contract term for the subscription.

Servers

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

Path parameters

Name	Type	Required	Description
`subscription-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 Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid 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 Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`contract_term`	Object	No	Parameters for contract_term
`contract_term.id`	String	No	Unique identifier for the contract term in the site. Default value If not provided, a unique identifier is automatically generated.
`contract_term.contract_start`	Integer	No	The start date of the contract term. Constraints Must be less than `contract_end`. For active contract terms, cannot be a future date unless the subscription `status` is `future`. For historical contract terms, must be a past date. Cannot be less than `created_at`. Must not overlap with existing contract terms for the subscription.
`contract_term.total_contract_value`	Integer	No	The sum of the totals of all invoices raised as part of the contract term. For active contract terms, this is a predicted value calculated as the sum of the contract estimate and `total_amount_raised`. Required if The contract term `status` is not `active` (for historical contract terms). Constraints Should not be sent when the contract term `status` is `active` (it is calculated automatically). Default value: 0
`contract_term.total_contract_value_before_tax`	Integer	No	The total amount of revenue expected to be generated from the contract term, calculated as the sum of all invoices raised during the term, excluding taxes. For active contract terms, this is calculated as the sum of the contract estimate (before tax) and `total_amount_raised_before_tax`. Required if The contract term `status` is not `active` and pre-tax TCV is enabled on the site (for historical contract terms). Constraints Should not be sent when the contract term `status` is `active` (it is calculated automatically). Default value: 0
`contract_term.total_amount_raised_before_tax`	Integer	No	The amount raised for the contract term up to the time of importing the subscription, excluding tax. This amount is added to the contract estimate to calculate the `total_contract_value_before_tax` for active contract terms. Required if The contract term `status` is `active` and pre-tax TCV is enabled on the site. Constraints Should not be sent when the contract term `status` is not `active`. Default value: 0
`contract_term.action_at_term_end`	String	No	Action to be taken when the contract term completes. * evergreen - The contract term completes and the subscription continues to renew without a new contract term. * renew_once - The contract term completes and a new contract term is started for the number of billing cycles specified in `contract_term_billing_cycle_on_renewal`. The `action_at_term_end` for the new contract term is set to `cancel`, so the subscription is canceled when the new contract term completes. * cancel - The contract term completes and the subscription is canceled. * renew - The contract term completes and a new contract term is started for the number of billing cycles specified in `contract_term_billing_cycle_on_renewal`. The `action_at_term_end` for the new contract term is set to `renew`. Valid values: `"renew_once"` `"evergreen"` `"cancel"` `"renew"` Default value: "renew"
`contract_term.status`	String	No	Current status of the contract term. Use `active` for currently running contract terms, or `completed`, `cancelled`, or `terminated` for historical contract terms. * active - An actively running contract term. Prerequisite The subscription `status` must be `future`, `in_trial`, `active`, or `non-renewing`. * completed - The contract term has run its full duration. * cancelled - The contract term was ended because a change in the subscription caused a subscription term reset, or the subscription was canceled due to non-payment. * terminated - The contract term was terminated ahead of completion. Valid values: `"terminated"` `"active"` `"completed"` `"cancelled"`
`contract_term.created_at`	Integer	No	The date when the contract term was created. Required if The contract term `status` is `active`. Constraints For active contract terms, cannot be a future date unless the subscription `status` is `future`. Must be less than or equal to `contract_start`. Default value For historical contract terms, defaults to `contract_start` if not provided.
`contract_term.total_amount_raised`	Integer	No	The amount raised for the contract term up to the time of importing the subscription. This amount is added to the contract estimate to calculate the `total_contract_value` for active contract terms. Required if The contract term `status` is `active`. Constraints Should not be sent when the contract term `status` is not `active`. Default value: 0
`contract_term.contract_end`	Integer	No	The end date of the contract term. Required if The contract term `status` is not `active` (for historical contract terms). Constraints Should not be sent when the contract term `status` is `active` (it is calculated automatically). Must be greater than `contract_start`. Must be a past date. Must not overlap with existing contract terms for the subscription.
`contract_term.cancellation_cutoff_period`	Integer	No	The number of days before `contract_end` during which the customer is barred from canceling the contract term. The customer can 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. Required if The `action_at_term_end` is `renew` or `renew_once`. Constraints Must be less than the duration of the contract term (in days). Should not be sent when `action_at_term_end` is `cancel` or `evergreen`.
`contract_term.billing_cycle`	Integer	No	The number of billing cycles of the subscription that the contract term covers. Required if The contract term `status` is `active`. Constraints For active contract terms, must be greater than the subscription's `remaining_billing_cycles` when the subscription `status` is `active` or `non-renewing`. Default value For historical contract terms, defaults to `1` if not provided.
`contract_term_billing_cycle_on_renewal`	Integer	No	The number of billing cycles the new contract term should run for when the contract term renews. This value is used when `action_at_term_end` is `renew` or `renew_once`. Constraints Should not be sent when `action_at_term_end` is `cancel` or `evergreen`. Default value Defaults to the value of `billing_cycle` or a custom value depending on the site configuration.

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.