Skip to main content
POST
Criar nova versão de preço
POST /plans/:id/prices Faz parte do recurso Planos e Preços — 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 — 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 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

Resposta 201

Authorizations

x-api-key
string
header
required

API Key da Credential (gerada no Backoffice)

Headers

Idempotency-Key
string

Chave única para garantir idempotência da requisição

Path Parameters

id
string
required

ID do plano

Body

application/json
amount
integer
required

Valor da cobrança, em centavos (menor unidade da moeda).

Required range: x >= 0
planItemId
string

Item do plano que este preço versiona. Informe este OU planItemKey.

Required string length: 1 - 36
planItemKey
string

Alternativa ao planItemId: a key do item dentro do plano.

Required string length: 1 - 100
Pattern: ^[a-z0-9-_]+$
billingScheme
enum<string>
default:fixed

Forma de cobrança. Hoje só fixed (valor fixo por ciclo).

Available options:
fixed
currency
enum<string>
default:BRL

Código de moeda ISO 4217. Hoje o único valor aceito é 'BRL'.

Available options:
BRL

Response

Price criado e marcado como current

id
string

Identificador único do registro.

planItemId
string

ID do componente (plan item) ao qual o preço se refere.

planId
string

ID do plano ao qual o registro pertence.

billingScheme
string

Esquema de cobrança do preço: fixed, per_unit, tiered, package ou metered.

amount
integer

Valor do preço ou da linha, em centavos.

currency
string

Moeda no padrão ISO 4217 (ex.: BRL).

recurrence
object

Regra de recorrência (intervalo, unidade e âncora do ciclo).

trialSpec
object | null

Configuração do período de teste (trial) do preço; nula se sem trial.

isCurrent
boolean

Indica se esta é a versão de preço atualmente vigente.

publishedAt
string<date-time> | null

Data e hora em que a versão de preço foi publicada (ISO 8601).

archivedAt
string<date-time> | null

Data e hora em que a versão de preço foi arquivada; nula se ainda vigente (ISO 8601).

createdAt
string<date-time>

Data e hora de criação do registro (ISO 8601).

updatedAt
string<date-time>

Data e hora da última atualização do registro (ISO 8601).