> ## 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 versões de preço
> Todas as versões de preço do plano, vigentes e antigas, para auditar o histórico de reajustes.
`GET /plans/:id/prices`
Faz parte do recurso [Planos e Preços](/pt-BR/subscriptions/plans) — o item, o preço versionado e
os status estão lá.
Devolve **todas** as versões de preço do plano, de todos os itens — as vigentes, as que foram
substituídas por um reajuste e as arquivadas. É a leitura de auditoria: o histórico de quanto o
plano já custou e desde quando.
**Para saber o preço em vigor, use [`GET /plans/{id}`](/pt-BR/subscriptions/plans/get).** Ele traz
cada item já com o seu `currentPrice` resolvido. Esta rota é o contrário: entrega tudo e deixa a
seleção com você.
**Dois campos distinguem as versões:** `isCurrent` diz qual está valendo para novas assinaturas, e
`archivedAt` marca a que foi tirada de circulação. Uma versão substituída por reajuste tem
`isCurrent: false` e `archivedAt: null` — não foi arquivada, apenas deixou de ser a mais recente,
e continua sendo cobrada de quem a contratou.
**A resposta não é paginada.** Vem o array inteiro, sem `page` nem `limit`. O volume é o número de
reajustes que o plano já teve.
## Exemplo
```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/plans/plan_lhutpqeq2ml3stia4vn90xars/prices \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
[
{
"id": "price_c8u3fwq1bnz5vhk60msyxrtae",
"planItemId": "pli_oaimno59ai3uuqwq0ti7gxs0j",
"planId": "plan_lhutpqeq2ml3stia4vn90xars",
"billingScheme": "fixed",
"amount": 11900,
"currency": "BRL",
"isCurrent": true,
"publishedAt": "2026-08-10T16:04:20.000Z",
"archivedAt": null
},
{
"id": "price_l1r8693wk6ksbd9044bwvwu93",
"planItemId": "pli_oaimno59ai3uuqwq0ti7gxs0j",
"planId": "plan_lhutpqeq2ml3stia4vn90xars",
"billingScheme": "fixed",
"amount": 9900,
"currency": "BRL",
"isCurrent": false,
"publishedAt": "2026-08-10T13:45:30.000Z",
"archivedAt": null
}
]
```
O exemplo está abreviado. As duas versões acima são do mesmo item: a de `9900` foi substituída
pelo reajuste para `11900`, e continua sendo cobrada de quem assinou antes.
## OpenAPI
````yaml openapi/billing.json GET /plans/{id}/prices
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}/prices:
get:
tags:
- Plans
summary: Listar todas as versões de preço de um plano
operationId: PlanController_listPrices
parameters:
- name: id
in: path
required: true
description: ID do plano
schema:
type: string
responses:
'200':
description: Lista de versões de preço (não paginada)
content:
application/json:
schema:
type: array
items:
type: object
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).
example:
- 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'
'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)
````