> ## 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 planos
> Lista paginada dos planos da conta, com filtros por status, código, nome, item e faixa de preço.
`GET /plans`
Faz parte do recurso [Planos e Preços](/pt-BR/subscriptions/plans) — o conceito e os status estão
lá.
Devolve os planos da sua conta, do mais recente para o mais antigo, em páginas de 20 por padrão. Os
filtros são opcionais e se somam: quem envia mais de um recebe só os planos que atendem a todos.
**A listagem não traz os itens.** Cada linha é o plano — código, nome, status, cadência —, sem
`items` e sem preço. Para saber o que o plano cobra, use
[`GET /plans/{id}`](/pt-BR/subscriptions/plans/get), que devolve os itens com o preço em vigor de
cada um.
**Arquivados continuam na listagem.** Sem filtro, a resposta traz `active`, `inactive` e
`archived` juntos — arquivar encerra as vendas, não remove o registro. Para ver só o que aceita
novas assinaturas, use `?status=active`.
**`priceMin` e `priceMax` olham os itens, mas filtram o plano.** Um plano entra no resultado se
**algum** item seu tem preço vigente dentro do limite, e a resposta traz o plano inteiro. Com os
dois limites juntos, é **um mesmo item** que precisa caber na faixa — um plano com um item abaixo
de `priceMin` e outro acima de `priceMax`, mas nenhum entre os dois, fica de fora.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/plans \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d status=active \
-d name=pro \
-d page=1 \
-d limit=20
```
```json Resposta 200 theme={null}
{
"data": [
{
"id": "plan_lhutpqeq2ml3stia4vn90xars",
"code": "pro-monthly",
"name": "Plano Pro",
"description": "Todos os recursos, cobrado mensalmente",
"status": "active",
"recurrence": {
"interval": 1,
"unit": "month",
"anchor": "subscription_start",
"collectionTiming": "prepaid"
},
"trialSpec": null,
"metadata": {},
"createdAt": "2026-08-10T13:45:30.000Z",
"updatedAt": "2026-08-10T13:45:30.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```
## OpenAPI
````yaml openapi/billing.json GET /plans
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:
/plans:
get:
tags:
- Plans
summary: Listar planos
description: >-
Retorna a lista paginada de planos da sua conta. Os filtros são
opcionais e se somam: quem envia mais de um recebe só os planos que
atendem a todos.
operationId: PlanController_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 do plano. 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:
- draft
- active
- inactive
- archived
description: >-
Situação do plano. 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: >-
Código do plano. Correspondência **parcial**: `pro` encontra
`plano-pro-anual`. Um valor por requisição.
schema:
type: string
maxLength: 100
description: >-
Código do plano. Correspondência **parcial**: `pro` encontra
`plano-pro-anual`. Um valor por requisição.
- name: name
in: query
required: false
description: >-
Nome do plano. Correspondência **parcial**, sem diferenciar
maiúsculas. Um valor por requisição.
schema:
type: string
maxLength: 255
description: >-
Nome do plano. Correspondência **parcial**, sem diferenciar
maiúsculas. Um valor por requisição.
- name: item
in: query
required: false
description: >-
Planos que tenham algum componente cujo nome case **parcialmente**
com o texto. Filtra o plano, não o componente: a resposta traz o
plano inteiro.
schema:
type: string
maxLength: 255
description: >-
Planos que tenham algum componente cujo nome case **parcialmente**
com o texto. Filtra o plano, não o componente: a resposta traz o
plano inteiro.
- name: priceMin
in: query
required: false
description: >-
Planos com **algum** componente cujo preço vigente seja maior ou
igual a este valor, em centavos.
schema:
type: integer
minimum: 0
description: >-
Planos com **algum** componente cujo preço vigente seja maior ou
igual a este valor, em centavos.
- name: priceMax
in: query
required: false
description: >-
Planos com **algum** componente cujo preço vigente seja menor ou
igual a este valor, em centavos. Combinado com `priceMin`, é um
**mesmo** componente que precisa caber na faixa — um plano sem
nenhum componente entre os dois limites fica de fora.
schema:
type: integer
minimum: 0
description: >-
Planos com **algum** componente cujo preço vigente seja menor ou
igual a este valor, em centavos. Combinado com `priceMin`, é um
**mesmo** componente que precisa caber na faixa — um plano sem
nenhum componente entre os dois limites fica de fora.
- name: createdFrom
in: query
required: false
description: Planos criados a partir desta data, em ISO 8601 com fuso. Inclusivo.
schema:
type: string
format: date-time
description: >-
Planos criados a partir desta data, em ISO 8601 com fuso.
Inclusivo.
- name: createdTo
in: query
required: false
description: Planos criados até esta data, em ISO 8601 com fuso. Inclusivo.
schema:
type: string
format: date-time
description: Planos criados até esta data, em ISO 8601 com fuso. Inclusivo.
- name: sortBy
in: query
required: false
description: 'Campo de ordenação: `createdAt` ou `name`. Default: `createdAt`.'
schema:
type: string
enum:
- createdAt
- name
description: 'Campo de ordenação: `createdAt` ou `name`. Default: `createdAt`.'
- 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 de planos
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
code:
type: string
description: >-
Código de identificação do recurso (ex.: código do
plano ou do contrato).
name:
type: string
description: Nome de exibição do plano ou do componente.
description:
type: string
nullable: true
description: >-
Descrição do item (item do plano ou linha da
fatura).
status:
type: string
description: >-
Status atual do registro (assinatura, fatura, plano
ou slip de pagamento).
recurrence:
type: object
nullable: true
description: >-
Cadência da cobrança: a cada quantas unidades
(`interval`), qual unidade (`unit`), a âncora do
ciclo e se cobra no início ou no fim. Vale para
todos os itens recorrentes.
trialSpec:
type: object
nullable: true
description: >-
Período de teste padrão da oferta. A assinatura pode
sobrescrevê-lo.
metadata:
type: object
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: plan_lhutpqeq2ml3stia4vn90xars
code: pro-monthly
name: Pro Plan
description: Pro tier with all features
status: active
recurrence:
interval: 1
unit: month
anchor: subscription_start
collectionTiming: prepaid
trialSpec: null
metadata: {}
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
pagination:
page: 1
limit: 20
total: 1
totalPages: 1
'400':
description: Filtro ou paginação inválidos
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)
````