Listar planos

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/plans \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/plans', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
  }
}

{
  "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)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET

plans

Listar planos

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/plans \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/plans', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
  }
}

{
  "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)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET /plans Faz parte do recurso Planos e Preços — 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}, 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

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

Resposta 200

{
  "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 }
}

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Query Parameters

page

integer

default:1

Página da listagem. Padrão: 1.

Required range: x >= 1

limit

integer

default:20

Itens por página. Padrão: 20. Máximo: 100.

Required range: 1 <= x <= 100

status

enum<string>[]

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.

Available options:

draft,

active,

inactive,

archived

code

string

Código do plano. Correspondência parcial: pro encontra plano-pro-anual. Um valor por requisição.

Maximum string length: 100

name

string

Nome do plano. Correspondência parcial, sem diferenciar maiúsculas. Um valor por requisição.

Maximum string length: 255

item

string

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.

Maximum string length: 255

priceMin

integer

Planos com algum componente cujo preço vigente seja maior ou igual a este valor, em centavos.

Required range: x >= 0

priceMax

integer

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.

Required range: x >= 0

createdFrom

string<date-time>

Planos criados a partir desta data, em ISO 8601 com fuso. Inclusivo.

createdTo

string<date-time>

Planos criados até esta data, em ISO 8601 com fuso. Inclusivo.

sortBy

enum<string>

Campo de ordenação: createdAt ou name. Default: createdAt.

Available options:

createdAt,

name

sortDir

enum<string>

Direção da ordenação: asc ou desc. Default: desc.

Available options:

asc,

desc

Response

Lista paginada de planos

data

object[]

Lista de registros retornados na página atual.

Show child attributes

pagination

object

Dados de paginação do resultado.

Show child attributes

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Listar planos

Exemplo

Authorizations

Query Parameters

Response

​Exemplo

Authorizations

Query Parameters

Response

Exemplo