Endpoint responsible for listing subscriptions registered in the Asaas account according to the provided filters.

Unlike retrieving a specific subscription, this endpoint returns a paginated list of subscriptions, allowing subscriptions to be queried by customer, payment method, status, external reference, customer group, or deletion status.

This resource is recommended for integrations that need to query subscriptions in bulk, synchronize data with external systems, feed reconciliation routines, build administrative screens, or locate subscriptions before performing actions such as individual retrieval, update, or cancellation.

📘

Subscription Guide

To understand the complete behavior of subscriptions, recurrence, charge creation, and the resource lifecycle, refer to the Subscription guide.

When to use

Use this endpoint when your integration needs to:

• list subscriptions registered in the account;
• retrieve all subscriptions from a specific customer;
• filter subscriptions by payment method;
• locate active, inactive, or expired subscriptions;
• search for subscriptions linked to a reference from your system;
• synchronize subscriptions with ERPs, CRMs, dashboards, or internal systems;
• retrieve deleted subscriptions, when necessary.

To retrieve the data of a single subscription, use the individual retrieval endpoint by providing the subscription identifier.

Pagination

Subscription listing is paginated.

Use the limit and offset parameters to control the number of records returned and the starting position of the query.

Example of the first page:

GET https://api.asaas.com/v3/subscriptions?limit=100&offset=0

Example of the next page:

GET https://api.asaas.com/v3/subscriptions?limit=100&offset=100

To iterate through all results, increment offset according to the limit used until there are no more records to be returned.

📘

Recommended

For integrations with a large volume of subscriptions, use pagination with limit=100 and process the data in batches, avoiding repetitive or unnecessary queries.

Available filters

Filters can be used to restrict the returned list.

Filters can be combined to make the query more specific.

Example:

GET https://api.asaas.com/v3/subscriptions?customer={customer_id}&billingType=CREDIT_CARD&status=ACTIVE

🚧

Attention

When using the customer filter, provide an existing customer belonging to the account authenticated by the API Key. If the identifier does not exist or does not belong to the account, no subscription will be returned for this filter.

Payment methods

The billingType filter allows subscriptions to be listed according to the configured payment method.

Accepted values:

• UNDEFINED
• BOLETO
• CREDIT_CARD
• DEBIT_CARD
• TRANSFER
• DEPOSIT
• PIX

Example:

GET https://api.asaas.com/v3/subscriptions?billingType=CREDIT_CARD

Use this filter when your integration needs to separate subscriptions by payment method, such as credit card, Pix, or boleto subscriptions.

Subscription status

The status filter allows subscriptions to be listed according to their current status.

Accepted values:

• ACTIVE
• EXPIRED
• INACTIVE

Example:

GET https://api.asaas.com/v3/subscriptions?status=ACTIVE

This filter is useful for routines that need to consider only active subscriptions or identify expired/inactive subscriptions for updates in external systems.

Query by customer

To list subscriptions for a specific customer, use the customer parameter with the unique customer identifier in Asaas.

GET https://api.asaas.com/v3/subscriptions?customer={customer_id}

This filter is recommended for customer detail screens, payer reconciliation routines, or checks before creating a new subscription.

📘

Best practices

Store the customer identifier returned by Asaas when creating the customer. Although it is possible to search for customers using other data, the customer ID is the safest way to associate subscriptions with the correct payer.

Query by external reference

If your integration sends the externalReference field when creating the subscription, it can later be used to locate records linked to your system identifier.

GET https://api.asaas.com/v3/subscriptions?externalReference={internal_reference}

This filter is recommended for integrations that need to reconcile data between Asaas and proprietary systems, such as ERPs, CRMs, or SaaS platforms.

Deleted subscriptions

By default, the listing may not consider deleted subscriptions depending on the filter used.

To retrieve only deleted subscriptions, use:

GET https://api.asaas.com/v3/subscriptions?deletedOnly=true

To include deleted subscriptions together with the others, use:

GET https://api.asaas.com/v3/subscriptions?includeDeleted=true

🚧

Attention

Use deletedOnly when the intention is to return only deleted records. Use includeDeleted when the intention is to keep the general listing and also include deleted subscriptions in the result.

Important behaviors

When using this endpoint, consider that:

• the listing returns only subscriptions from the account authenticated by the API Key;
• requests without filters return a paginated listing of the account subscriptions;
• filters can be combined to reduce the volume of data returned;
• the response may be empty if no record matches the provided filters;
• deleted subscriptions depend on the use of deletedOnly or includeDeleted;
• large-volume queries should use pagination;
• GET requests must be sent without a body.

❗️

Attention

GET requests with a body may return a 403 error. Always send the filters as query params in the URL.

Usage examples

List subscriptions for a specific customer:

GET https://api.asaas.com/v3/subscriptions?customer={customer_id}

Filter subscriptions by payment method:

GET https://api.asaas.com/v3/subscriptions?billingType=CREDIT_CARD

List active credit card subscriptions:

GET https://api.asaas.com/v3/subscriptions?billingType=CREDIT_CARD&status=ACTIVE

List subscriptions with pagination:

GET https://api.asaas.com/v3/subscriptions?limit=100&offset=0

List subscriptions by external reference:

GET https://api.asaas.com/v3/subscriptions?externalReference={internal_reference}

Best practices

• Use filters whenever possible to reduce the returned volume.

• Use pagination for recurring queries or large volumes.

• Store the subscription ID returned by Asaas for future queries.

• Store the customer ID to avoid inaccurate searches.

• Use externalReference to reconcile data with your system.

• Treat empty responses as an expected scenario.

• Do not send a body in GET requests.

• Avoid performing full listings at high frequency when more specific filters can be used.

Common errors

400 Bad Request

May occur when a filter is sent with an invalid value, such as an unsupported billingType or status.

401 Unauthorized

Occurs when the API Key was not provided, is invalid, or does not correspond to the environment being used.

403 Forbidden

May occur when the GET request is sent with a body. Listing requests should use query params only.

Empty response

May occur when there are no subscriptions for the provided filters, when the specified customer has no subscriptions, or when the identifier sent does not belong to the authenticated account.

Operational impacts

Subscription listings may involve a large volume of data, especially for accounts with many active recurring subscriptions.

To avoid slowness, unnecessary API limit consumption, or excessive application processing, it is recommended to:

• query by customer whenever possible;

• use status, payment method, or external reference filters;

• process paginated results in batches;

• avoid full synchronizations at very short intervals;

• store locally the identifiers returned by the API.

Related content

• Create subscription

• Retrieve a single subscription

• Update subscription

• Delete subscription

• Create customer

• List customers

• API authentication

• Pagination

• API limits

• Payment webhooks and Subscription webhooks.