API Reference

Authentication

Every question carries your key, so TimTim.Live knows who is asking. Send it in the Authorization header: Bearer tt_….

• tt_test_…

  Sandbox. Sample events only. Free, made on the dashboard.

• tt_pk_live_…

  Website key. Safe in a web page. Locked to your domains.

• tt_sk_live_…

  Secret key. Server only. Never put it in a page or an app.

No key at all? GET /v1/demo/events answers anyone with sample events. Big companies can swap a name and password for a one-hour pass instead (OAuth, how). Most people do not need it.

Endpoints

Each row is one endpoint: 19 in all. Long lists come in pages, as { object: "list", events: […], next }. Send next back as cursor to get the next page (cursor).

Keeping up with changes

Ask GET /v1/events?changed_since=2026-10-06T10:00:00Z to get every event that changed after that time — including ones that ended or were cancelled. The answer also has a withdrawn list: events you may no longer show. Remove those ids. Or skip polling and use webhooks.

Status and availability

Every event has a status:

• scheduled
• postponed
• rescheduled
• cancelled
• sold_out
• completed

and tickets.availability: available, limited, sold_out, not_on_sale or ended. Hide the ticket button when it is sold_out or ended. See it happen.

Which events you get

Only events their organizers sell on TimTim.Live, that are published and public, and whose organizers left partner sharing on. Each event says so in can_share. Test keys get sample events only.

Buy links and attribution

Each event has a buy link in tickets.buy_url. Send people there. TimTim.Live runs the checkout, the tickets and the refunds, and the sale is counted for your key. Do not change the link. Want to know which of your pages sent the buyer? Add ?sub_id= with your own click id. It comes back on the earning, the webhook and any postback.

Your results are in GET /v1/earnings.

Webhooks

A webhook is a message TimTim.Live sends to your server when something happens: event.changed, earnings.changed, conversion.postback. Add webhook addresses on the dashboard.

Verify the signature

Each message carries a seal made with a secret only you and TimTim.Live know. Check it before you trust the message. The code below does it. The details: every delivery has TimTim-Signature: t=…,v1=…. v1 is HMAC-SHA256 of t + "." + the raw body with your webhook secret. Refuse it if the time is more than 5 minutes off, and use TimTim-Delivery-Id to ignore repeats.

// Node — Express with the RAW body (do not JSON.parse before checking)
import crypto from "node:crypto";

app.post("/timtim", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("TimTim-Signature") ?? "";           // t=1700000000,v1=<hex>
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const body = req.body.toString("utf8");
  const expected = crypto.createHmac("sha256", process.env.TIMTIM_WEBHOOK_SECRET)
    .update(`${parts.t}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  const same = expected.length === (parts.v1 ?? "").length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  if (!fresh || !same) return res.sendStatus(400);

  const message = JSON.parse(body);                            // { id, type, mode, data }
  if (alreadyHandled(req.get("TimTim-Delivery-Id"))) return res.sendStatus(200);
  // message.type === "event.changed"    → message.data.event
  // message.type === "earnings.changed" → message.data.earning
  res.sendStatus(200);
});

Retries

Reply "got it" (any 2xx code) within 10 seconds. If you do not, we try again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h — 8 tries in all. Test keys' webhooks retry the same way.

Rate limits

A rate limit is how many questions a key may ask in one minute.

• Test keys: 60 requests a minute.
• Live keys: 120 a minute (1200 for approved high-volume partners).
• Website keys count each visitor on their own: 120 a minute per visitor, and up to 6000 a minute for the whole site.

The same question from a website key gets the same answer for 30 seconds. So a busy page is fast, and new events show up within half a minute.

Too many? You get 429 and a Retry-After header in seconds. Wait that long. See a real 429.

Errors

When something goes wrong, the answer says what happened (title) and what to do next (detail). It also has a code and a request_id. Send us the request id and we can find it. Technically it is application/problem+json (error answer). Every error code.