Maxio Advanced Billing
HomeSDKsAPI ReferenceContext Plugin
Subscriptions

List Subscriptions

GET
/subscriptions.json

Lists subscriptions for a site. Use the query string filters and pagination to control responses from the server.

If you have the new Catalog experience enabled, some subscriptions may not have an associated product. For subscriptions without an associated product, 'product', 'product_price_point_id', and 'product_price_point_type' are returned as 'null'.

Search for a subscription

Use the query strings below to search for a subscription using the criteria available. The return value will be an array.

Self-Service Page token

Self-Service Page token for the subscriptions is not returned by default. If this information is desired, the include[]=self_service_page_token parameter must be provided with the request.

Authorization

BasicAuth
AuthorizationBasic <token>

The username is a Maxio Chargify API key. The password is x.

In: header

Query Parameters

page?integer

Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query page=1.

Range1 <= value
Default1
per_page?integer

This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query per_page=200.

Rangevalue <= 200
Default20
sort?Subscription Sort

The attribute by which to sort

Default"signup_date"

Value in

  • "signup_date"
  • "period_start"
  • "period_end"
  • "next_assessment"
  • "updated_at"
  • "created_at"
  • "total_payments"
  • "id"
  • "open_balance"
  • "expires_at"
direction?Sorting direction

Controls the order in which results are returned. Use in query direction=asc.

Value in

  • "asc"
  • "desc"
state?Subscription State Filter

The current state of the subscription

Value in

  • "active"
  • "canceled"
  • "expired"
  • "expired_cards"
  • "expired_cards_(live_subscriptions)"
  • "expired_cards_(all_subscriptions)"
  • "on_hold"
  • "awaiting_signup"
  • "awaiting_signup_date"
  • "past_due"
  • "pending_cancellation"
  • "pending_renewal"
  • "prepaid_dunning"
  • "suspended"
  • "trial_ended"
  • "trialing"
  • "unpaid"
product?|

Filter subscriptions by product. Accepts product ID or exact product name. Product handle is not supported.

q?string

Search string.

q_scope?string

Scope of fields used by the q search.

Value in

  • "full_name"
  • "first_name"
  • "last_name"
  • "organization"
  • "customer_reference"
  • "subscription_reference"
customer_id?integer

The Advanced Billing id of the customer.

product_price_point_id?integer

The ID of the product price point. If supplied, product is required.

coupon?integer

The numeric id of the coupon currently applied to the subscription. (This can be found in the URL when editing a coupon. Note that the coupon code cannot be used.)

coupon_code?string

The coupon code currently applied to the subscription

collection_method?string

The collection method for the subscription.

Value in

  • "automatic"
  • "remittance"
  • "prepaid"
branding_theme_id?integer

Filter subscriptions by the ID of an assigned Branding Theme. Branding Themes is a beta feature. See Understand Branding Themes for more information.

date_field?Subscription Date Field

The type of filter you'd like to apply to your search. Allowed Values: , current_period_ends_at, current_period_starts_at, created_at, activated_at, canceled_at, expires_at, trial_started_at, trial_ended_at, updated_at

Value in

  • "current_period_ends_at"
  • "current_period_starts_at"
  • "created_at"
  • "activated_at"
  • "canceled_at"
  • "expires_at"
  • "trial_started_at"
  • "trial_ended_at"
  • "updated_at"
start_date?string

The start date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query start_date=2022-07-01.

Formatdate
end_date?string

The end date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query end_date=2022-08-01.

Formatdate
start_datetime?string

The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Use in query start_datetime=2022-07-01 09:00:05.

Formatdate-time
end_datetime?string

The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Use in query end_datetime=2022-08-01 10:00:05.

Formatdate-time
metadata?

The value of the metadata field specified in the parameter. Use in query metadata[my-field]=value&metadata[other-field]=another_value.

group_status?string

Filter by whether a subscription is in a group.

