Listar versões de preço

Listar todas as versões de preço de um plano

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/plans/{id}/prices \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

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));

[
  {
    "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"
  }
]

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET

plans

{id}

prices

Listar todas as versões de preço de um plano

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/plans/{id}/prices \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

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));

[
  {
    "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"
  }
]

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET /plans/:id/prices Faz parte do recurso Planos e Preços — 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}. 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

curl https://api.sandbox.z2pay.com/v1/plans/plan_lhutpqeq2ml3stia4vn90xars/prices \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Resposta 200

[
  {
    "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.

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Path Parameters

string

required

ID do plano

Response

Lista de versões de preço (não paginada)

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).

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Exemplo

Authorizations

Path Parameters

Response

​Exemplo

Authorizations

Path Parameters

Response

Exemplo