Developers

Ticketz API

Connect your own website, till, kiosk or door system to Ticketz. List your events, sell or issue tickets, scan them at the door and hear about every order as it happens.

API access is switched on per account. Once it is on, create a key under Account, API and webhooks in your dashboard. The key is shown once, so keep it somewhere safe, and only ever use it from your own server, never in a web page.

Basics

• Base address: https://ticketz.uk/api/v1. Always this address, never your own yourname.ticketz.uk event page address.
• Send the key on every call: Authorization: Bearer tz_live_...
• Send and receive JSON. Dates are YYYY-MM-DD, times are HH:MM, UK time. Instants are ISO timestamps. Money is in pence.
• Up to 600 calls every 5 minutes per key. Errors come back as { "error": "plain English message", "code": "..." }.
• An order is identified by its reference, for example TZ-AB12CD. A ticket by its reference TK-AB12CDE or its code (the long string in the QR).
• An event can be referred to by its id, its slug or the externalRef you set on it.

curl https://ticketz.uk/api/v1/events \
  -H "Authorization: Bearer tz_live_..."

Your website

Show your events on your own site and send people to the event page to pay, or issue free tickets from your own form.

POST /api/v1/orders
{ "event": "quiz-night", "items": { "12": 2 },
  "name": "Jo Bloggs", "email": "[email protected]", "phone": "07700 900123",
  "paid": true, "note": "Cash at the bar", "by": "Karen" }

201 { "order": { "ref": "TZ-AB12CD", "status": "paid", "quantity": 2, "total": 2000,
      "tickets": [ { "ref": "TK-XY12ABC", "type": "Standard", "status": "valid", "code": "...", "url": "https://.../t/..." }, ... ] },
      "manageUrl": "https://..." }

To sell paid tickets by card, send people to the event's url. Card payments always go through the event page and your own Stripe account.

Your till or door system

Add "by": "Karen" to any action and the order history shows who did it.

Moving over from another system

POST /import takes up to 1000 orders a call. Give every order your own id as externalRef, so running it again never makes a copy; only a cancellation is brought up to date. Imported orders send no emails or texts, are never charged, and get real ticket codes so the door app can scan or find them. The answer tells you the Ticketz reference for each of your ids.

{ "event": "quiz-night",
  "orders": [ { "externalRef": "old-381", "name": "Rita", "email": "[email protected]", "phone": "07700 900666",
                "tickets": [ { "type": "Standard", "quantity": 2, "price": 1000 } ],
                "paid": true, "total": 2000, "createdAt": "2026-08-01T10:00:00Z" },
              { "externalRef": "old-382", "name": "Sam", "email": "[email protected]",
                "items": { "12": 1 }, "status": "cancelled" } ] }

200 { "imported": 2, "updated": 0, "unchanged": 0, "skipped": 0, "refs": { "old-381": "TZ-...", "old-382": "TZ-..." }, "problems": [] }

tickets names the ticket type (or gives its id) and can set a price; items uses your ticket type ids. checkedIn: true (or a number) marks tickets as already scanned in.

Webhooks

Save an https address under Account, API and webhooks and tick the events you want: order.paid (tickets issued, paid or free), order.cancelled, order.refunded, ticket.checked_in, event.updated. We POST JSON within a second or two, and try twice more if your server does not answer. POST /webhooks/test sends a test event to your address and waits for the result.

{ "id": "evt_...", "type": "order.paid", "createdAt": "...",
  "organiser": { "id": 4, "name": "...", "slug": "..." },
  "data": { "ref": "TZ-AB12CD", "status": "paid", "event": { "id": 7, "slug": "quiz-night", "name": "Quiz night", "date": "2026-10-03", "start": "19:30" },
            "name": "Jo Bloggs", "email": "[email protected]", "quantity": 2, "total": 2000,
            "tickets": [ { "ref": "TK-XY12ABC", "type": "Standard", "status": "valid", "code": "..." } ], ... } }

For ticket.checked_in the data is the order plus ticket, the one just scanned. For event.updated the data is the event.

Every webhook carries a Ticketz-Signature: t=TIMESTAMP,v1=HMAC header. Check it before trusting the body: work out HMAC-SHA256 of TIMESTAMP + "." + raw body with your signing secret, compare it in constant time, and reject anything older than five minutes.

const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const want = crypto.createHmac('sha256', SECRET).update(`${t}.${rawBody}`).digest('hex');
const ok = want.length === v1.length
  && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(v1))
  && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Webhooks can arrive late or not at all if your server is down, so also poll GET /orders?since= every minute or so and you will never miss a change.

Stuck? Send us a help request and we will help.