Value in

  • "ungrouped"
  • "grouped"
dunning_exemption?boolean

Filter by dunning exemption status.

payment_gateways?string

Comma-separated payment gateway identifiers.

currencies?string

Comma-separated currency codes.

include?array<>

Allows including additional data in the response. Use in query: include[]=self_service_page_token.

Response Body

application/json

curl -X GET "https://example.com/subscriptions.json"
[  {    "subscription": {      "id": 0,      "state": "pending",      "balance_in_cents": 0,      "total_revenue_in_cents": 0,      "product_price_in_cents": 0,      "product_version_number": 0,      "current_period_ends_at": "2019-08-24T14:15:22Z",      "next_assessment_at": "2019-08-24T14:15:22Z",      "trial_started_at": "2019-08-24T14:15:22Z",      "trial_ended_at": "2019-08-24T14:15:22Z",      "activated_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "cancellation_message": "string",      "cancellation_method": "merchant_ui",      "cancel_at_end_of_period": true,      "canceled_at": "2019-08-24T14:15:22Z",      "current_period_started_at": "2019-08-24T14:15:22Z",      "previous_state": "pending",      "signup_payment_id": 0,      "signup_revenue": "string",      "delayed_cancel_at": "2019-08-24T14:15:22Z",      "coupon_code": "string",      "snap_day": "string",      "payment_collection_method": "automatic",      "customer": {        "first_name": "string",        "last_name": "string",        "email": "string",        "cc_emails": "string",        "organization": "string",        "reference": "string",        "id": 0,        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z",        "address": "string",        "address_2": "string",        "city": "string",        "state": "string",        "state_name": "string",        "zip": "string",        "country": "string",        "country_name": "string",        "phone": "string",        "verified": true,        "portal_customer_created_at": "2019-08-24T14:15:22Z",        "portal_invite_last_sent_at": "2019-08-24T14:15:22Z",        "portal_invite_last_accepted_at": "2019-08-24T14:15:22Z",        "tax_exempt": true,        "surcharging": true,        "vat_number": "string",        "vat_country": "string",        "entity_identifier_kind": "vat_eu",        "entity_identifier_value": "string",        "parent_id": 0,        "locale": "string",        "default_subscription_group_uid": "string",        "salesforce_id": "string",        "tax_exempt_reason": "string",        "default_auto_renewal_profile_id": 0,        "maxioid": "string",        "branding_theme_id": 0      },      "product": {        "id": 0,        "name": "string",        "handle": "string",        "description": "string",        "accounting_code": "string",        "request_credit_card": true,        "expiration_interval": 0,        "expiration_interval_unit": "day",        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z",        "price_in_cents": 0,        "interval": 0,        "interval_unit": "day",        "initial_charge_in_cents": 0,        "trial_price_in_cents": 0,        "trial_interval": 0,        "trial_interval_unit": "day",        "archived_at": "2019-08-24T14:15:22Z",        "require_credit_card": true,        "return_params": "string",        "taxable": true,        "update_return_url": "string",        "initial_charge_after_trial": true,        "version_number": 0,        "update_return_params": "string",        "product_family": {          "id": 0,          "name": "string",          "handle": "string",          "accounting_code": null,          "description": "string",          "surcharging": true,          "created_at": "2019-08-24T14:15:22Z",          "updated_at": "2019-08-24T14:15:22Z",          "archived_at": "2019-08-24T14:15:22Z"        },        "public_signup_pages": [          {            "id": 0,            "return_url": "string",            "return_params": "string",            "url": "string"          }        ],        "product_price_point_name": "string",        "request_billing_address": true,        "require_billing_address": true,        "require_shipping_address": true,        "tax_code": "string",        "default_product_price_point_id": 0,        "use_site_exchange_rate": true,        "item_category": "string",        "product_price_point_id": 0,        "product_price_point_handle": "string",        "unspsc_code": "string",        "features": [          {            "id": 0,            "feature_template_id": 0,            "feature_key": "string",            "feature_name": "string",            "feature_kind": "access_right",            "value": "string",            "periodicity_interval": 0,            "periodicity_unit": "hour",            "price_point_type": "ProductPricePoint",            "price_point_id": 0,            "archived_at": "2019-08-24T14:15:22Z",            "created_at": "2019-08-24T14:15:22Z",            "updated_at": "2019-08-24T14:15:22Z"          }        ]      },      "credit_card": {        "id": 10088716,        "first_name": "Test",        "last_name": "Subscription",        "masked_card_number": "XXXX-XXXX-XXXX-1",        "card_type": "bogus",        "expiration_month": 1,        "expiration_year": 2022,        "customer_id": 14543792,        "current_vault": "bogus",        "vault_token": "1",        "billing_address": "123 Montana Way",        "billing_city": "Billings",        "billing_state": "MT",        "billing_zip": "59101",        "billing_country": "US",        "customer_vault_token": null,        "billing_address_2": "",        "payment_type": "credit_card",        "site_gateway_setting_id": 1,        "gateway_handle": null      },      "group": {        "uid": "string",        "scheme": 0,        "primary_subscription_id": 0,        "primary": true      },      "bank_account": {        "id": 0,        "first_name": "string",        "last_name": "string",        "customer_id": 0,        "current_vault": "authorizenet",        "vault_token": "string",        "billing_address": "string",        "billing_city": "string",        "billing_state": "string",        "billing_zip": "string",        "billing_country": "string",        "customer_vault_token": "string",        "billing_address_2": "string",        "bank_name": "string",        "masked_bank_routing_number": "string",        "masked_bank_account_number": "string",        "bank_account_type": "checking",        "bank_account_holder_type": "personal",        "payment_type": "bank_account",        "verified": false,        "site_gateway_setting_id": 0,        "gateway_handle": "string",        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z"      },      "payment_type": "string",      "referral_code": "string",      "next_product_id": 0,      "next_product_handle": "string",      "coupon_use_count": 0,      "coupon_uses_allowed": 0,      "reason_code": "string",      "automatically_resume_at": "2019-08-24T14:15:22Z",      "coupon_codes": [        "string"      ],      "offer_id": 0,      "payer_id": 0,      "current_billing_amount_in_cents": 0,      "product_price_point_id": 0,      "product_price_point_type": "catalog",      "next_product_price_point_id": 0,      "net_terms": 0,      "stored_credential_transaction_id": 0,      "reference": "string",      "on_hold_at": "2019-08-24T14:15:22Z",      "prepaid_dunning": true,      "coupons": [        {          "code": "string",          "use_count": 0,          "uses_allowed": 0,          "expires_at": "string",          "recurring": true,          "amount_in_cents": 0,          "percentage": "string"        }      ],      "dunning_communication_delay_enabled": true,      "dunning_communication_delay_time_zone": "string",      "receives_invoice_emails": true,      "locale": "string",      "currency": "string",      "scheduled_cancellation_at": "2019-08-24T14:15:22Z",      "credit_balance_in_cents": 0,      "prepayment_balance_in_cents": 0,      "prepaid_configuration": {        "id": 0,        "initial_funding_amount_in_cents": 0,        "replenish_to_amount_in_cents": 0,        "auto_replenish": true,        "replenish_threshold_amount_in_cents": 0      },      "self_service_page_token": "string"    }  }]

