Appearance
Create a program
POST
/programs
Creates a card template. It is created UNPUBLISHED — publish it as a second call once you are happy with it. Image uploads are not part of v1: supply a logo or access image by URL at create time instead. Several fields are conditionally required by type and the example below cannot show every branch at once: a stamp program (standard, private) also needs total_stamps and icon_key, discount needs discount_percent, access needs access_image_url, and prepaid needs initial_balance_cents.
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
255Request 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, "visible_in_catalog": true, "location_scope": "all_locations", "border_enabled": false, "type": "standard"
{
}
Responses
Create 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
{
}
POST
/programs