Merchant offer prices
Manage the priced variants of a merchant's offers — create prices in different currencies, set the default, and soft-delete or restore one.
An offer price is one currency's worth of an offer: an amount in integer minor units plus its ISO 4217 currency. An offer can carry several prices so the same plan sells in several markets.
One price per offer is the default — the one used when a charge does not name a specific price. Prices are soft-deleted, so a price still referenced by an active subscription can be restored rather than lost.
These endpoints power the Tokeflow Dashboard UI. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-merchant-id header identifying the merchant in context, and the signed-in user must be a member with access to it.
The offer price object
Returned by the list and retrieve endpoints on this page.
| Field | Type | Description |
|---|---|---|
id | string | — |
offer_id | string | — |
currency | string | ISO 4217 currency code. |
amount | number | Amount in minor units (cents). |
first_charge_amount | number | null | First-cycle amount in minor units (used when offer.setup_charge = true). 0 = card validation. |
is_default | boolean | — |
created_at | string | (ISO 8601 UTC). |
updated_at | string | (ISO 8601 UTC). |
Endpoints
DELETE/api/v1/merchant/offer-prices/:id
Auth: Dashboard session (JWT bearer). Merchant membership required.
Soft-delete an offer price.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Example request
curl -X DELETE https://api.tokeflow.com/api/v1/merchant/offer-prices/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Example response — 204 No Content
An empty body is returned on success.
GET/api/v1/merchant/offer-prices/:id
Auth: Dashboard session (JWT bearer). Merchant membership required.
Get an offer price by ID.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Example request
curl https://api.tokeflow.com/api/v1/merchant/offer-prices/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Example response — 200
{
"id": "opr_b1c2d3e4f5",
"offer_id": "ofr_a1b2c3d4e5",
"currency": "BRL",
"amount": 9900,
"first_charge_amount": 0,
"is_default": true,
"created_at": "2026-05-19T12:00:00Z",
"updated_at": "2026-05-19T12:00:00Z"
}PATCH/api/v1/merchant/offer-prices/:id
Auth: Dashboard session (JWT bearer). Merchant membership required.
Update an offer price.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Example request
curl -X PATCH https://api.tokeflow.com/api/v1/merchant/offer-prices/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{}'Example response — 200
{
"id": "opr_b1c2d3e4f5",
"offer_id": "ofr_a1b2c3d4e5",
"currency": "BRL",
"amount": 9900,
"first_charge_amount": 0,
"is_default": true,
"created_at": "2026-05-19T12:00:00Z",
"updated_at": "2026-05-19T12:00:00Z"
}POST/api/v1/merchant/offer-prices/:id/restore
Auth: Dashboard session (JWT bearer). Merchant membership required.
Restore a soft-deleted offer price.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Example request
curl -X POST https://api.tokeflow.com/api/v1/merchant/offer-prices/obj_1a2b3c4d/restore \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Example response — 201
{
"id": "opr_b1c2d3e4f5",
"offer_id": "ofr_a1b2c3d4e5",
"currency": "BRL",
"amount": 9900,
"first_charge_amount": 0,
"is_default": true,
"created_at": "2026-05-19T12:00:00Z",
"updated_at": "2026-05-19T12:00:00Z"
}GET/api/v1/merchant/offers/:offerId/prices
Auth: Dashboard session (JWT bearer). Merchant membership required.
List prices for an offer.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
offerId | string | Yes | — |
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number (1-indexed). Default 1, min 1. |
limit | number | No | Number of items per page. Default 20, min 1, max 100. |
currency | string | No | ISO 4217 currency code |
is_default | boolean | No | Filter to the default price only |
Example request
curl -G https://api.tokeflow.com/api/v1/merchant/offers/ofr_5e2b8c14/prices \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "currency=BRL" \
--data-urlencode "is_default=True"Example response — 200
{
"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:00Z",
"updated_at": "2026-05-19T12:00:00Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"total_pages": 3,
"has_next": true,
"has_prev": false
}
}POST/api/v1/merchant/offers/:offerId/prices
Auth: Dashboard session (JWT bearer). Merchant membership required.
Add a price to an offer.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
offerId | string | Yes | — |
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
currency | string | Yes | ISO 4217 currency code. |
amount | number | Yes | Amount in minor units (cents). Ex: R$99.00 = 9900. |
first_charge_amount | number | No | First-cycle amount in minor units. Used when offer.setup_charge = true. 0 = card validation. |
is_default | boolean | No | Default currency for this offer. |
Example request
curl -X POST https://api.tokeflow.com/api/v1/merchant/offers/ofr_5e2b8c14/prices \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{
"currency": "BRL",
"amount": 9900,
"first_charge_amount": 0,
"is_default": true
}'Example response — 201
{
"id": "opr_b1c2d3e4f5",
"offer_id": "ofr_a1b2c3d4e5",
"currency": "BRL",
"amount": 9900,
"first_charge_amount": 0,
"is_default": true,
"created_at": "2026-05-19T12:00:00Z",
"updated_at": "2026-05-19T12:00:00Z"
}Errors
Errors use the standard envelope. The most common cases here:
| HTTP | Meaning |
|---|---|
400 | Invalid parameters or a state that does not allow this operation. |
401 | Missing, expired, or invalid Dashboard session token. |
403 | Authenticated, but the signed-in user lacks access to this entity. |
404 | The record does not exist or is not visible to this entity. |