API Version
Product Catalog
Library

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, the total contract value, the action to be taken at the end of the contract term, and so on. To allow for exceptions, you also have the option of terminating an active contract term and charging a termination fee.

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

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 }

API Index URL GET

https://{site}.chargebee.com/api/v2/contract_terms

Model Class

id
string, max chars=50
Id that uniquely identifies the contract term in the site.
status
enumerated string
Current status of contract
Possible values are
activeAn actively running contract term.completedThe contract term has run its full duration.cancelledThe contract term was ended because: terminatedThe contract term was terminated ahead of completion.
Show all values[+]
contract_start
timestamp(UTC) in seconds
The start date of the contract term
contract_end
timestamp(UTC) in seconds
The end date of the contract term
billing_cycle
integer, min=0
The number of billing cycles of the subscription that the contract term is for.
action_at_term_end
enumerated string, default=renew
Action to be taken when the contract term completes.
Possible values are
renew
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.
  • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed 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.
  • The action_at_term_end for the new contract term is set to cancel.
  • Show all values[+]
    total_contract_value
    in cents, default=0, min=0
    The sum of the totals 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. If the subscription was imported with the contract term, then this value includes the value passed for total_amount_raised.
    total_contract_value_before_tax
    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, 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
    timestamp(UTC) in seconds
    The date when the contract term was created.
    subscription_id
    string, max chars=50
    The 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.
    id id
    string, max chars=50
    Id that uniquely identifies the contract term in the site.
    status status
    enumerated string
    Current status of contract
    contract_start contract_start
    timestamp(UTC) in seconds
    The start date of the contract term
    contract_end contract_end
    timestamp(UTC) in seconds
    The end date of the contract term
    billing_cycle billing_cycle
    integer, min=0
    The number of billing cycles of the subscription that the contract term is for.
    action_at_term_end action_at_term_end
    enumerated string, default=renew
    Action to be taken when the contract term completes.
    total_contract_value total_contract_value
    in cents, default=0, min=0
    The sum of the totals 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. If the subscription was imported with the contract term, then this value includes the value passed for total_amount_raised.
    total_contract_value_before_tax total_contract_value_before_tax
    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 cancellation_cutoff_period
    optional, integer
    The number of days before 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 created_at
    timestamp(UTC) in seconds
    The date when the contract term was created.
    subscription_id subscription_id
    string, max chars=50
    The Id of the subscription that this contract term is for.
    remaining_billing_cycles 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.