> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar assinaturas
> Lista paginada das assinaturas da conta, com filtros por estado, cliente, plano, forma de pagamento e data.
`GET /subscriptions`
Faz parte do recurso [Assinaturas](/pt-BR/subscriptions) — o conceito e os dez estados estão lá.
Devolve as assinaturas da sua conta em páginas de 20 por padrão, da mais recente para a mais antiga.
Os filtros são opcionais e se somam: quem envia mais de um recebe só as assinaturas que atendem a
todos.
**A listagem não traz os itens.** Cada linha é a assinatura — estado, cliente, datas do ciclo —,
sem `items`. Para saber o que ela cobra, use
[`GET /subscriptions/{id}`](/pt-BR/subscriptions/get).
**`dateFrom` e `dateTo` não fazem nada sozinhos.** Eles filtram o campo escolhido em `dateField`
— `started`, `ended` ou `next_invoice`. Sem `dateField`, o intervalo não tem sobre o que incidir.
É o filtro que responde as perguntas de operação: `next_invoice` entre hoje e amanhã lista o que
vai ser cobrado. Para achar quem está devendo, liste as **faturas** com
[`GET /invoices?status=past_due`](/pt-BR/subscriptions/invoices/list) — o vencimento é dado da
fatura, não da assinatura.
**Para achar por cliente, você precisa do `cust_`.** O filtro `customerId` é correspondência
exata, e não há busca por nome ou e-mail aqui — use
[`GET /customers`](/pt-BR/customers/list) para achar o cliente e filtre por ID.
**Estados terminais continuam na listagem.** Sem filtro, `canceled`, `completed` e
`incomplete_expired` vêm junto com as ativas. Para o que está cobrando hoje, filtre
`?status=active,trialing,past_due`.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/subscriptions \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d status=active,past_due \
-d sortBy=nextInvoiceAt \
-d sortDir=asc \
-d limit=20
```
```json Resposta 200 theme={null}
{
"data": [
{
"id": "sub_x33m4yn6brazh71en4mki6f5c",
"number": { "sequence": 42 },
"referenceCode": "contrato-2026-0042",
"customerId": "cust_eqjzf65crxsrywqdfptanl7yp",
"customerName": "Ana Souza",
"status": "active",
"currency": "BRL",
"currentPeriodEnd": "2026-09-10T12:00:00.000Z",
"nextInvoiceAt": "2026-09-10T12:00:00.000Z",
"cancelAtPeriodEnd": false,
"createdAt": "2026-08-10T12:00:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```
## OpenAPI
````yaml openapi/billing.json GET /subscriptions
openapi: 3.0.3
info:
title: Z2Pay Billing API
version: 1.0.0
description: Cobrança recorrente da Z2Pay — planos, assinaturas e faturas
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Invoices
description: Faturas emitidas pelas assinaturas
- name: Plans
description: Planos de cobrança e versões de preço
- name: Subscriptions
description: Assinaturas recorrentes
paths:
/subscriptions:
get:
tags:
- Subscriptions
summary: Listar assinaturas
description: Lista paginada com filtros opcionais de status/customerId
operationId: SubscriptionController_list
parameters:
- name: page
in: query
required: false
description: 'Página da listagem. Padrão: 1.'
schema:
type: integer
minimum: 1
default: 1
description: 'Página da listagem. Padrão: 1.'
- name: limit
in: query
required: false
description: 'Itens por página. Padrão: 20. Máximo: 100.'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Itens por página. Padrão: 20. Máximo: 100.'
- name: status
in: query
required: false
description: >-
Situação da assinatura. Aceita vários valores, separados por vírgula
ou repetindo o parâmetro. Um valor inválido responde 400 com a lista
dos aceitos.
schema:
type: array
items:
type: string
enum:
- incomplete
- incomplete_expired
- pending_enrollment
- trialing
- active
- past_due
- unpaid
- paused
- canceled
- completed
description: >-
Situação da assinatura. Aceita vários valores, separados por
vírgula ou repetindo o parâmetro. Um valor inválido responde 400
com a lista dos aceitos.
- name: code
in: query
required: false
description: >-
Número da assinatura, como aparece no painel (`2026-0042`).
Correspondência **parcial**: `42` encontra `2026-0042`. Um valor por
requisição.
schema:
type: string
maxLength: 20
description: >-
Número da assinatura, como aparece no painel (`2026-0042`).
Correspondência **parcial**: `42` encontra `2026-0042`. Um valor
por requisição.
- name: paymentMethods
in: query
required: false
description: >-
Forma de pagamento padrão da assinatura. Aceita vários valores,
separados por vírgula ou repetindo o parâmetro.
schema:
type: array
items:
type: string
enum:
- card
- pix
- boleto
- other
description: >-
Forma de pagamento padrão da assinatura. Aceita vários valores,
separados por vírgula ou repetindo o parâmetro.
- name: planIds
in: query
required: false
description: >-
Assinaturas que cobram algum componente destes planos. Aceita vários
ids, separados por vírgula ou repetindo o parâmetro.
schema:
type: array
items:
type: string
maxLength: 36
description: >-
Assinaturas que cobram algum componente destes planos. Aceita
vários ids, separados por vírgula ou repetindo o parâmetro.
- name: dateField
in: query
required: false
description: >-
Qual data o período `dateFrom`/`dateTo` filtra: `started` (início),
`ended` (encerramento) ou `next_invoice` (próxima fatura). Sem ele,
o período não é aplicado.
schema:
type: string
enum:
- started
- ended
- next_invoice
description: >-
Qual data o período `dateFrom`/`dateTo` filtra: `started`
(início), `ended` (encerramento) ou `next_invoice` (próxima
fatura). Sem ele, o período não é aplicado.
- name: dateFrom
in: query
required: false
description: Início do período, em ISO 8601. Exige `dateField`.
schema:
type: string
oneOf:
- type: string
format: date-time
- type: string
description: Início do período, em ISO 8601. Exige `dateField`.
- name: dateTo
in: query
required: false
description: Fim do período, em ISO 8601. Exige `dateField`.
schema:
type: string
oneOf:
- type: string
format: date-time
- type: string
description: Fim do período, em ISO 8601. Exige `dateField`.
- name: customerId
in: query
required: false
description: Assinaturas de um cliente (`cust_`). Correspondência exata.
schema:
type: string
description: Assinaturas de um cliente (`cust_`). Correspondência exata.
- name: referenceCode
in: query
required: false
description: >-
O código que você gravou na criação da assinatura. Correspondência
**exata** — é o caminho para reencontrar pelo seu próprio
identificador.
schema:
type: string
maxLength: 255
description: >-
O código que você gravou na criação da assinatura. Correspondência
**exata** — é o caminho para reencontrar pelo seu próprio
identificador.
- name: sortBy
in: query
required: false
description: >-
Campo de ordenação: `code`, `startedAt` ou `nextInvoiceAt`. Default:
`startedAt`.
schema:
type: string
enum:
- code
- startedAt
- nextInvoiceAt
description: >-
Campo de ordenação: `code`, `startedAt` ou `nextInvoiceAt`.
Default: `startedAt`.
- name: sortDir
in: query
required: false
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
schema:
type: string
enum:
- asc
- desc
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
responses:
'200':
description: Lista paginada
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
number:
type: object
properties:
sequence:
type: integer
description: >-
Número sequencial do documento dentro da
numeração (assinatura ou fatura).
description: Número do endereço.
referenceCode:
type: string
description: >-
Código do contrato no sistema do integrador;
pesquisável, sem unicidade.
nullable: true
customerId:
type: string
description: ID do cliente associado ao registro.
customerEmail:
type: string
description: E-mail do cliente.
customerName:
type: string
description: Nome do cliente.
customerDocument:
type: string
description: Documento do cliente (CPF ou CNPJ).
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
status:
type: string
enum:
- incomplete
- incomplete_expired
- trialing
- active
- past_due
- unpaid
- paused
- canceled
- completed
description: >-
Status atual do registro (assinatura, fatura, plano
ou slip de pagamento).
billingGroupId:
nullable: true
description: >-
ID do grupo de cobrança ao qual o registro pertence;
nulo se não agrupado.
currentPeriodStart:
type: string
format: date-time
description: >-
Início do período de cobrança atual da assinatura
(ISO 8601).
currentPeriodEnd:
type: string
format: date-time
description: >-
Fim do período de cobrança atual da assinatura (ISO
8601).
nextInvoiceAt:
type: string
format: date-time
description: >-
Data e hora prevista para a próxima fatura da
assinatura (ISO 8601).
nullable: true
recurrence:
type: object
properties:
interval:
type: integer
description: >-
Quantidade de unidades por ciclo de cobrança
(ex.: interval 3 + unit month = trimestral).
unit:
type: string
description: >-
Unidade do ciclo de cobrança: day, week, month
ou year.
anchor:
type: string
description: >-
Âncora que fixa a data de renovação do ciclo:
subscription_start, day_of_month ou
end_of_month.
anchorDay:
type: integer
description: >-
Dia do mês (1–31) usado quando a âncora é
day_of_month.
collectionTiming:
type: string
description: >-
Momento da cobrança do ciclo: prepaid (no
início) ou postpaid (no fim).
description: >-
Regra de recorrência (intervalo, unidade e âncora do
ciclo).
collectionMethod:
type: string
enum:
- charge_automatically
description: >-
Como a fatura é cobrada. Hoje só a cobrança
automática na forma de pagamento padrão.
collectionTiming:
type: string
enum:
- prepaid
- postpaid
description: >-
Momento da cobrança do ciclo: prepaid (no início) ou
postpaid (no fim).
invoiceGenerationMode:
type: string
enum:
- just_in_time
- upfront
description: >-
Modo de geração de faturas: just_in_time (a cada
ciclo) ou upfront (todas antecipadas).
cancelAtPeriodEnd:
type: boolean
description: >-
Indica se a assinatura será cancelada ao fim do
período atual.
canceledAt:
nullable: true
description: >-
Data e hora do cancelamento; nula se não cancelado
(ISO 8601).
endedAt:
nullable: true
description: >-
Data e hora em que a assinatura foi efetivamente
encerrada; nula se ainda ativa (ISO 8601).
cancellationReason:
nullable: true
description: Motivo do cancelamento da assinatura.
pausedAt:
nullable: true
description: >-
Data e hora em que a assinatura foi pausada; nula se
não pausada (ISO 8601).
pauseResumesAt:
nullable: true
description: >-
Data e hora agendada para a retomada automática da
assinatura pausada (ISO 8601).
pauseReason:
nullable: true
description: Motivo da pausa da assinatura.
trialEnd:
nullable: true
description: >-
Data e hora de término do período de teste; nula se
sem trial (ISO 8601).
incompleteExpiresAt:
nullable: true
description: >-
Prazo para concluir o primeiro pagamento antes de a
assinatura incompleta expirar (ISO 8601).
trialRemindersFired:
type: array
items: {}
description: >-
Lembretes de fim do período de teste já disparados
para a assinatura.
maxCycles:
nullable: true
description: >-
Número máximo de ciclos da assinatura; nulo se não
houver limite.
issuedCycles:
type: integer
description: >-
Número de ciclos já faturados (faturas emitidas) da
assinatura.
completedCycles:
type: integer
description: >-
Número de ciclos já concluídos (pagos) da
assinatura.
defaultPaymentMethodRef:
type: object
properties:
id:
type: string
description: Identificador único do registro.
nullable: true
type:
type: string
description: >-
Tipo da referência: meio da forma de pagamento
(card, pix, boleto) ou natureza da linha da
fatura.
description: >-
Referência da forma de pagamento padrão usada para
cobrar a assinatura.
splitConfig:
nullable: true
description: >-
Configuração de divisão (split) dos valores entre
recebedores; nula se sem split.
paymentBehavior:
type: string
enum:
- allow_incomplete
- error_if_incomplete
description: >-
O que fazer quando a primeira cobrança não é
aprovada: allow_incomplete cria a assinatura com a
fatura em aberto; error_if_incomplete cancela a
assinatura.
latestInvoiceId:
type: string
description: ID da fatura mais recente gerada pela assinatura.
paymentUpdateToken:
nullable: true
description: >-
Token do link público para o cliente atualizar a
forma de pagamento; nulo se não gerado.
paymentUpdateMethods:
nullable: true
description: >-
Formas de pagamento permitidas no link público de
troca; nula se não habilitada.
metadata:
type: object
properties: {}
description: >-
Metadados livres (pares chave-valor) para uso do
integrador; não afeta o processamento.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro (ISO
8601).
description: Lista de registros retornados na página atual.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
description: Dados de paginação do resultado.
example:
data:
- id: sub_hsm2kigu74htdxj3nw2z6f9xw
number:
sequence: 42
referenceCode: CONTRATO-2026-0042
customerId: cust_c72q6ogr9iko0we85mqal04te
customerEmail: maria.silva@example.com
customerName: Maria Silva
customerDocument: '12345678909'
currency: BRL
status: active
billingGroupId: null
currentPeriodStart: '2025-06-01T03:00:00.000Z'
currentPeriodEnd: '2025-07-01T03:00:00.000Z'
nextInvoiceAt: '2025-07-01T03:00:00.000Z'
recurrence:
interval: 1
unit: month
anchor: day_of_month
anchorDay: 1
collectionTiming: prepaid
collectionMethod: charge_automatically
collectionTiming: prepaid
invoiceGenerationMode: just_in_time
cancelAtPeriodEnd: false
canceledAt: null
endedAt: null
cancellationReason: null
pausedAt: null
pauseResumesAt: null
pauseReason: null
trialEnd: null
incompleteExpiresAt: null
trialRemindersFired: []
maxCycles: null
issuedCycles: 1
completedCycles: 1
defaultPaymentMethodRef:
id: crd_tsj66oabsygc9kwvvzt8189f9
type: card
splitConfig: null
paymentBehavior: allow_incomplete
latestInvoiceId: inv_c3qahi4qnkc258lfc14gplupt
paymentUpdateToken: null
paymentUpdateMethods: null
metadata: {}
createdAt: '2025-06-01T13:45:30.000Z'
updatedAt: '2025-06-01T13:45:30.000Z'
pagination:
page: 1
limit: 20
total: 1
totalPages: 1
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````