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));import requests
url = "https://api.sandbox.z2pay.com/v1/plans"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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"
}
}Listar planos
Lista paginada dos planos da conta, com filtros por status, código, nome, item e faixa de preço.
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));import requests
url = "https://api.sandbox.z2pay.com/v1/plans"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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.
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.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
{
"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
API Key da Credential (gerada no Backoffice)
Query Parameters
Página da listagem. Padrão: 1.
x >= 1Itens por página. Padrão: 20. Máximo: 100.
1 <= x <= 100Situaçã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.
draft, active, inactive, archived Código do plano. Correspondência parcial: pro encontra plano-pro-anual. Um valor por requisição.
100Nome do plano. Correspondência parcial, sem diferenciar maiúsculas. Um valor por requisição.
255Planos que tenham algum componente cujo nome case parcialmente com o texto. Filtra o plano, não o componente: a resposta traz o plano inteiro.
255Planos com algum componente cujo preço vigente seja maior ou igual a este valor, em centavos.
x >= 0Planos 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.
x >= 0Planos criados a partir desta data, em ISO 8601 com fuso. Inclusivo.
Planos criados até esta data, em ISO 8601 com fuso. Inclusivo.
Campo de ordenação: createdAt ou name. Default: createdAt.
createdAt, name Direção da ordenação: asc ou desc. Default: desc.
asc, desc