Preços de Oferta

Um preço de oferta anexa um valor concreto, em uma moeda específica, a uma oferta. Uma oferta pode carregar vários preços — um por moeda — para que o mesmo plano possa ser vendido em BRL, USD, EUR e mais. Exatamente um preço por oferta pode ser marcado como o padrão dessa oferta.

Os preços são a folha do catálogo. A oferta define como um plano é cobrado (ciclo, teste, configuração); o preço define quanto ele custa em cada moeda.

Como funciona a precificação

• Os valores são unidades menores inteiras. Armazene centavos, não decimais. R$99.00 é 9900; US$150.00 é 15000. Sempre combine um amount com uma currency ISO 4217.
• Um preço por moeda, por oferta. Uma oferta não pode ter dois preços ativos na mesma moeda. Criar ou atualizar um preço para uma moeda que já está ocupada retorna 409 Conflict.
• Um padrão por oferta. No máximo um preço em uma oferta pode ter is_default: true. O padrão é o preço que o Tokeflow exibe primeiro (e lista primeiro) para essa oferta.
• first_charge_amount conduz cobranças de configuração. Quando a oferta pai tem setup_charge = true, o primeiro ciclo é cobrado com first_charge_amount em vez de amount. Um valor de 0 significa uma primeira cobrança apenas de validação de cartão. Deixe-o como null para cobrar o amount padrão no primeiro ciclo. Uma oferta com free_trial = true cobra 0 no primeiro ciclo independentemente deste campo, a menos que um first_charge_amount acima de 0 seja configurado como taxa de adesão inicial.

O objeto de preço de oferta

{
  "id": "opr_b1c2d3e4f5",
  "offer_id": "ofr_a1b2c3d4e5",
  "currency": "BRL",
  "amount": 9900,
  "first_charge_amount": 0,
  "is_default": true,
  "created_at": "2026-05-19T12:00:00.000Z",
  "updated_at": "2026-05-19T12:00:00.000Z"
}

Endpoints

Todos os endpoints de preço de oferta ficam sob https://api.tokeflow.com/api/v1. A autenticação usa uma chave secreta — veja Autenticação.

POST/api/v1/offers/:offerId/prices

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Adiciona um preço a uma oferta existente. A oferta pai deve pertencer ao merchant autenticado.

Parâmetros de caminho

Parâmetros de corpo

curl -X POST https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5/prices \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c3b9f1e-2a4d-4c8e-9f1a-6b2d8e0c4a11" \
  -d '{
    "currency": "BRL",
    "amount": 9900,
    "first_charge_amount": 0,
    "is_default": true
  }'

Resposta 201 Created

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 9900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z"
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

GET/api/v1/offers/:offerId/prices

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Lista os preços de uma oferta, o padrão primeiro e depois por moeda. Suporta filtragem e paginação.

Parâmetros de caminho

Parâmetros de consulta

curl "https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5/prices?page=1&limit=20&currency=BRL&is_default=true" \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME"

Resposta 200 OK

{
  "success": true,
  "data": [
    {
      "id": "opr_b1c2d3e4f5",
      "offer_id": "ofr_a1b2c3d4e5",
      "currency": "BRL",
      "amount": 9900,
      "first_charge_amount": 0,
      "is_default": true,
      "created_at": "2026-05-19T12:00:00.000Z",
      "updated_at": "2026-05-19T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_3a1d7f9c2b",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

GET/api/v1/offer-prices/:id

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Recupera um único preço pelo seu ID opr_. O preço deve pertencer a uma oferta de propriedade do merchant autenticado.

Parâmetros de caminho

curl https://api.tokeflow.com/api/v1/offer-prices/opr_b1c2d3e4f5 \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME"

Resposta 200 OK

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 9900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z"
  },
  "request_id": "req_5b2e8c0a1f",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

Um preço inexistente ou fora do escopo retorna 404 Not Found com um not_found_error.

PATCH/api/v1/offer-prices/:id

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Atualiza parcialmente um preço. Envie apenas os campos que você deseja alterar.

Parâmetros de caminho

Parâmetros de corpo (todos opcionais)

curl -X PATCH https://api.tokeflow.com/api/v1/offer-prices/opr_b1c2d3e4f5 \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 12900 }'

Resposta 200 OK

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 12900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T13:45:00.000Z"
  },
  "request_id": "req_9d4f1a7e3c",
  "timestamp": "2026-05-19T13:45:00.000Z"
}

DELETE/api/v1/offer-prices/:id

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Exclui logicamente um preço. O registro é mantido para auditabilidade e pode ser recuperado com restauração. A exclusão lógica libera o espaço de moeda do preço — e, se ele era o padrão, o espaço de padrão — para que um novo preço possa ocupá-los.

Parâmetros de caminho

curl -X DELETE https://api.tokeflow.com/api/v1/offer-prices/opr_b1c2d3e4f5 \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME"

Resposta 204 No Content

O corpo da resposta fica vazio em caso de sucesso.

POST/api/v1/offer-prices/:id/restore

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Restaura um preço excluído logicamente, retornando-o ao uso ativo. A restauração é rejeitada se um preço ativo tiver ocupado o mesmo espaço de moeda desde então, ou — para um preço padrão — se a oferta já tiver um padrão novamente.

Parâmetros de caminho

curl -X POST https://api.tokeflow.com/api/v1/offer-prices/opr_b1c2d3e4f5/restore \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME"

Resposta 201 Created

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 12900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T14:10:00.000Z"
  },
  "request_id": "req_1c7a3e9f2d",
  "timestamp": "2026-05-19T14:10:00.000Z"
}

Erros

Os endpoints de preço de oferta usam o envelope de erro padrão do Tokeflow. Casos comuns:

{
  "error": {
    "type": "conflict_error",
    "code": "OFFER_PRICE_CURRENCY_EXISTS",
    "message": "Offer ofr_a1b2c3d4e5 already has a price in currency BRL",
    "details": {},
    "request_id": "req_2f8b1d4c7a",
    "timestamp": "2026-05-19T12:05:00.000Z"
  }
}

Relacionados

• Ofertas — a configuração de cobrança à qual os preços se anexam.
• Produtos — os itens vendáveis aos quais as ofertas pertencem.
• Famílias de Produtos — agrupamento para produtos.
• Autenticação — chaves, escopos e contexto de merchant.