Appearance
Add a prize
POST
/programs/{id}/prizes
Adds one rung to the ladder, or one more option at a threshold that already exists. threshold is the stamp count that unlocks it and must be reachable — a threshold above the program's total_stamps is refused. Caps: three distinct thresholds per program, three options per threshold.
Authorizations
ApiKeyBearer
A shop-scoped API key created in the dashboard and shown exactly once. An MCP tmk_ key presented here returns a 401 that names the mistake.
Type
HTTP (bearer)
Parameters
Header Parameters
Idempotency-Key
Makes a retry safe: a repeat with the same key and body replays the stored response; the same key with a different body is a 409. Keys are remembered for 24h (IDEMPOTENCY_DEDUPE_WINDOW_HOURS). A request without the header is processed normally.
Type
string
Max Length
255Path Parameters
id*
An opaque id. The API never promises an id format.
Type
Requiredstring
Request Body
application/json
JSON "threshold": 10, "name": "Free coffee", "name_localizations": { "it": "Tessera Caffè" }, "description": "One espresso or filter coffee, redeemed at the till.", "description_localizations": { "it": "Dieci caffè, l’undicesimo lo offriamo noi." }, "ordinal": 0
{
}
Responses
Add a prize
application/json
JSON "id": "prz_docsfixture0001", "program_id": "prg_docsfixture0001", "threshold": 10, "name": "Free coffee", "description": "One espresso or filter coffee, redeemed at the till.", "ordinal": 0, "created_at": "2026-08-05T10:15:00.000Z", "updated_at": "2026-09-04T10:15:00.000Z"
{
}
POST
/programs/{id}/prizes