Endpoint responsável por listar assinaturas cadastradas na conta Asaas de acordo com os filtros informados.

Diferente da recuperação de uma assinatura específica, este endpoint retorna uma lista paginada de assinaturas, permitindo consultar assinaturas por cliente, forma de pagamento, status, referência externa, grupo de clientes ou situação de remoção.

Esse recurso é indicado para integrações que precisam consultar assinaturas em lote, sincronizar dados com sistemas externos, alimentar rotinas de conciliação, montar telas administrativas ou localizar assinaturas antes de realizar ações como consulta individual, atualização ou cancelamento.

📘

Guia de Assinaturas

Para entender o funcionamento completo de assinaturas, recorrência, criação de cobranças e ciclo de vida do recurso, consulte o guia de Assinaturas.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• listar assinaturas cadastradas na conta;
• consultar todas as assinaturas de um cliente específico;
• filtrar assinaturas por forma de pagamento;
• localizar assinaturas ativas, inativas ou expiradas;
• buscar assinaturas vinculadas a uma referência do seu sistema;
• sincronizar assinaturas com ERPs, CRMs, dashboards ou sistemas internos;
• recuperar assinaturas removidas, quando necessário.

Para consultar os dados de uma única assinatura, utilize o endpoint de recuperação individual informando o identificador da assinatura.

Paginação

A listagem de assinaturas é paginada.

Use os parâmetros limit e offset para controlar a quantidade de registros retornados e a posição inicial da consulta.

Exemplo de primeira página:

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

Exemplo de próxima página:

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

Para percorrer todos os resultados, incremente o offset de acordo com o limit utilizado até que não existam mais registros a serem retornados.

📘

Recomendado

Em integrações com grande volume de assinaturas, utilize paginação com limit=100 e processe os dados em lotes, evitando consultas repetitivas ou desnecessárias.

Filtros disponíveis

Os filtros podem ser utilizados para restringir o retorno da listagem.

Os filtros podem ser combinados para tornar a consulta mais específica.

Exemplo:

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

🚧

Atenção

Quando utilizar o filtro customer, informe um cliente existente e pertencente à conta autenticada pela API Key. Caso o identificador não exista ou não pertença à conta, nenhuma assinatura será retornada para esse filtro.

Formas de pagamento

O filtro billingType permite listar assinaturas de acordo com a forma de pagamento configurada.

Valores aceitos:

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

Exemplo:

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

Use esse filtro quando sua integração precisar separar assinaturas por meio de pagamento, como assinaturas em cartão de crédito, Pix ou boleto.

Status da assinatura

O filtro status permite listar assinaturas conforme sua situação atual.

Valores aceitos:

• ACTIVE
• EXPIRED
• INACTIVE

Exemplo:

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

Esse filtro é útil para rotinas que precisam considerar apenas assinaturas ativas ou identificar assinaturas encerradas/inativas para atualização em sistemas externos.

Consulta por cliente

Para listar assinaturas de um cliente específico, utilize o parâmetro customer com o identificador único do cliente no Asaas.

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

Esse filtro é indicado para telas de detalhe do cliente, rotinas de conciliação por pagador ou verificações antes de criar uma nova assinatura.

📘

Boas práticas

Armazene o identificador do cliente retornado pelo Asaas no momento da criação do cadastro. Embora seja possível buscar clientes por outros dados, o ID do cliente é a forma mais segura de relacionar assinaturas ao pagador correto.

Consulta por referência externa

Caso sua integração envie o campo externalReference na criação da assinatura, ele pode ser utilizado posteriormente para localizar registros vinculados ao identificador do seu sistema.

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

Esse filtro é recomendado para integrações que precisam conciliar dados entre o Asaas e sistemas próprios, como ERPs, CRMs ou plataformas SaaS.

Assinaturas removidas

Por padrão, a listagem pode não considerar assinaturas removidas conforme o filtro utilizado.

Para consultar somente assinaturas removidas, utilize:

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

Para incluir assinaturas removidas junto às demais, utilize:

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

🚧

Atenção

Utilize deletedOnly quando a intenção for retornar apenas registros removidos. Utilize includeDeleted quando a intenção for manter a listagem geral e também incluir assinaturas removidas no resultado.

Comportamentos importantes

Ao utilizar este endpoint, considere que:

• a listagem retorna apenas assinaturas da conta autenticada pela API Key;
• chamadas sem filtros retornam uma listagem paginada das assinaturas da conta;
• filtros podem ser combinados para reduzir o volume de dados retornados;
• o retorno pode ser vazio caso nenhum registro corresponda aos filtros informados;
• assinaturas removidas dependem do uso de deletedOnly ou includeDeleted;
• consultas com grande volume devem utilizar paginação;
• chamadas GET devem ser enviadas sem body.

❗️

Atenção

Requisições GET com body preenchido podem retornar erro 403. Envie os filtros sempre como query params na URL.

Exemplos de uso

Listar assinaturas de um cliente específico:

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

Filtrar assinaturas por forma de pagamento:

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

Listar assinaturas ativas em cartão de crédito:

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

Listar assinaturas com paginação:

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

Listar assinaturas por referência externa:

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

Boas práticas

• Utilize filtros sempre que possível para reduzir o volume retornado.
• Utilize paginação em consultas recorrentes ou com grande volume.
• Armazene o ID da assinatura retornado pelo Asaas para consultas futuras.
• Armazene o ID do cliente para evitar buscas imprecisas.
• Utilize externalReference para conciliar dados com o seu sistema.
• Trate respostas vazias como um cenário esperado.
• Não envie body em requisições GET.
• Evite executar listagens completas com alta frequência quando filtros mais específicos puderem ser utilizados.

Erros comuns

400 Bad Request

Pode ocorrer quando algum filtro é enviado com valor inválido, como um billingType ou status não aceito.

401 Unauthorized

Ocorre quando a API Key não foi informada, está inválida ou não corresponde ao ambiente utilizado.

403 Forbidden

Pode ocorrer quando a requisição GET é enviada com body preenchido. Chamadas de listagem devem utilizar apenas query params.

Retorno vazio

Pode ocorrer quando não existem assinaturas para os filtros informados, quando o cliente informado não possui assinaturas ou quando o identificador enviado não pertence à conta autenticada.

Impactos operacionais

Listagens de assinaturas podem envolver grande volume de dados, especialmente em contas com muitas recorrências ativas.

Para evitar lentidão, consumo desnecessário de limite de API ou processamento excessivo na aplicação, recomenda-se:

• consultar por cliente quando possível;
• utilizar filtros de status, forma de pagamento ou referência externa;
• processar resultados paginados em lotes;
• evitar sincronizações completas em intervalos muito curtos;
• armazenar localmente os identificadores retornados pela API.

Conteúdos relacionados

• Criar assinatura
• Recuperar uma única assinatura
• Atualizar assinatura
• Remover assinatura
• Criar cliente
• Listar clientes
• Autenticação da API
• Paginação
• Limites da API
• Webhooks de cobrança e Webhooks de assinatura.