> ## 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.
# Criar versão de preço
> Publica um valor novo para um item do plano. Quem já assinou continua no preço que contratou.
`POST /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á.
É assim que se reajusta: a versão nova entra como vigente e a anterior, de mesma moeda e cadência,
deixa de ser — sem apagar nada. A resposta é a versão criada.
**O reajuste não alcança quem já assinou.** Cada assinatura guarda a versão de preço que
contratou, e continua sendo faturada por ela para sempre. A versão nova vale para as assinaturas
criadas a partir daqui. Não existe rota que migre uma assinatura de versão.
**Escolha o item por `planItemId` ou por `planItemKey`** — um dos dois, não os dois. Sem nenhum, o
preço vai para o item de `key` `default`, que é o comportamento dos planos de item único.
Referência que não casa com nenhum item do plano responde `404`.
**Não se envia cadência nem período de teste.** Os dois vêm do plano, como no
[item novo](/pt-BR/subscriptions/plans/items) — o preço os herda no momento em que nasce.
**A versão anterior continua existindo.** Ela deixa de ser corrente, mas segue na
[listagem de versões](/pt-BR/subscriptions/plans/prices) e continua valendo para as assinaturas
que a contrataram. É o histórico do que cada cliente paga.
**Plano arquivado não recebe preço novo.** A rota responde `409`.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/plans/plan_lhutpqeq2ml3stia4vn90xars/prices \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-d '{
"planItemKey": "default",
"amount": 11900,
"currency": "BRL"
}'
```
```json Resposta 201 theme={null}
{
"id": "price_c8u3fwq1bnz5vhk60msyxrtae",
"planItemId": "pli_oaimno59ai3uuqwq0ti7gxs0j",
"planId": "plan_lhutpqeq2ml3stia4vn90xars",
"billingScheme": "fixed",
"amount": 11900,
"currency": "BRL",
"recurrence": {
"interval": 1,
"unit": "month",
"anchor": "subscription_start",
"collectionTiming": "prepaid"
},
"trialSpec": null,
"isCurrent": true,
"publishedAt": "2026-08-10T16:04:20.000Z",
"archivedAt": null,
"createdAt": "2026-08-10T16:04:20.000Z",
"updatedAt": "2026-08-10T16:04:20.000Z"
}
```
## OpenAPI
````yaml openapi/billing.json POST /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:
post:
tags:
- Plans
summary: Criar nova versão de preço
description: >-
Cria uma nova versão de Price sob o plano. Marca automaticamente o Price
anterior de mesma (moeda, recorrência) como não-current
operationId: PlanController_createPriceVersion
parameters:
- name: id
in: path
required: true
description: ID do plano
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
planItemId:
type: string
minLength: 1
maxLength: 36
description: >-
Item do plano que este preço versiona. Informe este OU
`planItemKey`.
planItemKey:
type: string
minLength: 1
maxLength: 100
pattern: ^[a-z0-9-_]+$
description: >-
Alternativa ao `planItemId`: a `key` do item dentro do
plano.
billingScheme:
type: string
enum:
- fixed
default: fixed
description: Forma de cobrança. Hoje só `fixed` (valor fixo por ciclo).
amount:
type: integer
minimum: 0
description: Valor da cobrança, em centavos (menor unidade da moeda).
currency:
type: string
enum:
- BRL
description: Código de moeda ISO 4217. Hoje o único valor aceito é 'BRL'.
default: BRL
required:
- amount
responses:
'201':
description: Price criado e marcado como current
content:
application/json:
schema:
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_pl6wvkht5oj7juq19v9qf5uwy
planItemId: pli_oaimno59ai3uuqwq0ti7gxs0j
planId: plan_lhutpqeq2ml3stia4vn90xars
billingScheme: fixed
amount: 11900
currency: BRL
recurrence:
interval: 1
unit: month
anchor: subscription_start
collectionTiming: prepaid
trialSpec:
durationDays: 7
requiresPaymentMethod: true
isCurrent: true
publishedAt: '2025-06-29T16:00:00.000Z'
archivedAt: null
createdAt: '2025-06-29T16:00:00.000Z'
updatedAt: '2025-06-29T16:00:00.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: Price not found
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````