Offer Prices

An offer price attaches a concrete amount, in a specific currency, to an offer. An offer can carry several prices — one per currency — so the same plan can be sold in BRL, USD, EUR, and more. Exactly one price per offer can be marked as the default for that offer.

Prices are the leaf of the catalog. The offer defines how a plan bills (cycle, trial, setup); the price defines how much it costs in each currency.

How pricing works

• Amounts are integer minor units. Store cents, not decimals. R$99.00 is 9900; US$150.00 is 15000. Always pair an amount with an ISO 4217 currency.
• One price per currency, per offer. An offer cannot have two live prices in the same currency. Creating or updating a price into a currency that is already taken returns 409 Conflict.
• One default per offer. At most one price on an offer can have is_default: true. The default is the price Tokeflow surfaces first (and lists first) for that offer.
• first_charge_amount drives setup charges. When the parent offer has setup_charge = true, the first cycle is billed at first_charge_amount instead of amount. A value of 0 means a card-validation-only first charge (for example, a free trial that verifies the card). Leave it null to bill the standard amount on the first cycle.

The offer price object

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

All offer price endpoints live under https://api.tokeflow.com/api/v1. Authentication uses a secret key — see Authentication.

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

Auth: Organization key (with merchant_id) or Merchant key.

Adds a price to an existing offer. The parent offer must belong to the authenticated merchant.

Path parameters

Body parameters

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
  }'

Response 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: Organization key (with merchant_id) or Merchant key.

Lists the prices on an offer, default first then by currency. Supports filtering and pagination.

Path parameters

Query parameters

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"

Response 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: Organization key (with merchant_id) or Merchant key.

Retrieves a single price by its opr_ ID. The price must belong to an offer owned by the authenticated merchant.

Path parameters

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

Response 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"
}

A missing or out-of-scope price returns 404 Not Found with a not_found_error.

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

Auth: Organization key (with merchant_id) or Merchant key.

Partially updates a price. Send only the fields you want to change.

Path parameters

Body parameters (all optional)

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 }'

Response 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: Organization key (with merchant_id) or Merchant key.

Soft-deletes a price. The record is retained for auditability and can be brought back with restore. Soft-deleting frees the price's currency slot — and, if it was the default, the default slot — so a new price can occupy them.

Path parameters

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

Response 204 No Content

The response body is empty on success.

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

Auth: Organization key (with merchant_id) or Merchant key.

Restores a soft-deleted price, returning it to active use. Restore is rejected if a live price has since taken the same currency slot, or — for a default price — if the offer already has a default again.

Path parameters

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

Response 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"
}

Errors

Offer price endpoints use Tokeflow's standard error envelope. Common cases:

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

Related

• Offers — the billing configuration prices attach to.
• Products — the sellable items offers belong to.
• Product Families — grouping for products.
• Authentication — keys, scopes, and merchant context.