Appearance
Update a card
PATCH
/cards/{id}
Holder fields and external_ref. A card installed on a device is locked: its holder fields and expiry are frozen and a write returns 409 card_locked — reissue it (which unbinds the device) and the fields open again. An ARCHIVED card is a different 409, conflict, and reissue is NOT the way round that one: archiving is permanent, and it KEEPS the holder as the audit record of whose card it was, so the holder fields can never be edited again — issue a new card instead. external_ref is the exception to both: it is yours, not the holder's, so it stays writable, and it is applied BEFORE the holder fields are refused — a PATCH that mixes the two can therefore 409 with external_ref already changed. Requires an UNRESTRICTED key: a key limited to specific locations is refused with 403 location_scope_unsupported, and shop-wide data is never silently served to it instead. A card is not attributed to a location anywhere in TesserApp — it belongs to a program, and programs belong to the whole shop — so there is no correct subset of cards to serve such a key.
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 "holder_name": "Ada Lovelace", "holder_email": "ada@docsfixture.invalid", "expires_at": "2026-10-04T10:15:00.000Z", "external_ref": "EMP-00417"
{
}
Responses
Update a card
application/json
JSON "id": "cin_docsfixture0001", "program_id": "prg_docsfixture0001", "program_name": "Coffee Card", "program_type": "standard", "external_ref": "EMP-00417", "holder_name": "Ada Lovelace", "holder_email": "ada@docsfixture.invalid", "status": "active", "stamps_count": 4, "current_value": 4, "expires_at": "2026-10-04T10:15:00.000Z", "installed_at": "2026-09-04T10:15:00.000Z", "created_at": "2026-08-05T10:15:00.000Z", "all_locations": true, "locations": [ { "id": "loc_docsfixture0001", "name": "Via Roma 1" } ], "barcode": { "scan_url": "https://tesserapp.eu/scan/prg_docsfixture0001/cin_docsfixture0001", "legacy_payload": "tlp:prg_docsfixture0001:cin_docsfixture0001" }
{
}
PATCH
/cards/{id}