Subscriptions

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Resource object representing unbilled_charge.
optional

Returns a list of subscriptions meeting all the conditions specified in the filter parameters below.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     --data-urlencode item_id[in]="["basic"]"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     --data-urlencode item_id[in]="["basic"]"

Sample Response [ JSON ]

{
    "list": [
        {
            "customer": {
                "allow_direct_debit": false,
                "auto_collection": "off",
                "card_status": "no_card",
                "created_at": 1612890919,
                "deleted": false,
                "excess_payments": 0,
                "first_name": "John",
                "id": "__test__8asukSOXdvg4PD",
                "last_name": "Doe",
                "net_term_days": 0,
                "object": "customer",
                "pii_cleared": "active",
                "preferred_currency_code": "USD",
                "promotional_credits": 0,
                "refundable_credits": 0,
                "resource_version": 1612890919000,
                "taxability": "taxable",
                "unbilled_charges": 0,
                "updated_at": 1612890919
            },
            "subscription": {
                "activated_at": 1612890920,
                "billing_period": 1,
                "billing_period_unit": "month",
                "created_at": 1612890920,
                "currency_code": "USD",
                "current_term_end": 1615310120,
                "current_term_start": 1612890920,
                "customer_id": "__test__8asukSOXdvg4PD",
                "deleted": false,
                "due_invoices_count": 1,
                "due_since": 1612890920,
                "has_scheduled_changes": false,
                "id": "__test__8asukSOXdvliPG",
                "mrr": 0,
                "next_billing_at": 1615310120,
                "object": "subscription",
                "remaining_billing_cycles": 1,
                "resource_version": 1612890920000,
                "started_at": 1612890920,
                "status": "active",
                "subscription_items": [
                    {
                        "amount": 1000,
                        "billing_cycles": 1,
                        "free_quantity": 0,
                        "item_price_id": "basic-USD",
                        "item_type": "plan",
                        "object": "subscription_item",
                        "quantity": 1,
                        "unit_price": 1000
                    },
                    {..}
                ],
                "total_dues": 1100,
                "updated_at": 1612890920
            }
        },
        {..}
    ],
    "next_offset": "[\"1612890918000\",\"230000000081\"]"
}

URL Format GET

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

limit

The number of resources to be returned.
optional, integer, default=10, min=1, max=100

offset

Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
optional, string, max chars=1000

include_deleted

Indicates whether to include deleted objects in the list. The deleted objects have the attribute deleted as true.
optional, boolean, default=false

sort_by[<sort-order>]

Sorts based on the specified attribute.
Supported attributes : created_at, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
optional, string filter

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is_not] = "8gsnbYfsMLds"
optional, string filter

customer_id[<operator>]

Identifier of the customer with whom this subscription is associated.
Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is] = "8gsnbYfsMLds"
optional, string filter

item_id[<operator>]

The plan item code.
Supported operators : is, is_not, starts_with, in, not_in

Example → item_id[is] = "silver"
optional, string filter

item_price_id[<operator>]

The plan item price code.
Supported operators : is, is_not, starts_with, in, not_in

Example → item_price_id[is_not] = "silver-USD-monthly"
optional, string filter

status[<operator>]

Current state of the subscription. Possible values are : future, in_trial, active, non_renewing, paused, cancelled.
Supported operators : is, is_not, in, not_in

Example → status[is] = "active"
optional, enumerated string filter

cancel_reason[<operator>]

The reason for canceling the subscription. Set by Chargebee automatically. Possible values are : not_paid, no_card, fraud_review_failed, non_compliant_eu_customer, tax_calculation_failed, currency_incompatible_with_gateway, non_compliant_customer.
Supported operators : is, is_not, in, not_in, is_present

Example → cancel_reason[is] = "not_paid"
optional, enumerated string filter

cancel_reason_code[<operator>]

remaining_billing_cycles[<operator>]

When the subscription is not on a contract term: this value is the number of billing cycles remaining after the current cycle, at the end of which, the subscription cancels.
When the subscription is on a contract term: this value is the number of billing cycles remaining in the contract term after the current billing cycle.

.
Supported operators : is, is_not, lt, lte, gt, gte, between, is_present

Example → remaining_billing_cycles[is] = "3"
optional, integer filter

created_at[<operator>]

The time at which the subscription was created.
Supported operators : after, before, on, between

Example → created_at[on] = "1435054328"
optional, timestamp(UTC) in seconds filter

activated_at[<operator>]

Time at which the subscription status last changed to active. For example, this value is updated when an in_trial or cancelled subscription activates.
Supported operators : after, before, on, between, is_present

Example → activated_at[on] = "1435054328"
optional, timestamp(UTC) in seconds filter

next_billing_at[<operator>]

The date/time at which the next billing for the subscription happens. This is usually right after current_term_end unless multiple subscription terms were invoiced in advance using the terms_to_charge parameter.
Supported operators : after, before, on, between

Example → next_billing_at[before] = "1435054328"
optional, timestamp(UTC) in seconds filter

cancelled_at[<operator>]

Time at which subscription was cancelled or is set to be cancelled.
Supported operators : after, before, on, between

Example → cancelled_at[on] = "1435054328"
optional, timestamp(UTC) in seconds filter

has_scheduled_changes[<operator>]

If true, there are subscription changes scheduled on next renewal. Possible values are : true, false
Supported operators : is

Example → has_scheduled_changes[is] = "true"
optional, boolean filter

updated_at[<operator>]

To filter based on updated_at. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by input parameter as updated_at for a faster response.
Supported operators : after, before, on, between

Example → updated_at[on] = "1243545465"
optional, timestamp(UTC) in seconds filter

offline_payment_method[<operator>]

The preferred offline payment method for the subscription. Possible values are : no_preference, cash, check, bank_transfer, ach_credit, sepa_credit.
Supported operators : is, is_not, in, not_in

Example → offline_payment_method[is] = "cash"
optional, enumerated string filter

auto_close_invoices[<operator>]

Set to false to override for this subscription, the site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute has a higher precedence than the same attribute at the customer level. Possible values are : true, false
Supported operators : is

Example → auto_close_invoices[is] = "true"
optional, boolean filter

create_pending_invoices[<operator>]

You can also set this to true explicitly using the create/update subscription operations. This is useful in the following scenarios:

When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
When you need to inspect all charges before closing invoices for this subscription.

Applicable only when Metered Billing is enabled for the site

. Possible values are : true, false
Supported operators : is

Example → create_pending_invoices[is] = "true"
optional, boolean filter

override_relationship[<operator>]

If true, ignores the hierarchy relationship and uses customer as payment and invoice owner. Possible values are : true, false
Supported operators : is

Example → override_relationship[is] = "false"
optional, boolean filter

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

next_offset

This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000

Retrieves a list of contract term resources for the subscription specified in the path.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdty0Mv/contract_terms \
     -G  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdty0Mv/contract_terms \
     -G  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"list": [
    {"contract_term": {
        "action_at_term_end": "renew",
        "billing_cycle": 6,
        "cancellation_cutoff_period": 0,
        "contract_end": 1628529313,
        "contract_start": 1612890913,
        "created_at": 1612890913,
        "id": "__test__8asukSOXdty7Mw",
        "object": "contract_term",
        "remaining_billing_cycles": 5,
        "status": "active",
        "total_contract_value": 6600
    }},
    {..}
]}

URL Format GET

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

limit

The number of resources to be returned.
optional, integer, default=10, min=1, max=100

offset

contract_term

Resource object representing contract_term.
always returned

next_offset

This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000

Returns a list of discounts currently attached to the subscription given by {subscription_id}. The list is sorted by date of creation, in descending order.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8at0iSK6IPu41q/discounts \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8at0iSK6IPu41q/discounts \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

{"list": [
    {"discount": {
        "amount": 100,
        "applied_count": 1,
        "apply_on": "invoice_amount",
        "created_at": 1608822300,
        "currency_code": "USD",
        "duration_type": "forever",
        "id": "__test__8at0iSK6IPuW1r",
        "invoice_name": "__test__8at0iSK6IPuW1r",
        "object": "discount",
        "type": "fixed_amount"
    }},
    {..}
]}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/discounts

limit

The number of resources to be returned.
optional, integer, default=10, min=1, max=100

offset

discount

Resource object representing discount.
always returned

next_offset

This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
optional, string, max chars=1000

