# Contract terms

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


Subscriptions can run indefinitely or they may run for a fixed number of billing cycles. Subscription can have "contract terms", which define a lock-in period on the subscription for a certain number of billing cycles. This prevents the subscription from being canceled by the customer when it is within the contract term.

The **contract term** resource described below defines the properties of this lock-in period. This includes the [number of billing cycles](/docs/api/contract_terms/contract_term-object#remaining_billing_cycles), the [total contract value](/docs/api/contract_terms/contract_term-object#total_contract_value), the [action to be taken](/docs/api/contract_terms/contract_term-object#action_at_term_end) at the end of the contract term, and so on. To allow for exceptions, you also have the option of terminating an [`active`](/docs/api/contract_terms/contract_term-object#status) contract term and charging a [termination fee](/docs/api/contract_terms).

A contract term starts in the `active` state and ends in the `completed` state. If the contract was canceled due to non-payment or other reasons, it can end in the `canceled` or `terminated` state. A given contract term is always associated with one, and only one subscription. A subscription, however, can be associated with only one `active` contract term. Over time, a subscription can be associated with several non-`active` contract terms. The `active` contract term for a subscription is available as an [object](/docs/api/subscriptions/subscription-object#contract_term) within the subscription.

To enable and configure contract terms, follow these steps in the Chargebee UI:

1.  Click **Settings** on the left navigation.
2.  Click **Configure Chargebee**.
3.  Under **Billing**, click **Contract Terms**.
4.  Enable and configure the feature as needed.

Once contract terms have been configured, the following actions can be performed using the API:

-   **Define a contract term** for a subscription and **set renewal options** for the contract term. The following endpoints support this:
    
-   [Create a subscription](/docs/api/subscriptions/create-subscription-for-items)
-   [Update a subscription](/docs/api/subscriptions/update-subscription-for-items)
-   [Reactivate a subscription](/docs/api/subscriptions/reactivate-a-subscription)
-   [Create a subscription ramp](/docs/api/ramps/create-a-ramp)
-   [Update a subscription ramp](/docs/api/ramps/update-a-subscription-ramp)
-   **Retrieving** a historical record of all contract terms for a subscription can be done via the following endpoint:
    
-   [List contract terms for a subscription](/docs/api/subscriptions/list-contract-terms-for-a-subscription)
-   **Canceling a contract term** can be done via the following endpoints:
    
-   [Update a subscription](/docs/api/subscriptions/update-subscription-for-items)
-   [Cancel a subscription](/docs/api/subscriptions/cancel-subscription-for-items)
-   [Update a subscription ramp](/docs/api/ramps/update-a-subscription-ramp)

#### Including a termination fee[](#including-a-termination-fee)

When a contract is canceled mid-term, you can set a termination fee to be levied. Here's how:

1.  [Create](/docs/api/item_prices/create-an-item-price) an item price for an item of [type](/docs/api/items/item-object#type) `charge` with [price](/docs/api/item_prices/create-an-item-price#price) set to the termination fee.
2.  Do one of the following:

-   [Attach the charge-item to a plan](/docs/api/attached_items/create-an-attached-item), setting the `charge_on_event` parameter to `contract_termination`. OR
-   [Include the charge-item price on a subscription](/docs/api/subscriptions/create-subscription-for-items), setting the `subscription_items[charge_on_event][i]` parameter to `contract_termination`.

Once the above steps are done, the termination fee will be charged automatically if you [terminate the contract in the middle of its term](/docs/api/subscriptions/cancel-subscription-for-items#contract_term_cancel_option).

## Sample Contract term

```json
{
  "action_at_term_end": "renew",
  "billing_cycle": 12,
  "cancellation_cutoff_period": 0,
  "contract_end": 1548974761,
  "contract_start": 1517438761,
  "created_at": 1517438761,
  "id": "__test__3Nl7o66Rt41dR98T",
  "remaining_billing_cycles": 11,
  "status": "active",
  "total_contract_value": 10740
}
```

## Contract terms attributes

## Input Parameters

- `id` (required, string, max chars=50)
  Id that uniquely identifies the contract term in the site.

- `status` (required, enumerated string)
  Current status of contract
  Possible enum values:
    - `active`
      An actively running contract term.
    - `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](/docs/api/v2/pcv-1/subscriptions/update-a-subscription#force_term_reset).
      
      -   the subscription was cancelled due to non-payment.
    - `terminated`
      The contract term was terminated ahead of completion.

- `contract_start` (required, timestamp(UTC) in seconds)
  The start date of the contract term

- `contract_end` (required, timestamp(UTC) in seconds)
  The end date of the contract term

- `billing_cycle` (required, integer, min=0)
  The number of billing cycles of the subscription that the contract term is for.

- `action_at_term_end` (required, enumerated string, default=renew)
  Action to be taken when the contract term completes.
  Possible enum values:
    - `renew`
      -   Contract term completes and a new contract term is started for the number of billing cycles specified in [`contract_billing_cycle_on_renewal`](/docs/api/v2/pcv-1/subscriptions/create-subscription-for-customer#contract_term_billing_cycle_on_renewal).
      -   The `action_at_term_end` for the new contract term is set to `renew`.
    - `evergreen`
      Contract term completes and the subscription renews.
    - `cancel`
      Contract term completes and subscription is canceled.
    - `renew_once`
      Used when you want to renew the contract term just once. Does the following: - Contract term completes and a new contract term is started for the number of billing cycles specified in [`contract_billing_cycle_on_renewal`](/docs/api/v2/pcv-1/subscriptions/create-subscription-for-customer#contract_term_billing_cycle_on_renewal).
      
      -   The `action_at_term_end` for the new contract term is set to `cancel`.

- `total_contract_value` (required, in cents, default=0, min=0)
  The sum of the [totals](/docs/api/invoices/invoice-object#total) of all the invoices raised as part of the contract term. For `active` contract terms, this is a predicted value. The value depends on the [type of currency](/docs/api/contract_terms). If the subscription was [imported](/docs/api/contract_terms) with the contract term, then this value includes the value passed for `total_amount_raised` .

- `total_contract_value_before_tax` (required, in cents, default=0, min=0)
  It refers to the total amount of revenue that is expected to be generated from a specific contract term, calculated as the sum of all invoices raised during the term, regardless of payment status. It is based on past performance and the specified currency in the contract. If the subscription was imported, the value for `total_amount_raised_before_tax` is included in the calculation of the total contract value before tax. It's important to note that this value excludes any applicable taxes.

- `cancellation_cutoff_period` (optional, integer)
  The number of days before [`contract_end`](/docs/api/contract_terms/contract_term-object#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.

- `created_at` (required, timestamp(UTC) in seconds)
  The date when the contract term was created.

- `subscription_id` (required, string, max chars=50)
  The [Id](/docs/api/subscriptions/subscription-object#id) of the subscription that this contract term is for.

- `remaining_billing_cycles` (optional, integer, min=0)
  The number of subscription billing cycles remaining after the current one for the contract term. This attribute is only returned for `active` contract terms.