curl --request POST \
--url https://api.sandbox.z2pay.com/v1/plans/{id}/prices \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": 1,
"planItemId": "<string>",
"planItemKey": "<string>",
"billingScheme": "fixed",
"currency": "BRL"
}
'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 1,
planItemId: '<string>',
planItemKey: '<string>',
billingScheme: 'fixed',
currency: 'BRL'
})
};
fetch('https://api.sandbox.z2pay.com/v1/plans/{id}/prices', 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/{id}/prices"
payload = {
"amount": 1,
"planItemId": "<string>",
"planItemKey": "<string>",
"billingScheme": "fixed",
"currency": "BRL"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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"
}{
"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"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Price not found"
}
}{
"error": "A request with this idempotency key is already being processed"
}{
"error": "Idempotency key already used with a different request body"
}Criar versão de preço
Publica um valor novo para um item do plano. Quem já assinou continua no preço que contratou.
curl --request POST \
--url https://api.sandbox.z2pay.com/v1/plans/{id}/prices \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": 1,
"planItemId": "<string>",
"planItemKey": "<string>",
"billingScheme": "fixed",
"currency": "BRL"
}
'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 1,
planItemId: '<string>',
planItemKey: '<string>',
billingScheme: 'fixed',
currency: 'BRL'
})
};
fetch('https://api.sandbox.z2pay.com/v1/plans/{id}/prices', 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/{id}/prices"
payload = {
"amount": 1,
"planItemId": "<string>",
"planItemKey": "<string>",
"billingScheme": "fixed",
"currency": "BRL"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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"
}{
"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"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Price not found"
}
}{
"error": "A request with this idempotency key is already being processed"
}{
"error": "Idempotency key already used with a different request body"
}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.
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.409.Exemplo
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"
}'
{
"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"
}
Authorizations
API Key da Credential (gerada no Backoffice)
Headers
Chave única para garantir idempotência da requisição
Path Parameters
ID do plano
Body
Valor da cobrança, em centavos (menor unidade da moeda).
x >= 0Item do plano que este preço versiona. Informe este OU planItemKey.
1 - 36Alternativa ao planItemId: a key do item dentro do plano.
1 - 100^[a-z0-9-_]+$Forma de cobrança. Hoje só fixed (valor fixo por ciclo).
fixed Código de moeda ISO 4217. Hoje o único valor aceito é 'BRL'.
BRL Response
Price criado e marcado como current
Identificador único do registro.
ID do componente (plan item) ao qual o preço se refere.
ID do plano ao qual o registro pertence.
Esquema de cobrança do preço: fixed, per_unit, tiered, package ou metered.
Valor do preço ou da linha, em centavos.
Moeda no padrão ISO 4217 (ex.: BRL).
Regra de recorrência (intervalo, unidade e âncora do ciclo).
Configuração do período de teste (trial) do preço; nula se sem trial.
Indica se esta é a versão de preço atualmente vigente.
Data e hora em que a versão de preço foi publicada (ISO 8601).
Data e hora em que a versão de preço foi arquivada; nula se ainda vigente (ISO 8601).
Data e hora de criação do registro (ISO 8601).
Data e hora da última atualização do registro (ISO 8601).