Retrieves a subscription.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXe0W3SU \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXe0W3SU \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890938,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXe0QYSR",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890938000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890938
    },
    "subscription": {
        "activated_at": 1612890938,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890938,
        "currency_code": "USD",
        "current_term_end": 1615310138,
        "current_term_start": 1612890938,
        "customer_id": "__test__8asukSOXe0QYSR",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890938,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXe0W3SU",
        "mrr": 0,
        "next_billing_at": 1615310138,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890938000,
        "started_at": 1612890938,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890938
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Sample admin console URL

https://{site}.chargebee.com/admin-console/subscriptions/123x

Retrieves a subscription with the scheduled changes applied.
Note: Only the following attributes are changed

item_id
item_price_id
billing_period
billing_period_unit
remaining_billing_cycles
coupons

Other attributes such as status, next_billing_at are not changed and will reflect the current subscription values.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXe0ksSf/retrieve_with_scheduled_changes \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXe0ksSf/retrieve_with_scheduled_changes \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890939,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXe0g2Sc",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890939000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890939
    },
    "subscription": {
        "activated_at": 1612890939,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890939,
        "currency_code": "USD",
        "current_term_end": 1615310139,
        "current_term_start": 1612890939,
        "customer_id": "__test__8asukSOXe0g2Sc",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890939,
        "has_scheduled_changes": true,
        "id": "__test__8asukSOXe0ksSf",
        "item_tiers": [],
        "mrr": 0,
        "next_billing_at": 1615310139,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890940000,
        "started_at": 1612890939,
        "status": "active",
        "subscription_items": [
            {
                "amount": 8000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 4,
                "unit_price": 2000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890940
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/retrieve_with_scheduled_changes

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Removes the subscription changes scheduled on next renewal. Advance charges, if any, will be refunded as credits and a new invoice will be generated on renewal.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdyTgRH/remove_scheduled_changes \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdyTgRH/remove_scheduled_changes \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890930,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdyOjRE",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890930000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890930
    },
    "subscription": {
        "activated_at": 1612890930,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890930,
        "currency_code": "USD",
        "current_term_end": 1615310130,
        "current_term_start": 1612890930,
        "customer_id": "__test__8asukSOXdyOjRE",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890930,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdyTgRH",
        "mrr": 0,
        "next_billing_at": 1615310130,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890932000,
        "started_at": 1612890930,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890932
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_changes

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing credit_note.
optional

Note: Cannot be called when the subscription is on a contract term. (That is, when the contract_term.status attribute is active.)

If the subscription is in Non Renewing or In Trial state and is also scheduled to cancel at the end of current term, then this API can be used to remove the scheduled cancellation. When a scheduled cancellation is removed, the subscription will revert to Active or In Trial state, whichever is the state before cancellation was scheduled.

While removing the scheduled cancellation, you may specify the number of billing cycles. If the billing cycle is not specified, the default billing cycle from the plan will be applied on the subscription.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdy9TR2/remove_scheduled_cancellation \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdy9TR2/remove_scheduled_cancellation \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505329,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdy5GQz",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505329175,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505329
    },
    "subscription": {
        "activated_at": 1517505329,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517505329,
        "currency_code": "USD",
        "current_term_end": 1519924529,
        "current_term_start": 1517505329,
        "customer_id": "__test__8asukSOXdy5GQz",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1517505329,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdy9TR2",
        "mrr": 0,
        "next_billing_at": 1519924529,
        "object": "subscription",
        "resource_version": 1517505330230,
        "started_at": 1517505329,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1517505330
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_cancellation

billing_cycles

Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Removes Coupons associated with the Subscription. If the param 'coupon_ids' is not specified, all the Coupons linked to the Subscription will be removed.

Sample Request

# removes the listed coupons associated with the subscription.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdxPSQY/remove_coupons \
     -X POST  \
     -u {site_api_key}:\
     -d coupon_ids[0]="P10DISC"

copy

# removes the listed coupons associated with the subscription.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdxPSQY/remove_coupons \
     -X POST  \
     -u {site_api_key}:\
     -d coupon_ids[0]="P10DISC"

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890926,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdxKsQV",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890926000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890926
    },
    "subscription": {
        "activated_at": 1612890926,
        "billing_period": 1,
        "billing_period_unit": "month",
        "coupon": "A5USD",
        "coupons": [
            {
                "applied_count": 1,
                "apply_till": 1644340526,
                "coupon_id": "A5USD",
                "object": "coupon"
            },
            {..}
        ],
        "created_at": 1612890926,
        "currency_code": "USD",
        "current_term_end": 1615310126,
        "current_term_start": 1612890926,
        "customer_id": "__test__8asukSOXdxKsQV",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890926,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdxPSQY",
        "mrr": 0,
        "next_billing_at": 1615310126,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890927000,
        "started_at": 1612890926,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 540,
        "updated_at": 1612890927
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_coupons

coupon_ids[0..n]

List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.
optional, list of string

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

This endpoint supports 3DS; create a payment_intent and provide it via this endpoint.

Updates the specified subscription by setting the parameters passed. Any parameters not provided are left unmodified. If an invoice is generated for this operation, any available credits and excess payments for the customer are automatically applied.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asrKRrLKtirr/update_for_items \
     -u {site_api_key}:\
     -d subscription_items[item_price_id][0]="basic-USD" \
     -d subscription_items[quantity][0]=4 \
     -d subscription_items[unit_price][0]=1000 \
     -d invoice_immediately="true"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asrKRrLKtirr/update_for_items \
     -u {site_api_key}:\
     -d subscription_items[item_price_id][0]="basic-USD" \
     -d subscription_items[quantity][0]=4 \
     -d subscription_items[unit_price][0]=1000 \
     -d invoice_immediately="true"

Sample Response [ JSON ]

{
    "credit_notes": [],
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890941,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXe1B5Sp",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890941000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890941
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 3000,
        "amount_paid": 0,
        "amount_to_collect": 3000,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asukSOXe1B5Sp",
        "date": 1612890942,
        "deleted": false,
        "due_date": 1612890942,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__30",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 3000,
                "customer_id": "__test__8asukSOXe1B5Sp",
                "date_from": 1612890942,
                "date_to": 1615310141,
                "description": "basic USD - Prorated Charges",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asukSOXe1VTT0",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 3,
                "subscription_id": "__test__8asukSOXe1FHSs",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612890942000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 3000,
        "subscription_id": "__test__8asukSOXe1FHSs",
        "tax": 0,
        "term_finalized": true,
        "total": 3000,
        "updated_at": 1612890942,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1612890941,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890941,
        "currency_code": "USD",
        "current_term_end": 1615310141,
        "current_term_start": 1612890941,
        "customer_id": "__test__8asukSOXe1B5Sp",
        "deleted": false,
        "due_invoices_count": 2,
        "due_since": 1612890941,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXe1FHSs",
        "mrr": 0,
        "next_billing_at": 1615310141,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890942000,
        "started_at": 1612890941,
        "status": "active",
        "subscription_items": [
            {
                "amount": 4000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 4,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 4100,
        "updated_at": 1612890942
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/update_for_items

mandatory_items_to_remove[0..n]

Item ids of mandatorily attached addons that are to be removed from the subscription.
optional, list of string

replace_items_list

If true then the existing subscription_items list for the subscription is replaced by the one provided. If false then the provided subscription_items list gets added to the existing list.
optional, boolean

invoice_date

The document date displayed on the invoice PDF. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. When not provided, the date is the same as reactivate_from or changes_scheduled_at (the former is considered when both are passed). Moreover, if create_pending_invoices is set to true, and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
It is not earlier than changes_scheduled_at or reactivate_from.
invoice_immediately is true.

.
optional, timestamp(UTC) in seconds

start_date

The new start date of a future subscription. Applicable only for future subscriptions.
optional, timestamp(UTC) in seconds

trial_end

The time at which the trial has ended or will end for the subscription. This is only allowed when the subscription status is future, in_trial, or cancelled. Also, the value must not be earlier than changes_scheduled_at or start_date. Note: This parameter can be backdated (set to a value in the past) only when the subscription is in cancelled status. Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end is backdated, the subscription immediately goes into active or non_renewing status.
optional, timestamp(UTC) in seconds

billing_cycles

Billing cycles set for plan-item price is used by default.
optional, integer, min=0

terms_to_charge

The number of subscription billing cycles to invoice in advance. If a new term is started for the subscription due to this API call, then terms_to_charge is inclusive of this new term. See description for the force_term_reset parameter to learn more about when a subscription term is reset.
optional, integer, min=1

reactivate_from

If the subscription status is cancelled and it is being reactivated via this operation, this is the date/time at which the subscription should be reactivated. Note: It is recommended not to pass this parameter along with changed_scheduled_at. reactivate_from can be backdated (set to a value in the past). Use backdating when the subscription has been reactivated already but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:

Backdating must be enabled for subscription reactivation operations.
The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is the day of the month by which the accounting for the previous month must be closed.
The date is on or after the last date/time any of the product catalog items of the subscription were changed.
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, changes_scheduled_at cannot be earlier than 14th February.

.
optional, timestamp(UTC) in seconds

billing_alignment_mode

Override the billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing.
optional, enumerated string

Possible values are

auto_collection

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string

Possible values are

offline_payment_method

The preferred offline payment method for the subscription.
optional, enumerated string

Possible values are

no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.

po_number

Purchase order number for this subscription.
optional, string, max chars=100

coupon_ids[0..n]

List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes. If changes_scheduled_at is in the past, then the currently available coupons can be used even if they were not available as of the date for when the change is scheduled.
optional, list of string

replace_coupon_list

If true then the existing coupon_ids list for the subscription is replaced by the one provided. If false then the provided list gets added to the existing coupon_ids.
optional, boolean

prorate

Raise prorated credits or charges as applicable while changing the subscription. When not provided, the value is taken from the site settings.
optional, boolean

end_of_term

Set this to true if you want the update to be applied at the end of the current subscription billing cycle.
optional, boolean

force_term_reset

Say the subscription has the renewal date as 28th of every month. When the plan-item price of the subscription is set to one that has the same billing period as the current plan-item price, the subscription change does not change the term. In other words, the subscription still renews on the 28th. Passing this parameter as true will have the subscription reset its term to the current date (provided end_of_term is false).
Note: When the new plan-item price has a billing period different from the current plan-item price of the subscription, the term is always reset, regardless of the value passed for this parameter.
optional, boolean, default=false

reactivate

When the status of the subscription is cancelled, this parameter determines whether the subscription is reactivated upon making this API request. Unless passed explicitly as false, this parameter is implied as true when you provide the subscription_items parameter.
optional, boolean

token_id

The Chargebee payment token generated by Chargebee JS.
optional, string, max chars=40

invoice_notes

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.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject

invoice_immediately

Note: invoice_immediately only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.

.
optional, boolean

override_relationship

If true, ignores the hierarchy relationship and uses customer as payment and invoice owner.
optional, boolean

changes_scheduled_at

When change_option is set to specific_date, then set the date/time at which the subscription change is to happen or has happened. Note: It is recommended not to pass this parameter along with reactivate_from. changes_scheduled_at can be set to a value in the past. This is called backdating the subscription change and is performed when the subscription change has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:

Backdating must be enabled for subscription change operations.
Only the following changes can be backdated:

Changes in the recurring items or their prices.
Addition of non-recurring items.

Subscription status is active, cancelled, or non_renewing.
The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is typically the day of the month by which the accounting for the previous month must be closed.
The date is on or after current_term_start.
The date is on or after the last date/time any of the following changes were made:

Changes in the recurring items or their prices.
Addition of non-recurring items.

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, changes_scheduled_at cannot be earlier than 14th February.

.
optional, timestamp(UTC) in seconds

change_option

When the quote is converted, this attribute determines the date/time as of when the subscription change is to be carried out.
optional, enumerated string

Possible values are

immediatelyThe change is carried out immediately.end_of_termThe change is carried out at the end of the current billing cycle of the subscription.specific_dateThe change is carried out as of the date specified under changes_scheduled_at.

contract_term_billing_cycle_on_renewal

free_period

The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit.
optional, integer, min=1

free_period_unit

The unit of time in multiples of which the free_period parameter is expressed. The value must be equal to or lower than the period_unit attribute of the plan chosen.
optional, enumerated string

Possible values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).

create_pending_invoices

You can also set this to true explicitly using the create/update subscription operations. This is useful in the following scenarios:

When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
When you need to inspect all charges before closing invoices for this subscription.

Applicable only when Metered Billing is enabled for the site

.
optional, boolean

auto_close_invoices

trial_end_action

Possible values are

card

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

card[first_name]

Cardholder's first name.
optional, string, max chars=50

card[last_name]

Cardholder's last name.
optional, string, max chars=50

card[number]

The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500

card[expiry_month]

Card expiry month.
required if card provided, integer, min=1, max=12

card[expiry_year]

Card expiry year.
required if card provided, integer

card[cvv]

The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520

card[billing_addr1]

Address line 1, as available in card billing address.
optional, string, max chars=150

card[billing_addr2]

Address line 2, as available in card billing address.
optional, string, max chars=150

card[billing_city]

City, as available in card billing address.
optional, string, max chars=50

card[billing_state_code]

card[billing_state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

card[billing_zip]

Postal or Zip code, as available in card billing address.
optional, string, max chars=20

card[billing_country]

card[additional_information]

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.

.
optional, jsonobject

payment_method

Parameters for payment_method
pass parameters as payment_method[<param name>]

payment_method[type]

The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
optional, enumerated string

Possible values are

cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.

genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.

Show all values[+]

payment_method[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

payment_method[reference_id]

The reference id. In the case of Amazon and PayPal this will be the billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=200

payment_method[tmp_token]

Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k

payment_method[issuing_country]

payment_method[additional_information]

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.

.
optional, jsonobject

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_information]

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.

.
optional, jsonobject

billing_address

Parameters for billing_address
pass parameters as billing_address[<param name>]

billing_address[first_name]

The first name of the billing contact.
optional, string, max chars=150

billing_address[last_name]

The last name of the billing contact.
optional, string, max chars=150

billing_address[email]

The email address.
optional, string, max chars=70

billing_address[company]

The company name.
optional, string, max chars=250

billing_address[phone]

The phone number.
optional, string, max chars=50

billing_address[line1]

Address line 1.
optional, string, max chars=150

billing_address[line2]

Address line 2.
optional, string, max chars=150

billing_address[line3]

Address line 3.
optional, string, max chars=150

billing_address[city]

The name of the city.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

billing_address[zip]

Zip or Postal code.
optional, string, max chars=20

billing_address[country]

billing_address[validation_status]

The address verification status.
optional, enumerated string

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

shipping_address[first_name]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

shipping_address[validation_status]

The address verification status.
optional, enumerated string

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

customer

Parameters for customer
pass parameters as customer[<param name>]

customer[vat_number]

The VAT/tax registration number for the customer. For customers with billing_address country as XI (which is United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.
optional, string, max chars=20

customer[vat_number_prefix]

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address country as XI (which is United Kingdom - Northern Ireland).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address country as XI. That’s the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.
optional, string, max chars=10

customer[business_customer_without_vat_number]

Confirms that a customer is a valid business without an EU/UK VAT number.
optional, boolean

customer[registered_for_gst]

Confirms that a customer is registered under GST. If set to true then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.
optional, boolean

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
optional, enumerated string

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

contract_term[cancellation_cutoff_period]

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

The unique identifier of the item price.
required, string, max chars=100

subscription_items[quantity][0..n]

The quantity of the item purchased.
optional, integer, min=1

subscription_items[quantity_in_decimal][0..n]

The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
optional, string, max chars=33

subscription_items[unit_price][0..n]

subscription_items[unit_price_in_decimal][0..n]

When price overriding is enabled for the site, the price or per-unit price of the item can be set here. The value set for the item price is used by default. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled. If changes_scheduled_at is in the past and a unit_price_in_decimal is not passed, then the item price’s current unit price is considered even if the item price did not exist on the date as of when the change is scheduled.
optional, string, max chars=33

subscription_items[billing_cycles][0..n]

subscription_items[trial_end][0..n]

The date/time when the trial period of the item ends. Applies to plan-items and—-when enabled-—addon-items as well.
optional, timestamp(UTC) in seconds

subscription_items[service_period_days][0..n]

The service period of the item in days from the day of charge.
optional, integer, min=1, max=730

subscription_items[charge_on_event][0..n]

Possible values are

subscription_items[charge_once][0..n]

Indicates if the charge-item is to be charged only once or each time the charge_on_event occurs. This parameter only applies to charge-items.
optional, boolean

subscription_items[charge_on_option][0..n]

Indicates when the charge-item is to be charged. This parameter only applies to charge-items.
optional, enumerated string

Possible values are

immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event.

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[apply_on][0..n]

The amount on the invoice to which the discount is applied.
required, enumerated string

Possible values are

discounts[duration_type][0..n]

Specifies the time duration for which this discount is attached to the subscription.
required, enumerated string

Possible values are

discounts[percentage][0..n]

The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.
optional, double, min=0.01, max=100.0

discounts[amount][0..n]

The value of the discount. The format of this value depends on the kind of currency. This is only applicable when discount.type is fixed_amount.
optional, in cents, min=0

discounts[period][0..n]

The duration of time for which the discount is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
optional, integer, min=1

discounts[period_unit][0..n]

The unit of time for period. Applicable only when duration_type is limited_period.
optional, enumerated string

Possible values are

dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.

discounts[included_in_mrr][0..n]

Set this to false if this coupon should be excluded from monthly recurring revenue (MRR) calculations for the site. The following prerequisites must be met to allow this parameter to be passed:

The discount duration_type must be one_time.
The feature must be enabled in Chargebee.
The site-level setting must be to include coupons in MRR calculations. The site level setting is also the default value for the attribute when this parameter is not passed.

.
optional, boolean

discounts[item_price_id][0..n]

The id of the item price in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.
optional, string, max chars=100

discounts[operation_type][0..n]

The operation to be carried out for the discount.
required, enumerated string

Possible values are

addThe discount is attached to the subscription.removeThe discount (given by discounts[id]) is removed from the subscription. Subsequent invoices will no longer have the discount applied. Tip: If you want to replace a discount, remove it and add another in the same API call.

discounts[id][0..n]

The id of the discount to be removed. This parameter is only relevant when discounts[operation_type] is remove.
optional, string, max chars=50

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[item_price_id][0..n]

The id of the item price for which the tier price is being overridden.
optional, string, max chars=100

item_tiers[starting_unit][0..n]

The lowest value in the quantity tier.
optional, integer, min=1

item_tiers[ending_unit][0..n]

The highest value in the quantity tier.
optional, integer

item_tiers[price][0..n]

The overridden price of the tier. The value depends on the type of currency.
optional, in cents, min=0

item_tiers[starting_unit_in_decimal][0..n]

item_tiers[ending_unit_in_decimal][0..n]

item_tiers[price_in_decimal][0..n]

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Resource object representing unbilled_charge.
optional

Resource object representing credit_note.
optional

Changes the subscription's current term end date. Depending on the "status" of the subscription, "term end date" has different effects.

If the Subscription is in trial, it affects trial end date.
If the Subscription is active, it affects the next billing date.
If the Subscription's status is non_renewing, this affects the upcoming cancellation date.

Tip: To cycle through a couple of billing cycles and test webhooks, you may use this API.

Notes

When changing the term_end for active / non_renewing subscriptions, by default no additional charges (when term gets extended) will be added or credits (when term gets reduced) will be issued. However you can specify prorate param as true for adding prorated charges / issuing prorated credits. Further for the charges that got added, you can specify invoice_immediately as false to add them to unbilled charges and invoice them later.
Advance charges, if any will be credited back during this operation.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdtByMK/change_term_end \
     -u {site_api_key}:\
     -d term_ends_at=1613413800

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdtByMK/change_term_end \
     -u {site_api_key}:\
     -d term_ends_at=1613413800

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890910,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdt6gMH",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890910000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890910
    },
    "subscription": {
        "activated_at": 1612890910,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890910,
        "currency_code": "USD",
        "current_term_end": 1613413800,
        "current_term_start": 1612890910,
        "customer_id": "__test__8asukSOXdt6gMH",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890910,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdtByMK",
        "mrr": 0,
        "next_billing_at": 1613413800,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890911000,
        "started_at": 1612890910,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890911
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/change_term_end

term_ends_at

The time at which the current term should end for this subscription.
required, timestamp(UTC) in seconds

prorate

Applicable for active / non_renewing subscriptions. If specified as true prorated charges / credits will be added during this operation.
optional, boolean

invoice_immediately

Note: invoice_immediately only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.

.
optional, boolean

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Resource object representing unbilled_charge.
optional

Resource object representing credit_note.
optional

This operation supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.

This API is used to reactivate a cancelled subscription. You may also optionally specify a trial end date, to move the subscription to In Trial state. If trial end is not specified, the subscription will be activated and any applicable charges will be initiated.

Unless the billing cycle is specified, it will be set to plan's default billing cycle.

During an in-term reactivation⁺⁺, unless the billing cycle is specified, the subscription's remaining billing cycles will be restored. If a trial end date is specified, then the plan's default billing cycle is used.

What is an "in-term reactivation"?
An "in-term reactivation" happens when the billing term of the subscription is retained upon cancellation and reactivation is initiated within that term.

When is the ‘billing term’ retained for a cancelled subscription?
When dunning (payment failure retry settings) is configured with the last retry configured as

cancel subscription and mark invoice as ‘Not Paid’, or
cancel subscription and mark the invoice as ‘Voided’ and the case if any of the current term invoices is partially or fully paid, the invoice is not voided but instead Chargebee marks the invoices as ‘Not Paid’.

Note : In both cases, the billing term is retained and upon reactivation the subscription will be moved to active state (if the plan does not have a trial period) and no invoice will be generated. Ensure that you collect any unpaid invoices.

Example : A Subscription was billed from 1st to 31st of a month and it was cancelled on the 20th due to one of the above cases (billing term is not reset). If the reactivation happens on 25th then it is considered an in-term reactivation.

Notes

Reactivation of a subscription in non_renewing state has been deprecated. To remove a scheduled cancellation of a non_renewing Subscription, use Remove Scheduled Cancellation API.

However, if you use reactivate API to remove scheduled cancellation for a non_renewing Subscription, then the status will be set to active and the billing cycle will be set to forever. If any value is passed for trial_end or billing cycle, an error will be thrown.

If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.

Additional Error Scenarios: If there is a need to create an immediate charge and the collection fails, an error will be thrown.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdwxyQE/reactivate \
     -X POST  \
     -u {site_api_key}:\
     -d invoice_immediately="true" \
     -d billing_cycles=4

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdwxyQE/reactivate \
     -X POST  \
     -u {site_api_key}:\
     -d invoice_immediately="true" \
     -d billing_cycles=4

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890924,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdwsNQB",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890924000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890924
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1100,
        "amount_paid": 0,
        "amount_to_collect": 1100,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asukSOXdwsNQB",
        "date": 1612890925,
        "deleted": false,
        "due_date": 1612890925,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__18",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asukSOXdwsNQB",
                "date_from": 1612890925,
                "date_to": 1615310125,
                "description": "basic USD",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asukSOXdxDQQP",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asukSOXdwxyQE",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612890926000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1100,
        "subscription_id": "__test__8asukSOXdwxyQE",
        "tax": 0,
        "term_finalized": true,
        "total": 1100,
        "updated_at": 1612890926,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1612890925,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890924,
        "currency_code": "USD",
        "current_term_end": 1615310125,
        "current_term_start": 1612890925,
        "customer_id": "__test__8asukSOXdwsNQB",
        "deleted": false,
        "due_invoices_count": 2,
        "due_since": 1612890924,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdwxyQE",
        "mrr": 0,
        "next_billing_at": 1615310125,
        "object": "subscription",
        "remaining_billing_cycles": 3,
        "resource_version": 1612890926000,
        "started_at": 1612890924,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 3,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 2200,
        "updated_at": 1612890926
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/reactivate

trial_end

Providing this parameter indicates that the subscription reactivates with an in_trial status and the trial period ends at the date provided. The value must not be earlier than reactivate_from. Note: This parameter can be backdated (set to a value in the past) only when reactivate_from has been backdated. Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end is backdated, the subscription immediately goes into active or non_renewing status.
optional, timestamp(UTC) in seconds

billing_cycles

Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.
optional, integer, min=0

reactivate_from

The date/time at which the subscription was reactivated. When not provided, the subscription is reactivated immediately on calling this API. The value of this parameter must always be in the past (backdating). Do this when the subscription has already been reactivated and the billing has been delayed. The following prerequisites must be met for this parameter to be passed:

The backdating feature has been enabled for subscription reactivation operations.
The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is 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, reactivate_from cannot be earlier than 14th February.

.
optional, timestamp(UTC) in seconds

invoice_immediately

Note: invoice_immediately only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.

.
optional, boolean

billing_alignment_mode

Applicable when calendar billing is enabled and a new active term gets started during this operation. Unless specified the configured default value will be used.
optional, enumerated string

Possible values are

terms_to_charge

invoice_date

The document date displayed on the invoice PDF. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. When not provided, the date is the same as reactivate_from. Moreover, if create_pending_invoices is true, and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
It is not earlier than reactivate_from.
invoice_immediately is true.

.
optional, timestamp(UTC) in seconds

contract_term_billing_cycle_on_renewal

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
optional, enumerated string, default=cancel

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.

contract_term[cancellation_cutoff_period]

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_information]

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.

.
optional, jsonobject

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Resource object representing unbilled_charge.
optional

Adds a one time charge to the subscription which will be added to the invoice generated at the end of the current term. If there are any applicable coupons in the subscription, an appropriate discount will be applied.

To collect a charge immediately, use this API.

Notes

If any subscription changes happen before the end of the current term, these charges will be collected along with it.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXds3JLW/add_charge_at_term_end \
     -u {site_api_key}:\
     -d amount=300 \
     -d description="Service Charge"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXds3JLW/add_charge_at_term_end \
     -u {site_api_key}:\
     -d amount=300 \
     -d description="Service Charge"

Sample Response [ JSON ]

{"estimate": {
    "created_at": 1612890907,
    "invoice_estimate": {
        "amount_due": 1400,
        "amount_paid": 0,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asukSOXdrvyLT",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 300,
                "customer_id": "__test__8asukSOXdrvyLT",
                "date_from": 1612890906,
                "date_to": 1612890906,
                "description": "Service Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__8asukSOXdsHoLe",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "subscription_id": "__test__8asukSOXds3JLW",
                "tax_amount": 0,
                "unit_amount": 300
            },
            {..}
        ],
        "object": "invoice_estimate",
        "price_type": "tax_exclusive",
        "recurring": true,
        "round_off_amount": 0,
        "sub_total": 1400,
        "taxes": [],
        "total": 1400
    },
    "object": "estimate",
    "subscription_estimate": {
        "currency_code": "USD",
        "id": "__test__8asukSOXds3JLW",
        "next_billing_at": 1615310105,
        "object": "subscription_estimate",
        "status": "active"
    }
}}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/add_charge_at_term_end

amount

The amount to be charged. The unit depends on the type of currency.
optional, in cents, min=1

description

Description for this charge.
required, string, max chars=250

amount_in_decimal

The decimal representation of the amount for the one-time charge. Provide the value in major units of the currency. Can be provided only when multi-decimal pricing is enabled.
optional, string, max chars=33

avalara_sale_type

Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction is for an item that is subject to vendor use tax.

avalara_transaction_type

Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

avalara_service_type

Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

date_from

The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds

date_to

The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds

estimate

Resource object representing estimate.
always returned

Creates an advance invoice or an advance invoicing schedule. When an advance invoice is generated, and auto_collection is on for the subscription, the payment_source associated with the subscription is charged. Any changes scheduled for the subscription are taken into account automatically while generating an advance invoice. Advance invoices are not generated for a subscription when it is in the paused status. Advance invoices are generated only for non-metered items in a subscription.

Notes

This operation is supported only on select plans. To know more, take a look at our plans and pricing page.
This operation is not supported for non_renewing and cancelled subscriptions.
This operation is not supported if an advance invoice is already present. You could void/delete that invoice and try creating another advance invoice.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdtV2MX/charge_future_renewals \
     -u {site_api_key}:\
     -d terms_to_charge=5

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdtV2MX/charge_future_renewals \
     -u {site_api_key}:\
     -d terms_to_charge=5

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890911,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdtPJMU",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890911000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890911
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 5500,
        "amount_paid": 0,
        "amount_to_collect": 5500,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asukSOXdtPJMU",
        "date": 1612890912,
        "deleted": false,
        "due_date": 1612890912,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": true,
        "id": "__demo_inv__6",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asukSOXdtPJMU",
                "date_from": 1615310111,
                "date_to": 1617988511,
                "description": "basic USD",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asukSOXdthZMf",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asukSOXdtV2MX",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612890912000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 5500,
        "subscription_id": "__test__8asukSOXdtV2MX",
        "tax": 0,
        "term_finalized": true,
        "total": 5500,
        "updated_at": 1612890912,
        "write_off_amount": 0
    },
    "subscription": {
        "activated_at": 1612890911,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890911,
        "currency_code": "USD",
        "current_term_end": 1615310111,
        "current_term_start": 1612890911,
        "customer_id": "__test__8asukSOXdtPJMU",
        "deleted": false,
        "due_invoices_count": 2,
        "due_since": 1612890911,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdtV2MX",
        "mrr": 0,
        "next_billing_at": 1628529311,
        "object": "subscription",
        "resource_version": 1612890911000,
        "started_at": 1612890911,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 6600,
        "updated_at": 1612890911
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/charge_future_renewals

terms_to_charge

For schedule_type = immediate: the number of future billing cycles to be invoiced in advance. The invoicing is done for the remaining_billing_cycles of the subscription if that is less than terms_to_charge.
For schedule_type = fixed_intervals: The number of future billing cycles in one interval. The schedule is created such that the total number of billing cycles in the schedule does not exceed the remaining_billing_cycles of the subscription.

.
optional, integer, default=1, min=1

invoice_immediately

Whether the charge should be invoiced immediately or added to unbilled_charges. Applicable only when schedule_type is immediate.
optional, boolean

schedule_type

The type of advance invoice or advance invoicing schedule.
optional, enumerated string

Possible values are

immediateCharge immediately for the number of billing cycles specified by terms_to_charge.specific_datesCharge on specific dates. For each date, specify the number of billing cycles to charge for. Up to 5 dates can be configured.fixed_intervalsCharge at fixed intervals of time. Specify the number of billing cycles that constitute an interval and the number of days before each interval that the invoice should be generated. Also specify when the schedule should end.

fixed_interval_schedule

Parameters for fixed_interval_schedule
pass parameters as fixed_interval_schedule[<param name>]

fixed_interval_schedule[number_of_occurrences]

The number of advance invoices to generate. The schedule is created such that the total number of billing cycles in the schedule does not exceed the remaining_billing_cycles of the subscription. This parameter is applicable only when fixed_interval_schedule[end_schedule_on] = after_number_of_intervals.
optional, integer, min=1

fixed_interval_schedule[days_before_renewal]

The number of days before each interval that advance invoices are generated.
optional, integer, min=1

fixed_interval_schedule[end_schedule_on]

Specifies when the schedule should end.
optional, enumerated string

Possible values are

after_number_of_intervalsAdvance invoices are generated a specified number of times.specific_dateEnd the advance invoicing schedule on a specific date.subscription_endAdvance invoices are generated for as long as the subscription is active.

fixed_interval_schedule[end_date]

The date when the schedule should end. Advance invoices are not generated beyond this date. It must be at least 1 day before the start of the last billing cycle of the subscription and also within 5 years from the current date. This parameter is only applicable when fixed_interval_schedule[end_schedule_on] = specific_date.
optional, timestamp(UTC) in seconds

specific_dates_schedule

Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]

specific_dates_schedule[terms_to_charge][0..n]

The number of billing cycles to charge for, on the date specified. Applicable only when schedule_type is specific_dates.
optional, integer

specific_dates_schedule[date][0..n]

The unique id of the member of the advance_invoice_schedule array which corresponds to the specific_dates_schedule that you intend to modify. Only applicable when schedule_type is specific_dates.
optional, timestamp(UTC) in seconds

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Resource object representing advance_invoice_schedule.
optional

Modifies the advance invoicing schedule for a subscription.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2vpB3C/edit_advance_invoice_schedule \
     -X POST  \
     -u {site_api_key}:\
     -d schedule_type="specific_dates" \
     -d specific_dates_schedule[id][0]="__test__KyVkmQSCX2vwe3Q" \
     -d specific_dates_schedule[terms_to_charge][0]=1

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2vpB3C/edit_advance_invoice_schedule \
     -X POST  \
     -u {site_api_key}:\
     -d schedule_type="specific_dates" \
     -d specific_dates_schedule[id][0]="__test__KyVkmQSCX2vwe3Q" \
     -d specific_dates_schedule[terms_to_charge][0]=1

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2w3g3U/edit_advance_invoice_schedule \
     -X POST  \
     -u {site_api_key}:\
     -d schedule_type="fixed_intervals" \
     -d fixed_interval_schedule[days_before_renewal]=3

Sample Response [ JSON ]

{"advance_invoice_schedules": [
    {
        "id": "__test__KyVkmQSCX2vwe3Q",
        "object": "advance_invoice_schedule",
        "schedule_type": "specific_dates",
        "specific_dates_schedule": {
            "date": 1518339708,
            "object": "specific_dates_schedule",
            "terms_to_charge": 1
        }
    },
    {..}
]}

{"advance_invoice_schedules": [
    {
        "fixed_interval_schedule": {
            "days_before_renewal": 3,
            "end_schedule_on": "subscription_end",
            "object": "fixed_interval_schedule",
            "terms_to_charge": 1
        },
        "id": "__test__KyVkmQSCX2wAO3i",
        "object": "advance_invoice_schedule",
        "schedule_type": "fixed_intervals"
    },
    {..}
]}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/edit_advance_invoice_schedule

terms_to_charge

The number of billing cycles in one interval.
optional, integer, min=1

schedule_type

The type of advance invoice or advance invoicing schedule.
optional, enumerated string

Possible values are

specific_datesCharge on specific dates. For each date, specify the number of billing cycles to charge for. Up to 5 dates can be configured.fixed_intervalsCharge at fixed intervals of time. Specify the number of billing cycles that constitute an interval and the number of days before each interval that the invoice should be generated. Also specify when the schedule should end.

fixed_interval_schedule

Parameters for fixed_interval_schedule
pass parameters as fixed_interval_schedule[<param name>]

fixed_interval_schedule[number_of_occurrences]

fixed_interval_schedule[days_before_renewal]

The number of days before each interval that advance invoices are generated.
optional, integer, min=1

fixed_interval_schedule[end_schedule_on]

Specifies when the schedule should end.
optional, enumerated string

Possible values are

fixed_interval_schedule[end_date]

specific_dates_schedule

Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]

specific_dates_schedule[id][0..n]

The unique id of the member of the advance_invoice_schedule array which corresponds to the specific_dates_schedule that you intend to modify. Only applicable when schedule_type is specific_dates.
optional, string, max chars=50

specific_dates_schedule[terms_to_charge][0..n]

The number of billing cycles to charge for, on the date specified. Applicable only when schedule_type is specific_dates.
optional, integer

specific_dates_schedule[date][0..n]

Resource object representing advance_invoice_schedule.
always returned

Retrieves the advance_invoice_schedule for a subscription. Note that this endpoint is only applicable for schedule_type = specific_dates or fixed_intervals.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2wPg43/retrieve_advance_invoice_schedule \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVkmQSCX2wPg43/retrieve_advance_invoice_schedule \
     -u {site_api_key}:

Sample Response [ JSON ]

{"advance_invoice_schedules": [
    {
        "id": "__test__KyVkmQSCX2wUp4H",
        "object": "advance_invoice_schedule",
        "schedule_type": "specific_dates",
        "specific_dates_schedule": {
            "date": 1518339710,
            "object": "specific_dates_schedule",
            "terms_to_charge": 2
        }
    },
    {..}
]}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/retrieve_advance_invoice_schedule

Resource object representing advance_invoice_schedule.
always returned

Deletes an advance invoicing schedule. When schedule_type = specific_dates, you also have the option of deleting a part of the schedule.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBsG2SYV7ZMB2K/remove_advance_invoice_schedule \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBsG2SYV7ZMB2K/remove_advance_invoice_schedule \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "advance_invoice_schedules": [],
    "subscription": {
        "customer": {
            "allow_direct_debit": false,
            "auto_collection": "off",
            "card_status": "no_card",
            "created_at": 1622014982,
            "deleted": false,
            "excess_payments": 0,
            "first_name": "John",
            "id": "__test__XpbBsG2SYV7ZFJ2H",
            "last_name": "Doe",
            "net_term_days": 0,
            "object": "customer",
            "pii_cleared": "active",
            "preferred_currency_code": "USD",
            "promotional_credits": 0,
            "refundable_credits": 0,
            "resource_version": 1622014982000,
            "taxability": "taxable",
            "unbilled_charges": 0,
            "updated_at": 1622014982
        },
        "subscription": {
            "activated_at": 1622014983,
            "billing_period": 1,
            "billing_period_unit": "month",
            "created_at": 1622014983,
            "currency_code": "USD",
            "current_term_end": 1624693383,
            "current_term_start": 1622014983,
            "customer_id": "__test__XpbBsG2SYV7ZFJ2H",
            "deleted": false,
            "due_invoices_count": 1,
            "due_since": 1622014983,
            "has_scheduled_advance_invoices": false,
            "has_scheduled_changes": false,
            "id": "__test__XpbBsG2SYV7ZMB2K",
            "mrr": 0,
            "next_billing_at": 1624693383,
            "object": "subscription",
            "resource_version": 1622014983000,
            "started_at": 1622014983,
            "status": "active",
            "subscription_items": [
                {
                    "amount": 1000,
                    "free_quantity": 0,
                    "item_price_id": "basic-USD",
                    "item_type": "plan",
                    "object": "subscription_item",
                    "quantity": 1,
                    "unit_price": 1000
                },
                {..}
            ],
            "total_dues": 1100,
            "updated_at": 1622014983
        }
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_advance_invoice_schedule

specific_dates_schedule

Parameters for specific_dates_schedule. Multiple specific_dates_schedule can be passed by specifying unique indices.
pass parameters as specific_dates_schedule[<param name>][<idx:0..n>]

specific_dates_schedule[id][0..n]

When schedule_type = specific_dates, pass the id of the specific_dates_schedule that you want to remove. If not passed, the entire advance_invoice_schedule is removed.
optional, string, max chars=50

Resource object representing subscription.
always returned

Resource object representing advance_invoice_schedule.
optional

Regenerates the current invoice for the subscription. The current invoice is that which includes non-metered items from the current term and metered items from the previous term of the subscription.

prerequisites

The current invoice of the subscription must have been voided or deleted.
The subscription status must be active or non_renewing.
There should be no unbilled charges for non-metered items for the current term.
There should be no unbilled charges for metered items for the previous term.
The subscription must not have any advance invoice or advance invoice schedule.

deleting an invoice

Usages are also deleted when an invoice is deleted. Therefore, if the invoice was deleted, you may add or bulk import usages before regenerating an invoice.

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/regenerate_invoice

date_from

The start date of the period being invoiced. The default value is current_term_start.
optional, timestamp(UTC) in seconds

date_to

The end date of the period being invoiced. The default value is current_term_end.
optional, timestamp(UTC) in seconds

prorate

Whether the charges should be prorated according to the term specified by date_from and date_to. Should not be passed without date_from and date_to.
optional, boolean

invoice_immediately

Only applicable when Consolidated Invoicing is enabled for the customer. Set to false to leave the current term charge for the subscription as unbilled. Once you have done this for all suitable subscriptions of the customer, call Create an invoice for unbilled charges to invoice them.
optional, boolean

Resource object representing invoice.
optional

Resource object representing unbilled_charge.
optional

Import previous and active contract terms.

For contract terms in active state, import is allowed only if the associated subscription is active, in_trial, future or non-renewing.
.

This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdvMNOv/import_contract_term \
     -X POST  \
     -u {site_api_key}:\
     -d contract_term[action_at_term_end]="cancel" \
     -d contract_term[billing_cycle]=5 \
     -d contract_term[contract_start]=1483245610 \
     -d contract_term[contract_end]=1493613610 \
     -d contract_term[status]="terminated" \
     -d contract_term[total_contract_value]="1000"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdvMNOv/import_contract_term \
     -X POST  \
     -u {site_api_key}:\
     -d contract_term[action_at_term_end]="cancel" \
     -d contract_term[billing_cycle]=5 \
     -d contract_term[contract_start]=1483245610 \
     -d contract_term[contract_end]=1493613610 \
     -d contract_term[status]="terminated" \
     -d contract_term[total_contract_value]="1000"

Sample Response [ JSON ]

{"contract_term": {
    "action_at_term_end": "cancel",
    "billing_cycle": 5,
    "cancellation_cutoff_period": 0,
    "contract_end": 1493613610,
    "contract_start": 1483245610,
    "created_at": 1483245610,
    "id": "__test__8asukSOXdvULP3",
    "object": "contract_term",
    "status": "terminated",
    "total_contract_value": 1000
}}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/import_contract_term

contract_term_billing_cycle_on_renewal

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[id]

Id that uniquely identifies the contract term in the site.
optional, string, max chars=50

contract_term[created_at]

The date when the contract term was created.
optional, timestamp(UTC) in seconds

contract_term[contract_start]

The start date of the contract term.
optional, timestamp(UTC) in seconds

contract_term[contract_end]

The end date of the contract term.
optional, timestamp(UTC) in seconds

contract_term[status]

Current status of contract.
optional, enumerated string

Possible values are

activeAn actively running contract term.completedThe contract term has run its full duration.cancelledThe contract term was ended because:

a change in the subscription caused a subscription term reset.
the subscription was cancelled due to non-payment.

.terminatedThe contract term was terminated ahead of completion.

contract_term[total_amount_raised]

The amount raised for the contract term till the time of importing the subscription. This amount is added to the total_contract_value.
optional, in cents, default=0, min=0

contract_term[total_contract_value]

contract_term[billing_cycle]

The number of billing cycles of the subscription that the contract term is for.
optional, integer, min=0

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
optional, enumerated string, default=renew

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

contract_term[cancellation_cutoff_period]

contract_term

Resource object representing contract_term.
always returned

Imports a subscription into Chargebee.

This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.

Sample Request

curl  https://{site}.chargebee.com/api/v2/customers/__test__8at19S2Bx82rKy/import_for_items \
     -u {site_api_key}:\
     -d subscription_items[item_price_id][0]="basic-USD" \
     -d subscription_items[quantity][0]=1 \
     -d status="active" \
     -d charged_items[item_price_id][0]="ssl-charge-USD" \
     -d charged_items[last_charged_at][0]=1516297094 \
     -d current_term_end=1593541800

copy

curl  https://{site}.chargebee.com/api/v2/customers/__test__8at19S2Bx82rKy/import_for_items \
     -u {site_api_key}:\
     -d subscription_items[item_price_id][0]="basic-USD" \
     -d subscription_items[quantity][0]=1 \
     -d status="active" \
     -d charged_items[item_price_id][0]="ssl-charge-USD" \
     -d charged_items[last_charged_at][0]=1516297094 \
     -d current_term_end=1593541800

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517505319,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdvWPP6",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517505319325,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517505319
    },
    "subscription": {
        "activated_at": 1517505319,
        "billing_period": 1,
        "billing_period_unit": "month",
        "charged_items": [
            {
                "item_price_id": "ssl-charge-USD",
                "last_charged_at": 1516295719,
                "object": "charged_item"
            },
            {..}
        ],
        "created_at": 1517505319,
        "currency_code": "USD",
        "current_term_end": 1614018600,
        "current_term_start": 1517505319,
        "customer_id": "__test__8asukSOXdvWPP6",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdvbfP9",
        "mrr": 0,
        "next_billing_at": 1614018600,
        "object": "subscription",
        "resource_version": 1517505319739,
        "started_at": 1517505319,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "updated_at": 1517505319
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/import_for_items

id

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
optional, string, max chars=50

trial_end

billing_cycles

The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan-item price is used.
optional, integer, min=0

start_date

The date/time at which the subscription is to start or has started. If not provided, the subscription starts immediately.
optional, timestamp(UTC) in seconds

auto_collection

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string

Possible values are

po_number

Purchase order number for this subscription.
optional, string, max chars=100

coupon_ids[0..n]

List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.
optional, list of string

payment_source_id

Id of the payment source to be attached to this subscription.
optional, string, max chars=40

status

Current state of the subscription.
required, enumerated string

Possible values are

current_term_end

End of the current billing term. Subscription is renewed immediately after this. If not given, this will be calculated based on plan billing cycle.
optional, timestamp(UTC) in seconds

current_term_start

Start of the current billing period of the subscription.
optional, timestamp(UTC) in seconds

trial_start

cancelled_at

Time at which subscription was cancelled or is set to be cancelled.
optional, timestamp(UTC) in seconds

started_at

Time at which the subscription was started. Is null for futuresubscriptions as it is yet to be started.
optional, timestamp(UTC) in seconds

pause_date

resume_date

For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.
optional, timestamp(UTC) in seconds

contract_term_billing_cycle_on_renewal

create_current_term_invoice

Set as true if you want an invoice to be created for the subscription.

The invoice will be created for the subscription only if it has an active or non_renewing status.
The period of the invoice is from current_term_start to current_term_end.
The invoice will not be generated if the subscription amount is zero dollars (for that period) and 'Hide Zero Value Line Items' option is enabled in site settings.
optional, boolean, default=false

invoice_notes

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.
optional, string, max chars=2000

meta_data

A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject

create_pending_invoices

You can also set this to true explicitly using the create/update subscription operations. This is useful in the following scenarios:

When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
When you need to inspect all charges before closing invoices for this subscription.

Applicable only when Metered Billing is enabled for the site

.
optional, boolean

auto_close_invoices

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[id]

Id that uniquely identifies the contract term in the site.
optional, string, max chars=50

contract_term[created_at]

The date when the contract term was created.
optional, timestamp(UTC) in seconds

contract_term[contract_start]

The start date of the contract term.
optional, timestamp(UTC) in seconds

contract_term[billing_cycle]

The number of billing cycles of the subscription that the contract term is for.
optional, integer, min=0

contract_term[total_amount_raised]

The amount raised for the contract term till the time of importing the subscription. This amount is added to the total_contract_value.
optional, in cents, default=0, min=0

contract_term[action_at_term_end]

Action to be taken when the contract term completes.
optional, enumerated string, default=renew

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

contract_term[cancellation_cutoff_period]

transaction

Parameters for transaction
pass parameters as transaction[<param name>]

transaction[amount]

The payment transaction amount. This parameter should be passed only if the invoice is created for current term.
optional, in cents, min=1

transaction[payment_method]

The payment method of this transaction. This parameter should be passed only if the invoice is created for current term.
optional, enumerated string, default=card

Possible values are

cashCash.checkCheck.

bank_transferBank Transfer.otherPayment Methods other than the above types.

Show all values[+]

transaction[reference_number]

The reference number for this transaction. For example, check number in case of check payment_method. This parameter should be passed only if the invoice is created for current term.
optional, string, max chars=100

transaction[date]

The date of occurence of the transaction. This parameter should be passed only if the invoice is created for current term.
optional, timestamp(UTC) in seconds

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

shipping_address[first_name]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

shipping_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

The unique identifier of the item price.
required, string, max chars=100

subscription_items[quantity][0..n]

The quantity of the item purchased.
optional, integer, min=1

subscription_items[quantity_in_decimal][0..n]

The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
optional, string, max chars=33

subscription_items[unit_price][0..n]

subscription_items[unit_price_in_decimal][0..n]

subscription_items[billing_cycles][0..n]

subscription_items[trial_end][0..n]

The date/time when the trial period of the item ends. Applies to plan-items and—-when enabled-—addon-items as well.
optional, timestamp(UTC) in seconds

subscription_items[service_period_days][0..n]

The service period of the item in days from the day of charge.
optional, integer, min=1, max=730

subscription_items[charge_on_event][0..n]

Possible values are

subscription_items[charge_once][0..n]

Indicates if the charge-item is to be charged only once or each time the charge_on_event occurs. This parameter only applies to charge-items.
optional, boolean

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[apply_on][0..n]

The amount on the invoice to which the discount is applied.
required, enumerated string

Possible values are

discounts[duration_type][0..n]

Specifies the time duration for which this discount is attached to the subscription.
required, enumerated string, default=forever

Possible values are

discounts[percentage][0..n]

The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.
optional, double, min=0.01, max=100.0

discounts[amount][0..n]

The value of the discount. The format of this value depends on the kind of currency. This is only applicable when discount.type is fixed_amount.
optional, in cents, min=0

discounts[period][0..n]

The duration of time for which the discount is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
optional, integer, min=1

discounts[period_unit][0..n]

The unit of time for period. Applicable only when duration_type is limited_period.
optional, enumerated string

Possible values are

dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.

discounts[included_in_mrr][0..n]

Set this to false if this coupon should be excluded from monthly recurring revenue (MRR) calculations for the site. The following prerequisites must be met to allow this parameter to be passed:

The discount duration_type must be one_time.
The feature must be enabled in Chargebee.
The site-level setting must be to include coupons in MRR calculations. The site level setting is also the default value for the attribute when this parameter is not passed.

.
optional, boolean

discounts[item_price_id][0..n]

The id of the item price in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.
optional, string, max chars=100

charged_items

Parameters for charged_items. Multiple charged_items can be passed by specifying unique indices.
pass parameters as charged_items[<param name>][<idx:0..n>]

charged_items[item_price_id][0..n]

A unique ID for your system to identify the item price.
optional, string, max chars=100

charged_items[last_charged_at][0..n]

Timestamp indicating when this charge item_price was last charged for this subscription.
optional, timestamp(UTC) in seconds

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[item_price_id][0..n]

The id of the item price for which the tier price is being overridden.
optional, string, max chars=100

item_tiers[starting_unit][0..n]

The lowest value in the quantity tier.
optional, integer, min=1

item_tiers[ending_unit][0..n]

The highest value in the quantity tier.
optional, integer

item_tiers[price][0..n]

The overridden price of the tier. The value depends on the type of currency.
optional, in cents, default=0, min=0

item_tiers[starting_unit_in_decimal][0..n]

item_tiers[ending_unit_in_decimal][0..n]

item_tiers[price_in_decimal][0..n]

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Assigns the payment source and sets auto collection state for the subscription.

Notes

When you don't pass any input param for this API, payment source and auto collection for the subscription will be the same as the customer's default settings.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdw1vPR/override_billing_profile \
     -X POST  \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__8asukSOXdwAuPa" \
     -d auto_collection="on"

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdw1vPR/override_billing_profile \
     -X POST  \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__8asukSOXdwAuPa" \
     -d auto_collection="on"

Sample Response [ JSON ]

{
    "payment_source": {
        "card": {
            "brand": "american_express",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "not_known",
            "iin": "378282",
            "last4": "0005",
            "masked_number": "***********0005",
            "object": "card"
        },
        "created_at": 1612890921,
        "customer_id": "__test__8asukSOXdvwzPO",
        "deleted": false,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__8astDSOXdqwz1y",
        "id": "pm___test__8asukSOXdwAuPa",
        "object": "payment_source",
        "reference_id": "tok___test__8asukSOXdwAqPZ",
        "resource_version": 1612890921000,
        "status": "valid",
        "type": "card",
        "updated_at": 1612890921
    },
    "subscription": {
        "activated_at": 1612890921,
        "auto_collection": "on",
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890921,
        "currency_code": "USD",
        "current_term_end": 1615310121,
        "current_term_start": 1612890921,
        "customer_id": "__test__8asukSOXdvwzPO",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdw1vPR",
        "mrr": 0,
        "next_billing_at": 1615310121,
        "object": "subscription",
        "payment_source_id": "pm___test__8asukSOXdwAuPa",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890921000,
        "started_at": 1612890921,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "updated_at": 1612890921
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/override_billing_profile

payment_source_id

Unique identifier of the payment source to be attached to this subscription.
optional, string, max chars=40

auto_collection

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string

Possible values are

Resource object representing subscription.
always returned

payment_source

Resource object representing payment_source.
optional

Deletes the subscription resource.

Notes

This operation is irreversible - all data related to the subscription, such as invoices, transactions, and reports, will be deleted.

Note: This operation schedules the subscription resource for deletion. It will be deleted in a few minutes.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdv6kOj/delete \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdv6kOj/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890917,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdv0dOg",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890917000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890917
    },
    "subscription": {
        "activated_at": 1612890917,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890917,
        "currency_code": "USD",
        "current_term_end": 1615310117,
        "current_term_start": 1612890917,
        "customer_id": "__test__8asukSOXdv0dOg",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890917,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdv6kOj",
        "mrr": 0,
        "next_billing_at": 1615310117,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890918000,
        "started_at": 1612890917,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890918
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/delete

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Pausing a subscription will move the subscription from its current state to Paused state, and will stop all recurring actions.

You could schedule the pause by passing specific_date/end_of_term parameter in pause_option. If scheduled, the subscription will not be paused until the specific_date/end_of_term is reached.

UNBILLED CHARGES

Any unbilled charges present in the subscription can be invoiced by specifying invoice or no_action. If invoice is chosen, automatic charge will be attempted on the payment method available if the customer has enabled auto-collection. If payment collection fails or when auto-collection is not enabled, the invoice will be closed as unpaid.
If no_action is chosen, charges will be added to the resumption invoice.

INVOICE DUNNING HANDLING

If invoice is in the dunning cycle, invoice_dunning_handing allows you to stop or continue dunning.

Note:

Applicable only for active/non-renewing subscriptions.
For non-renewing subscriptions, pause_date and resume_date should be before the cancellation date. If paused indefinitely, the subscription will be cancelled on the cancelled_at date.
Advance charges, if any, will be refunded as credits.

Sample Request

# pauses the subscription on end of term.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdwKMPo/pause \
     -X POST  \
     -u {site_api_key}:\
     -d pause_option="end_of_term"

copy

# pauses the subscription on end of term.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdwKMPo/pause \
     -X POST  \
     -u {site_api_key}:\
     -d pause_option="end_of_term"

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890922,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdwFjPl",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890922000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890922
    },
    "subscription": {
        "activated_at": 1612890922,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890922,
        "currency_code": "USD",
        "current_term_end": 1615310122,
        "current_term_start": 1612890922,
        "customer_id": "__test__8asukSOXdwFjPl",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890922,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdwKMPo",
        "mrr": 0,
        "object": "subscription",
        "pause_date": 1615310122,
        "remaining_billing_cycles": 1,
        "resource_version": 1612890923000,
        "started_at": 1612890922,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890923
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/pause

pause_option

List of options to pause the subscription.
optional, enumerated string

Possible values are

immediatelyPause immediately.end_of_termPause at the end of current term.specific_datePause on a specific date.

pause_date

Date on which the subscription will be paused. Applicable when 'specific_date' option is chosen in the pause_option field.
optional, timestamp(UTC) in seconds

unbilled_charges_handling

Applicable when unbilled charges are present for the subscription and pause_option is set as 'immediately'. Note: On the invoice raised, an automatic charge will be attempted on the payment method available, if customer's auto-collection property is ‘ON’.
optional, enumerated string

Possible values are

no_actionRetain as unbilled.invoiceInvoice charges.

invoice_dunning_handling

Handles dunning for invoices already in the dunning cycle, when subscription is paused. Applicable when pause_option is set as 'immediately'.
optional, enumerated string

Possible values are

continueContinue dunning.stopStop dunning.

resume_date

For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.
optional, timestamp(UTC) in seconds

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Resource object representing unbilled_charge.
optional

Resource object representing credit_note.
optional

Cancels the subscription.

Canceling contract terms

Subscriptions with contract terms can only be canceled by terminating the contract term.
When canceling a contract term, the default value for the following parameters is taken from the site settings for contract terms instead of the site settings for subscription cancellation.

credit_option_for_current_term_charges
unbilled_charges_option
account_receivables_handling
refundable_credits_handling

From among the parameters for this request, end_of_term or cancel_at should not be passed when using contract terms; use contract_term_cancel_option instead.
The subscription_items parameter is used to override price or quantity for the termination fee. To use this parameter, the following two conditions must be met:

contract_term_cancel_option must be set to terminate_now.
the subscription must have a subscription_items attribute with charge_on_event set to contract_term_termination.

Sample Request

# cancels the subscription after the term ends.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y28bL9/cancel_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d end_of_term="true"

copy

# cancels the subscription after the term ends.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y28bL9/cancel_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d end_of_term="true"

# cancels the subscription immediately with proration credits issued.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__KyVnZKS5y29FDJ/cancel_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d credit_option_for_current_term_charges="prorate" \
     -d end_of_term="false"

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890907,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdsPqLk",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890907000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890907
    },
    "subscription": {
        "activated_at": 1612890907,
        "billing_period": 1,
        "billing_period_unit": "month",
        "cancelled_at": 1615310107,
        "created_at": 1612890907,
        "currency_code": "USD",
        "current_term_end": 1615310107,
        "current_term_start": 1612890907,
        "customer_id": "__test__8asukSOXdsPqLk",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890907,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdsV6Ln",
        "mrr": 0,
        "object": "subscription",
        "remaining_billing_cycles": 0,
        "resource_version": 1612890908000,
        "started_at": 1612890907,
        "status": "non_renewing",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 0,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890908
    }
}

{
    "credit_notes": [
        {
            "allocations": [
                {
                    "allocated_amount": 1100,
                    "allocated_at": 1595874353,
                    "invoice_date": 1595874352,
                    "invoice_id": "__demo_inv__2",
                    "invoice_status": "paid"
                },
                {..}
            ],
            "amount_allocated": 1100,
            "amount_available": 0,
            "amount_refunded": 0,
            "base_currency_code": "USD",
            "create_reason_code": "Subscription Cancellation",
            "currency_code": "USD",
            "customer_id": "__test__KyVnZKS5y29BpH",
            "date": 1595874353,
            "deleted": false,
            "exchange_rate": 1,
            "fractional_correction": 0,
            "id": "__demo_cn__1",
            "line_item_discounts": [],
            "line_item_taxes": [],
            "line_items": [
                {
                    "amount": 1000,
                    "customer_id": "__test__KyVnZKS5y29BpH",
                    "date_from": 1595874353,
                    "date_to": 1598552752,
                    "description": "basic USD - Prorated Credits for 27-Jul-2020 - 27-Aug-2020",
                    "discount_amount": 0,
                    "entity_id": "basic-USD",
                    "entity_type": "plan_item_price",
                    "id": "li___test__KyVnZKS5y29OfS",
                    "is_taxed": false,
                    "item_level_discount_amount": 0,
                    "object": "line_item",
                    "pricing_model": "per_unit",
                    "quantity": 1,
                    "subscription_id": "__test__KyVnZKS5y29FDJ",
                    "tax_amount": 0,
                    "tax_exempt_reason": "tax_not_configured",
                    "unit_amount": 1000
                },
                {..}
            ],
            "linked_refunds": [],
            "object": "credit_note",
            "price_type": "tax_exclusive",
            "reason_code": "subscription_cancellation",
            "reference_invoice_id": "__demo_inv__2",
            "refunded_at": 1595874353,
            "resource_version": 1595874353000,
            "round_off_amount": 0,
            "status": "adjusted",
            "sub_total": 1100,
            "subscription_id": "__test__KyVnZKS5y29FDJ",
            "taxes": [],
            "total": 1100,
            "type": "adjustment",
            "updated_at": 1595874353
        },
        {..}
    ],
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1595874352,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__KyVnZKS5y29BpH",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1595874352000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1595874352
    },
    "subscription": {
        "activated_at": 1595874352,
        "billing_period": 1,
        "billing_period_unit": "month",
        "cancelled_at": 1595874353,
        "created_at": 1595874352,
        "currency_code": "USD",
        "current_term_end": 1595874353,
        "current_term_start": 1595874352,
        "customer_id": "__test__KyVnZKS5y29BpH",
        "deleted": false,
        "due_invoices_count": 0,
        "has_scheduled_changes": false,
        "id": "__test__KyVnZKS5y29FDJ",
        "mrr": 0,
        "object": "subscription",
        "resource_version": 1595874353000,
        "started_at": 1595874352,
        "status": "cancelled",
        "subscription_items": [
            {
                "amount": 1000,
                "item_free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "updated_at": 1595874353
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/cancel_for_items

end_of_term

Set this to true if you want to cancel the subscription at the end of the current subscription billing cycle. The subscription status changes to non_renewing.
optional, boolean, default=false

cancel_at

Specify the date/time at which you want to cancel the subscription. This parameter should not be provided when end_of_term is passed as true. cancel_at can be set to a value in the past. This is called backdating. Use backdating when the subscription has been canceled already but its billing has been delayed. The following prerequisites must be met to allow backdating:

Backdating must be enabled for subscription cancellation.
The current day of the month does not exceed the limit set in Chargebee for backdating subscription cancellation. This limit is typically the day of the month by which the accounting for the previous month must be closed.
The date is on or after current_term_start.
The date is on or after the last date/time any of the following changes were made:

Changes in the recurring items or their prices.
Addition of non-recurring items.

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 subscription’s plan is 2 months and today is 14th April, changes_scheduled_at cannot be earlier than 14th February.

.
optional, timestamp(UTC) in seconds

credit_option_for_current_term_charges

For immediate cancellation (end_of_term = false), specify how to provide credits for current term charges. When not provided, the site default is considered.
optional, enumerated string

Possible values are

noneNo credits notes are created.prorateProrated credits are issued.fullCredits are issues for the full value of the current term charges.

unbilled_charges_option

For immediate cancellation (end_of_term = false), specify how to handle any unbilled charges. When not provided, the site default is considered.
optional, enumerated string

Possible values are

invoiceAn invoice is generated immediately with the unbilled charges.deleteThe unbilled charges are deleted.

account_receivables_handling

Applicable when the subscription has past due invoices. Specify this if you want to close the due invoices of the subscription. If specified as schedule_payment_collection/write_off, the due invoices of the subscription will be qualified for the selected operation after the remaining refundable credits and excess payments are applied. Note: The payment collection attempt will be asynchronous. Not applicable when 'end_of_term' is true.
optional, enumerated string

Possible values are

no_actionNo action is taken.schedule_payment_collectionAn automatic charge for the due amount of the past invoices will be attempted on the payment method available, if customer's auto-collection property is ‘ON’.write_offThe amount due in the invoices will be written-off. Credit notes created due to write-off will not be sent in the response.

refundable_credits_handling

Applicable when the customer has remaining refundable credits(issued against online payments). If specified as schedule_refund, the refund will be initiated for these credits after they are applied against the subscription’s past due invoices if any. Note: The refunds initiated will be asynchronous. Not applicable when 'end_of_term' is true.
optional, enumerated string

Possible values are

no_actionNo action is taken. .schedule_refundInitiates refund of the remaining credits.

contract_term_cancel_option

Cancels the current contract term.

terminate_immediately immediately does the following:
- sets the contract term status to terminated.
- Cancels the subscription.
- Collects any termination fee.
end_of_contract_term Sets the contract_term[action_at_term_end] to cancel. In other words, the contract term is not renewed and the subscription is canceled at the end of the contract term.

.
optional, enumerated string

Possible values are

terminate_immediatelyTerminate immediately.end_of_contract_termEnd of contract term.

invoice_date

The document date displayed on the invoice PDF. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. When not provided, the date is the same as cancel_at. Moreover, if create_pending_invoices is true, and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
It is not earlier than cancel_at.

.
optional, timestamp(UTC) in seconds

cancel_reason_code

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

The unique id of the charge item_price that represents the termination fee.
optional, string, max chars=100

subscription_items[quantity][0..n]

The quantity associated with the termination fee. Applicable only when the item_price for the termination charge is quantity-based.
optional, integer, min=1

subscription_items[quantity_in_decimal][0..n]

The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
optional, string, max chars=33

subscription_items[unit_price][0..n]

The termination fee. In case it is quantity-based, this is the fee per unit.
optional, in cents, min=0

subscription_items[unit_price_in_decimal][0..n]

subscription_items[service_period_days][0..n]

The service period of the termination fee—expressed in days—starting from the current date.
optional, integer, min=1, max=730

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Resource object representing unbilled_charge.
optional

Resource object representing credit_note.
optional

This operation supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.

This API is used to resume a paused subscription. On resumption the subscription will be activated and any applicable charges will be initiated.

You could schedule the resumption by passing specific_date parameter in resume_option. If scheduled, the subscription will be resumed on the specific_date and moved to Active state.

For in-term resumption, unless there are scheduled changes, unbilled charges will not be charged.

What is an "in-term resumption"?
An “in-term resumption” is when the pause and resumption happens within the billing term of the subscription.

Example : A subscription was billed from 1st to 31st of a month. It was paused on the 20th and resumed before 31st. This is an in-term resumption.

UNPAID INVOICES

Specifying unpaid_invoices allows you to close invoices of the subscription which have amounts due. The invoices are chosen for payment collection after applying the available credits and excess payments.

If specified as schedule_payment_collection, payment collection for the amount due of past invoices will be attempted. The payment method available will be charged if auto-collection is enabled for the customer, and appropriate payment collection(payment succeeded or payment failed) events will be triggered. If the payment collection fails, no further retries will be made on the invoices.

Note: If the invoices of the subscription are consolidated, and any of the subscriptions in the consolidated invoice are cancelled, these invoices will not be selected for collection.

Sample Request

# resumes a subscription immediately by scheduling payment collection for unpaid
# invoices.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdznTS0/resume \
     -X POST  \
     -u {site_api_key}:\
     -d resume_option="immediately" \
     -d unpaid_invoices_handling="schedule_payment_collection"

copy

# resumes a subscription immediately by scheduling payment collection for unpaid
# invoices.
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdznTS0/resume \
     -X POST  \
     -u {site_api_key}:\
     -d resume_option="immediately" \
     -d unpaid_invoices_handling="schedule_payment_collection"

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890935,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdziiRx",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890935000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890935
    },
    "subscription": {
        "activated_at": 1612890935,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890935,
        "currency_code": "USD",
        "current_term_end": 1615310135,
        "current_term_start": 1612890935,
        "customer_id": "__test__8asukSOXdziiRx",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890935,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdznTS0",
        "mrr": 0,
        "next_billing_at": 1615310135,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890936000,
        "started_at": 1612890935,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890936
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/resume

resume_option

List of options to resume the subscription.
optional, enumerated string

Possible values are

immediatelyResume immediately.specific_dateResume on a specific date.

resume_date

Date on which the subscription will be resumed. Applicable when resume_option is set as 'specific_date'.
optional, timestamp(UTC) in seconds

charges_handling

Applicable when charges get added during this operation and resume_option is set as 'immediately'. Allows to raise invoice immediately or add them to unbilled charges.
optional, enumerated string

Possible values are

invoice_immediatelyInvoice immediately.add_to_unbilled_chargesAdd to unbilled charges.

unpaid_invoices_handling

Applicable when the subscription has past due invoices and resume_option is set as 'immediately'. Allows to collect past due invoices or retain them as unpaid. If 'schedule_payment_collection' option is chosen in this field, remaining refundable credits and excess payments are applied. Note: The payment collection attempt will be asynchronous.
optional, enumerated string

Possible values are

no_actionRetain as unpaid.schedule_payment_collectionCollect payment.

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_information]

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.

.
optional, jsonobject

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

Resource object representing invoice.
optional

Resource object representing unbilled_charge.
optional

If the subscription is in Active or Non Renewing state and is also scheduled to pause at the end_of_term/specific_date, this API can be used to remove the scheduled pause.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdz1ERW/remove_scheduled_pause \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdz1ERW/remove_scheduled_pause \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890932,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdywZRT",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890932000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890932
    },
    "subscription": {
        "activated_at": 1612890932,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890932,
        "currency_code": "USD",
        "current_term_end": 1615310132,
        "current_term_start": 1612890932,
        "customer_id": "__test__8asukSOXdywZRT",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890932,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdz1ERW",
        "mrr": 0,
        "next_billing_at": 1615310132,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890933000,
        "started_at": 1612890932,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890933
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_pause

Resource object representing subscription.
always returned

Resource object representing customer.
always returned

Resource object representing card.
optional

If the subscription is in Paused state and is scheduled to resume on a specific_date, this API can be used to remove the scheduled resumption. When the scheduled resumption is removed, the subscription will remain Paused.

Sample Request

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdzOFRl/remove_scheduled_resumption \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdzOFRl/remove_scheduled_resumption \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890933,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXdzJFRi",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890933000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890933
    },
    "subscription": {
        "activated_at": 1612890934,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890934,
        "currency_code": "USD",
        "current_term_end": 1615310134,
        "current_term_start": 1612890934,
        "customer_id": "__test__8asukSOXdzJFRi",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890934,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXdzOFRl",
        "mrr": 0,
        "object": "subscription",
        "pause_date": 1612890934,
        "remaining_billing_cycles": 1,
        "resource_version": 1612890935000,
        "started_at": 1612890934,
        "status": "paused",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890935
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/remove_scheduled_resumption

Resource object representing subscription.
always returned

Resource object representing customer.
always returned