Skip to main content
GET
List (All) Subscriptions

Authorizations

Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Query Parameters

limit
integer<int32>
default:20

A limit on the number of objects to be returned, between 1 and 100.

Required range: 1 <= x <= 100
starting_after
string

A cursor for use in pagination. starting_after is an object id that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

ending_before
string

A cursor for use in pagination. ending_before is an object id that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

account
string
required

Limit the subscription list to a specified account id or vid - all Subscriptions associated with that Account are displayed. A unique identifier. Optionally, this object can also be identified by its vid. Using a unique custom identifier is strongly encouraged.

Maximum string length: 128
include_children
boolean
default:false

Indicates whether or not to return any existing child accounts’ subscriptions for a given returned Subscription/account combination.

status
enum<string>

Filters the list of accounts by status. Can be:

  • Active
  • Cancelled
  • Expired
  • Paused
  • Pending Activation
  • Pending Cancel
  • Pending Pause
  • Pending Resume
  • Processing
Available options:
Active,
Cancelled,
Expired,
Pending Activation,
Pending Cancel,
Processing,
Pending Pause,
Paused,
Pending Resume
email
string<email>

Limit the Subscription list to subscriptions associated with the listed account and with a specific email.

primary_product
string
product
string

Limit the Subscription list to those subscriptions associated with the listed account and with the specified product id or vid as a SubscriptionItem. A unique identifier. Optionally, this object can also be identified by its vid. Using a unique custom identifier is strongly encouraged.

Maximum string length: 128

Response

JSON A list array with a data property that contains an array of up to limit Subscriptions, starting after the specified starting_after Subscription (or ending before the specified ending_before Subscription). Each entry in the array is a full Subscription object. If no more Subscriptions are available, the resulting array will be empty. This request should never throw an error.

A list of Subscription objects matching the query. Also:

  • "total_count": Integer count of the number of TimeInterval in the returned list.

  • "url": The query string provided in the request

  • "next": The route (partial URL) to the next TimeInterval object (string to select the "next"); included vid should match that of the last object returned here

  • "previous": The route (partial URL) to the previous TimeInterval object (string to select the "previous"); included vid should match that of the first object returned here

object
enum<string>
Available options:
List
total_count
integer

Integer count of the number of items in the returned list.

data
object[]
url
string

The query string provided in the request

next
string

The route (partial URL) to the next Subscription object (string to select the “next”); included id should match that of the last object returned here

previous
string

The route (partial URL) to the previous Subscriptions object (string to select the “previous”); included id should match that of the first object returned here

Example:

