ChargebeeAPI

List subscriptions

Try in API Explorer

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

Sample Request

URL Format

GET https://[site].chargebee.com/api/v2/subscriptions

Input Parameters

include_deleted
optional, boolean, default=false

Indicates whether to include deleted objects in the list. The deleted objects have the attribute deleted as true .

Filter Params

For operator usages, see the Pagination and Filtering section.
id[<operator>]

optional, string filter

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"

Supported operators: is, is_not, starts_with, in, not_in
customer_id[<operator>]

optional, string filter

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"

Supported operators: is, is_not, starts_with, in, not_in
item_id[<operator>]

optional, string filter

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

Example → item_id[is_not] = "silver"

Supported operators: is, is_not, starts_with, in, not_in
item_price_id[<operator>]

optional, string filter

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

Example → item_price_id[is] = "silver-USD-monthly"

Supported operators: is, is_not, starts_with, in, not_in
status[<operator>]

optional, enumerated string filter

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_not] = "active"

Supported operators: is, is_not, in, not_in
cancel_reason[<operator>]

optional, enumerated string filter

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"

Supported operators: is, is_not, in, not_in, is_present
cancel_reason_code[<operator>]

optional, string filter

Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation. Must be passed if set as mandatory in the app. The codes are case-sensitive. Supported operators : is, is_not, starts_with, in, not_in

Example → cancel_reason_code[is] = "Not Paid"

Supported operators: is, is_not, starts_with, in, not_in
remaining_billing_cycles[<operator>]

optional, integer filter

  • 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_not] = "3"

Supported operators: is, is_not, lt, lte, gt, gte, between, is_present
created_at[<operator>]

optional, timestamp(UTC) in seconds filter

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

Example → created_at[before] = "1435054328"

Supported operators: after, before, on, between
activated_at[<operator>]

optional, timestamp(UTC) in seconds filter

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[after] = "1435054328"

Supported operators: after, before, on, between, is_present
next_billing_at[<operator>]

optional, timestamp(UTC) in seconds filter

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[after] = "1435054328"

Supported operators: after, before, on, between
cancelled_at[<operator>]

optional, timestamp(UTC) in seconds filter

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

Example → cancelled_at[after] = "1435054328"

Supported operators: after, before, on, between
has_scheduled_changes[<operator>]

optional, boolean filter

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

Supported operators : is

Example → has_scheduled_changes[is] = "true"

Supported operators: is
updated_at[<operator>]

optional, timestamp(UTC) in seconds filter

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[after] = "1243545465"

Supported operators: after, before, on, between
offline_payment_method[<operator>]

optional, enumerated string filter

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_not] = "cash"

Supported operators: is, is_not, in, not_in
auto_close_invoices[<operator>]

optional, boolean filter

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"

Supported operators: is
override_relationship[<operator>]

optional, boolean filter

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"

Supported operators: is
business_entity_id[<operator>]

optional, string filter

The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

Supported operators : is, is_not, starts_with

Example → business_entity_id[is_not] = "business_entity_id"

Supported operators: is
channel[<operator>]

optional, enumerated string filter

The subscription channel this object originated from and is maintained in. Possible values are : web, app_store, play_store.

Supported operators : is, is_not, in, not_in

Example → channel[is_not] = "APP STORE"

Supported operators: is, is_not, in, not_in

Returns

next_offsetoptional, string, max chars=1000

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.

subscriptionSubscription object

Resource object representing subscription

customerCustomer object

Resource object representing customer

cardCard object

Resource object representing card