> ## 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.
# Buscar plano por ID
> Retorna o plano com seus itens, cada um acompanhado do preço em vigor.
`GET /plans/:id`
Faz parte do recurso [Planos e Preços](/pt-BR/subscriptions/plans) — o conceito e os status estão
lá.
Devolve a oferta completa: o plano, seus itens e, em cada item, o preço em vigor (`currentPrice`).
É a leitura para montar uma tela de contratação — a [listagem](/pt-BR/subscriptions/plans/list)
devolve só o plano, sem os itens.
**`currency` escolhe o preço, não filtra os itens.** Com ela, cada item traz o preço vigente
naquela moeda; um item que não tenha preço nessa moeda aparece do mesmo jeito, com `currentPrice`
nulo. Sem ela, cada item traz o primeiro preço encontrado.
**Itens arquivados não aparecem.** Arquivar um item o retira das próximas assinaturas e da
resposta desta rota. Isso não afeta as assinaturas em curso, que já o instanciaram e continuam
cobrando por ele — o item some do catálogo, não da cobrança.
**A cadência e o teste vêm duas vezes, e é de propósito.** Na raiz estão os do plano; dentro de
cada `currentPrice`, os que aquele preço herdou quando foi criado. Divergem quando o plano mudou
depois — o que vale para uma assinatura é sempre o do preço que ela contratou.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/plans/plan_lhutpqeq2ml3stia4vn90xars \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d currency=BRL
```
```json Resposta 200 theme={null}
{
"id": "plan_lhutpqeq2ml3stia4vn90xars",
"code": "pro-monthly",
"name": "Plano Pro",
"status": "active",
"recurrence": {
"interval": 1,
"unit": "month",
"anchor": "subscription_start",
"collectionTiming": "prepaid"
},
"trialSpec": null,
"items": [
{
"id": "pli_oaimno59ai3uuqwq0ti7gxs0j",
"key": "default",
"name": "Assinatura Pro",
"kind": "recurring",
"quantityDefault": 1,
"displayOrder": 0,
"currentPrice": {
"id": "price_l1r8693wk6ksbd9044bwvwu93",
"amount": 9900,
"currency": "BRL",
"billingScheme": "fixed",
"isCurrent": true
}
}
],
"createdAt": "2026-08-10T13:45:30.000Z",
"updatedAt": "2026-08-10T13:45:30.000Z"
}
```
O exemplo está abreviado — o playground ao lado mostra o corpo inteiro.
## OpenAPI
````yaml openapi/billing.json GET /plans/{id}
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/{id}:
get:
tags:
- Plans
summary: Buscar plano por ID
description: >-
Retorna o plano com seus itens, cada um acompanhado do preço em vigor
(`currentPrice`). `currency` restringe os preços a uma moeda; sem ela,
cada item traz o primeiro preço encontrado.
operationId: PlanController_getById
parameters:
- name: currency
in: query
required: false
description: >-
Moeda (ISO 4217) do preço devolvido em `currentPrice`. Não filtra a
lista de itens: componente sem preço nesta moeda vem com
`currentPrice` nulo. Omitida, cada item traz o primeiro preço
encontrado.
schema:
type: string
- name: id
in: path
required: true
description: ID do plano
schema:
type: string
responses:
'200':
description: Plano com itens e preços em vigor
content:
application/json:
schema:
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).
items:
type: array
description: Itens do plano, cada um com o preço em vigor.
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
planId:
type: string
description: ID do plano ao qual o registro pertence.
key:
type: string
description: >-
Chave única e legível (slug) do componente dentro do
plano.
name:
type: string
description: Nome de exibição do plano ou do componente.
kind:
type: string
enum:
- recurring
- activation
description: >-
Natureza da cobrança: `recurring` cobra a cada
ciclo; `activation` cobra uma única vez, na fatura
de adesão.
quantityDefault:
type: integer
description: >-
Quantidade padrão do componente ao instanciar a
assinatura.
displayOrder:
type: integer
description: >-
Ordem de exibição do componente na listagem do
plano.
description:
type: string
nullable: true
description: >-
Descrição do item (item do plano ou linha da
fatura).
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).
currentPrice:
type: object
nullable: true
properties:
id:
type: string
description: Identificador único do registro.
planItemId:
type: string
description: >-
ID do componente (plan item) ao qual o preço se
refere.
planId:
type: string
description: ID do plano ao qual o registro pertence.
billingScheme:
type: string
description: >-
Esquema de cobrança do preço: fixed, per_unit,
tiered, package ou metered.
amount:
type: integer
description: Valor do preço ou da linha, em centavos.
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
recurrence:
type: object
description: >-
Regra de recorrência (intervalo, unidade e
âncora do ciclo).
trialSpec:
type: object
nullable: true
description: >-
Configuração do período de teste (trial) do
preço; nula se sem trial.
isCurrent:
type: boolean
description: >-
Indica se esta é a versão de preço atualmente
vigente.
publishedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a versão de preço foi
publicada (ISO 8601).
archivedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a versão de preço foi
arquivada; nula se ainda vigente (ISO 8601).
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: Versão de preço vigente do item do plano.
example:
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'
items:
- id: pli_oaimno59ai3uuqwq0ti7gxs0j
planId: plan_lhutpqeq2ml3stia4vn90xars
key: default
name: Pro Subscription
kind: recurring
quantityDefault: 1
displayOrder: 0
description: null
metadata: {}
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
currentPrice:
id: price_l1r8693wk6ksbd9044bwvwu93
planItemId: pli_oaimno59ai3uuqwq0ti7gxs0j
planId: plan_lhutpqeq2ml3stia4vn90xars
billingScheme: fixed
amount: 9900
currency: BRL
recurrence:
interval: 1
unit: month
anchor: subscription_start
collectionTiming: prepaid
trialSpec: null
isCurrent: true
publishedAt: '2025-06-29T13:45:30.000Z'
archivedAt: null
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
'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
'404':
description: Plano não encontrado
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: NOT_FOUND
message: Plan not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````