"{ \"object\": \"List\", \"data\": [ { \"object\": \"Subscription\", \"id\": \"sub_12345\", \"vid\": \"b25ba01e345b0ec3855c0323ce0f56e02ca839fb\", \"created\": \"2023-01-20T13:25:01+00:00\", \"account\": { \"object\": \"Account\", \"id\": \"cust_2234\", \"external_id\": \"Ext_2234\", \"vid\": \"0cdae787f01facd2d86a7d48c6529b5679c7cfbe\", \"created\": \"2023-01-20T13:35:11+00:00\", \"default_currency\": \"USD\", \"email\": \"rbrown@example.com\", \"email_type\": \"html\", \"language\": \"EN-U\", \"notify_before_billing\": true, \"company\": \"Peanuts\", \"name\": \"Robbert Brown\", \"shipping_address\": { \"object\": \"Address\", \"vid\": \"ae42d842242e3c8c5928f093be9d1f9ad82f7dd7\", \"name\": \"Robbert Brown\", \"line1\": \"123 Main Street\", \"city\": \"San Francisco\", \"district\": \"CA\", \"postal_code\": \"94105\", \"country\": \"US\", \"phone\": \"415-555-3212\" }, \"metadata\": { \"favorite dog\": \"Snoopy\", \"favorite activity\": \"flying kites\" } }, \"billing_plan\": { \"object\": \"BillingPlan\", \"id\": \"plan_1234\", \"vid\": \"a5e4eb7e26b81138e91d9042973d41e797072344\", \"created\": \"2023-01-20T13:22:42+00:00\", \"description\": \"Simple Monthly Plan with Trial\", \"status\": \"Active\", \"trial\": { \"object\": \"BillingPlanPeriod\", \"type\": \"Day\", \"quantity\": 7, \"cycles\": 1, \"prices\": { \"object\": \"List\", \"data\": [ { \"object\": \"BillingPlanPrice\", \"amount\": 0, \"currency\": \"USD\" } ], \"total_count\": 1 }, \"do_not_notify_first_bill\": false }, \"periods\": { \"object\": \"List\", \"data\": [ { \"object\": \"BillingPlanPeriod\", \"type\": \"Month\", \"quantity\": 1, \"cycles\": 1, \"prices\": { \"object\": \"List\", \"data\": [ { \"object\": \"BillingPlanPrice\", \"amount\": 49.99, \"currency\": \"USD\" } ], \"total_count\": 1 } } ], \"total_count\": 1 }, \"skip_initial_billing_notification\": false, \"metadata\": { \"plan info\": \"trial billing plan\" }, \"entitlements\": { \"object\": \"List\", \"data\": [ { \"object\": \"Entitlement\", \"id\": \"ent_p1235\", \"description\": \"Access to ent_p1235\" } ], \"total_count\": 1 }, \"times_to_run\": \"1\", \"used_on_subscriptions\": true }, \"payment_method\": { \"object\": \"PaymentMethod\", \"id\": \"paymentMethod_1234\", \"vid\": \"7d372db846a01aafbae14807b94a221313cf6d5a\", \"created\": \"2023-01-20T13:20:05+00:00\", \"type\": \"CreditCard\", \"credit_card\": { \"object\": \"CreditCard\", \"vid\": \"c840fd31aed4346f92a617886cbfc147034f6bd7\", \"account\": \"341111XXXXX1111\", \"bin\": \"341111\", \"type\": \"AX\", \"last_digits\": \"1111\", \"account_length\": 15, \"expiration_date\": \"202605\", \"last_au_request_date\": null, \"last_update_date\": null }, \"account_holder\": \"Charles Brown\", \"billing_address\": { \"object\": \"Address\", \"vid\": \"519bd0405f9ca442868a1c98b603055ad09bc54c\", \"name\": \"Charlie Brown\", \"line1\": \"123 Main Street\", \"city\": \"San Francisco\", \"district\": \"CA\", \"postal_code\": \"94105\", \"country\": \"US\", \"phone\": \"415-555-3212\" }, \"customer_specified_type\": \"Personal Amex\", \"primary\": true, \"active\": true, \"linked_subscription\": true }, \"currency\": \"USD\", \"description\": \"Subscription_2234\", \"status\": \"Pending Cancel\", \"billing_state\": \"Billing Completed\", \"starts\": \"2023-01-20T05:52:02+00:00\", \"ends\": \"2023-01-26T00:00:00+00:00\", \"entitled_through\": \"2023-01-26T00:00:00+00:00\", \"items\": { \"object\": \"List\", \"data\": [ { \"object\": \"SubscriptionItem\", \"id\": \"sub_1234.1\", \"vid\": \"fe5b615735fc3d7c5544adddf99c38bae714e9bc\", \"index\": 0, \"product\": { \"object\": \"Product\", \"id\": \"prod_1234\", \"vid\": \"f549e4f493c23e16c3d7b74ebb51358ade375d11\", \"created\": \"2023-01-20T13:19:33+00:00\", \"status\": \"Active\", \"tax_classification\": \"TaxExempt\", \"prices\": { \"object\": \"List\", \"data\": [ { \"object\": \"ProductPrice\", \"amount\": 200, \"currency\": \"USD\" } ], \"total_count\": 1 } }, \"quantity\": 1, \"created\": \"2023-01-20T05:52:02+00:00\", \"ends\": \"2023-01-26T00:00:00+00:00\", \"starts\": \"2023-01-19T00:00:00+00:00\", \"discount_tickets\": { \"object\": \"List\", \"data\": [], \"total_count\": 0 } } ], \"total_count\": 1 }, \"billing_day\": 26, \"minimum_commitment\": 0, \"notify_on_transition\": false, \"cancel_reason\": { \"object\": \"CancelReason\", \"reason_code\": \"101\", \"description\": \"Merchant: Prevent Auto-Renewal\" }, \"balance\": 0 } ], \"total_count\": 1, \"url\": \"/subscriptions?account=cust_2234\", \"next\": \"/subscriptions?account=cust_2234&starting_after=sub_12345\", \"previous\": \"/subscriptions?account=cust_2234&ending_before=sub_12345\" }"