List Subscription Components for Site GET

Lists components applied to each subscription.

Create Subscription POST

Creates a Subscription for a customer and product. Specify the product with `product_id` or `product_handle`. To set a specific product price point, use `product_price_point_handle` or `product_price_point_id`. Identify an existing customer with `customer_id` or `customer_reference`. Optionally, include an existing payment profile using `payment_profile_id`. To create a new customer, pass customer_attributes. Select an option from the **Request Examples** drop-down on the right side of the portal to see examples of common scenarios for creating subscriptions. ## List vs Sales Pricing When a subscription uses custom pricing as the sales price, you can optionally provide a list price for any item. If omitted, the list price defaults to the sales price. The difference between the list price and sales price is used to calculate implicit discounts, which appear on Invoices and in reporting. List price can also support revenue allocations in [Advanced Revenue](https://docs.maxio.com/hc/en-us/articles/24177001342861-Create-and-Configure-RevenueBooks). If your site has list pricing enabled, the API accepts `custom_price.list_price_point_id` for custom pricing, validates and persists it, and returns list price metadata in subscription responses. If list pricing is disabled, this input is ignored and related response fields are omitted. When list pricing is enabled: - Subscription → Product `product_price_point_list_price_point_id` (integer) - `product_price_point_list_price_point_handle` (string) - Subscription Components (when components are included in the response, such as with subscriptions built from components or component serialization paths) `component_id` (integer) - `price_point_id` (integer) - `list_price_point_id` (integer) When list pricing is disabled: - Subscription → Product `product_price_point_list_price_point_id`: omitted - `product_price_point_list_price_point_handle`: omitted - Subscription Components `list_price_point_id`: omitted This functionality is supported in the API, but is not currently supported in SDKs. ## Subscriptions can now work independently from the catalog If you have the new [Catalog experience](https://maxio-test-wp.pages.dev/support/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, you can create subscriptions without a `product_id` or `product_handle` using POST /subscriptions, building them entirely from components. A valid subscription must include at least one active component with: - a positive `allocated_quantity`, - a positive `unit_balance`, or - 'enabled: true' (for on/off components) - a configured metered component `component_id` can be provided as a numeric ID or in handle: format. If `trial_interval` and `trial_interval_unit` are included, they are applied at creation. In the response, product and product price point fields are null, and component details are returned instead. This functionality is supported in the API, but is not currently supported in SDKs. ## Payment information Payment information may be required to create a subscription, depending on the options for the Product being subscribed. See [product options](https://docs.maxio.com/hc/en-us/articles/24261076617869-Edit-Products) for more information. See the [Payments Profile](https://maxio-test-wp.pages.dev/api/openapi/payment-profiles/createPaymentProfile) endpoint for details on payment parameters. See the [Subscription Signups](https://maxio-test-wp.pages.dev/getting-started/basic-concepts/subscription-signup) article for more information on working with subscriptions in Advanced Billing. ## Payment information Payment information may be required to create a subscription, depending on the options for the Product being subscribed. See [product options](https://docs.maxio.com/hc/en-us/articles/24261076617869-Edit-Products) for more information. See the [Payments Profile](https://maxio-test-wp.pages.dev/api/openapi/payment-profiles/createPaymentProfile) endpoint for details on payment parameters. Do not use real card information for testing. See the Sites articles that cover [testing your site setup](https://docs.maxio.com/hc/en-us/articles/24250712113165-Testing-Overview#testing-overview-0-0) for more details on testing in your sandbox. Note that collecting and sending raw card details in production requires [PCI compliance](https://docs.maxio.com/hc/en-us/articles/24183956938381-PCI-Compliance#pci-compliance-0-0) on your end. If your business is not PCI compliant, use [Maxio.js (formerly Chargify.js)](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview#chargify-js-overview-0-0) to collect credit card or bank account information. ## 3D Secure (3DS) Authentication post-authentication flow When a payment requires 3DS Authentication to adhere to Strong Customer Authentication (SCA), the request enters a post-authentication flow where a 422 Unprocessable Entity status is returned with an action_link that will direct the customer through 3DS Authentication. See the [3D Secure Post-Authentication Flow](https://docs.maxio.com/hc/en-us/articles/44277749524365-3D-Secure-Post-Authentication-Flow) article in the product documentation to learn how to manage the redirect flow.