Appearance
Update a program
PATCH
/programs/{id}
A partial update — send only the fields you are changing. type is immutable after create. If any card from this program is installed on a device the template is locked and this returns 409 program_has_installed_cards: publish a new program rather than editing a card people are already carrying. Sending prizes REPLACES the whole ladder; omit it to leave the ladder alone, and send [] to clear it.
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 "name": "Coffee Card", "name_localizations": { "it": "Tessera Caffè" }, "description": "Ten coffees, the eleventh on us.", "description_localizations": { "it": "Dieci caffè, l’undicesimo lo offriamo noi." }, "category": "bar", "brand_color_hex": "#6F4E37", "logo_url": "https://cdn.tesserapp.eu/shops/caffe-docsfixture/logo.png", "total_stamps": 10, "repeat_after_reset": true, "stamps_expire_after_days": 180
{
}
Responses
Update a program
application/json
JSON "id": "prg_docsfixture0001", "name": "Coffee Card", "description": "Ten coffees, the eleventh on us.", "category": "bar", "type": "standard", "active": true, "published_at": "2026-09-04T10:15:00.000Z", "suspended_at": null, "total_stamps": 10, "repeat_after_reset": true, "discount_percent": null, "initial_balance_cents": null, "default_expire_after_days": 365, "logo_url": "https://cdn.tesserapp.eu/shops/caffe-docsfixture/logo.png", "access_image_url": null, "brand_color_hex": "#6F4E37", "bg_color_hex": "#FFF8F0", "text_color_hex": "#2B1B12", "icon_key": "mug-hot", "location_scope": "all_locations", "scoped_location_ids": [ "loc_docsfixture0001" ], "created_at": "2026-08-05T10:15:00.000Z", "updated_at": "2026-09-04T10:15:00.000Z", "prizes": [ { "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" } ], "has_installed_cards": false
{
}
PATCH
/programs/{id}