Partner API — Hurtigstart

Den første integrasjonen din får plass på én skjerm.

Prøv nå — ingen nøkkel, ingen registrering

Åpne denne adressen i nettleseren din. Du ser eksempelarrangementer med en gang.

https://timtim.live/api/partner-network/demo?city=Washington

1
Hent en testnøkkel
Logg inn, fortell oss hvem du er, og trykk på Lag testnøkkel. Den starter med tt_test_ og ser bare eksempelarrangementer.

Finn arrangementer

Be om arrangementer i en by.

curl "https://api.timtim.live/v1/events?city=Washington&category=music" \
  -H "Authorization: Bearer tt_test_YOUR_KEY"

3
Vis arrangementet
Hvert arrangement har navn, dato, sted, bilde, pris og ferdige etiketter til kortet ditt.
4
Bruk buy_url
Bruk buy_url-en vi gir deg. Det er alt. TimTim.Live holder styr på hvor salget kom fra, inne i den lenken.
5
Se resultater
Se hvor mange du sendte, solgte billetter og inntekter i oversikten din, eller be om dem.
GET https://api.timtim.live/v1/earnings

Hent testnøkkelen min Prøv uten nøkkel

TimTim.Live-status

Referanse

Hvor du sender forespørsler

https://api.timtim.live/v1

Tilkoblingsnøkkelen din

Send nøkkelen din i Authorization-headeren. Testnøkler (tt_test_) ser bare eksempelarrangementer. Nettstednøkler (tt_pk_live_) kan ligge på en nettside og leser bare arrangementer. Servernøkler (tt_sk_live_) blir på serveren din og kan også lese inntekter. Vi viser en nøkkel bare én gang — ta godt vare på den.

curl

curl "https://api.timtim.live/v1/events?city=Washington&category=music" \
  -H "Authorization: Bearer tt_test_YOUR_KEY"

JavaScript

const res = await fetch("https://api.timtim.live/v1/events?city=Washington&category=music", {
  headers: { Authorization: "Bearer tt_test_YOUR_KEY" },
});
const { events, next } = await res.json();
for (const event of events) {
  console.log(event.name, event.display.date_label, event.tickets.buy_url);
}

Node

// Node 18+ — keep server keys (tt_sk_live_) on the server
const res = await fetch("https://api.timtim.live/v1/events?city=Washington", {
  headers: { Authorization: `Bearer ${process.env.TIMTIM_KEY}` },
});
if (!res.ok) {
  const problem = await res.json();
  throw new Error(`${problem.title} (${problem.request_id})`);
}
const { events } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.timtim.live/v1/events",
    params={"city": "Washington", "category": "music"},
    headers={"Authorization": f"Bearer {os.environ['TIMTIM_KEY']}"},
)
res.raise_for_status()
for event in res.json()["events"]:
    print(event["name"], event["tickets"]["buy_url"])

PHP

<?php
$ch = curl_init("https://api.timtim.live/v1/events?city=Washington&category=music");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer " . getenv("TIMTIM_KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
foreach ($data["events"] as $event) {
  echo $event["name"] . " " . $event["tickets"]["buy_url"] . PHP_EOL;
}

Filtre

city: Arrangementer i denne byen.
country: Landkode med to bokstaver, for eksempel US.
category: For eksempel musikk, festival eller konferanse.
from: Arrangementer på eller etter denne datoen (2026-10-20).
to: Arrangementer på eller før denne datoen.
changed_since: Bare arrangementer som er endret etter dette tidspunktet.
commissioned: true = bare arrangementer som gir belønning.
minimum_earnings: Bare arrangementer som betaler minst så mye per billett.
near: Et sted, for eksempel near=Paris,FR.
limit: Hvor mange arrangementer per side, 1 til 100 (20 hvis du ikke oppgir noe).

Bare fortell meg hva som er endret

Lagre tiden for siste synkronisering og send den som changed_since. Du får bare arrangementer som er endret — også avlysninger og utsolgte forestillinger. Du trenger ingen webhook. Arrangementer du må slutte å vise, kommer i listen withdrawn.

GET https://api.timtim.live/v1/events?changed_since=2026-10-06T10:00:00Z

Mer enn én side

Hvis svaret har next, send det tilbake som cursor= for å få neste side. Når next er tom, har du alt.

GET https://api.timtim.live/v1/events?city=Paris&cursor=eyJtIjoiZCIs…

Inntekter

Hvert arrangement har earn. Hvis earn.eligible er false, har arrangementet ingen belønning — det er likevel verdt å vise. Hvis det er true, sier earn.description hva du får, for eksempel «$5 per billett som oppfyller kravene». Hvis kjøpet blir refundert, trekkes belønningen tilbake.

Bulkfeeder (alt i én fil)

Lagre en bulkfeed i oversikten din, og last så ned alle arrangementene den dekker i én komprimert fil: GET /v1/bulk/FEED_ID.ndjson.gz eller .csv.gz, med servernøkkelen din. Legg til ?changed_since= for bare endringene, også arrangementer som er tatt ned. Testnøkler kan prøve det nå; ekte bruk krever en gjennomgang fra TimTim.Live.

GET https://api.timtim.live/v1/bulk/bfs_YOURFEED.ndjson.gz?changed_since=2026-10-06T00:00:00Z

Selg billetter i din egen app (innebygd handel)

Store partnere kan holde kjøperne i sin egen app. Spør GET /v1/events/EVENT_ID/tickets om hva som er til salgs, og send så POST /v1/orders med kjøperens valg. Du får en TimTim.Live-betalingslenke som du åpner for kjøperen; salget godskrives bedriften din direkte. Testnøkler kan prøve det nå. Ekte bruk krever en gjennomgang fra TimTim.Live og at kortbetaling er slått på.

POST https://api.timtim.live/v1/orders  (Idempotency-Key: …)  {"event_id": "evt_test_washington_konpa", "ticket_type_id": "tt_test_washington_konpa", "quantity": 2, "buyer_email": "…", "buyer_name": "…"}

Kortkoblede tilbud (banker og fordelsprogrammer)

GET /v1/offers gir hvert arrangement som betaler en belønning som et tilbud: arrangøren, datoene man kan kjøpe, prisen, stedet og belønningen. Kunden din aktiverer det via den sporede lenken din, og belønningen betales til bedriften din via /v1/earnings. Testnøkler ser eksempeltilbud. Ekte tilbud trenger en gjennomgang fra TimTim.Live. Å matche kortbetalinger direkte krever en avtale med et kortnettverk eller en bank, og det er ikke koblet til.

GET https://api.timtim.live/v1/offers?country=US

Status for arrangement og billetter

status er scheduled, postponed, rescheduled, cancelled, sold_out eller completed. tickets.availability er available, limited, sold_out, not_on_sale eller ended. Når et arrangement blir avlyst, ta det bort.

GET https://api.timtim.live/v1/events/evt_test_washington_konpa

Hvor raskt du kan spørre

Testnøkler: 60 forespørsler i minuttet. Livenøkler: 120 i minuttet. Går du raskere, får du svaret 429 med Retry-After, som er antall sekunder du må vente.

Hvilke arrangementer du får

Arrangementer som TimTim.Live-arrangører lager og velger å dele. Arrangementer vi har hentet fra andre billettsider, er aldri med, fordi vi ikke har rett til å dele dem.

Dette sender vi aldri

Kjøpernes navn, e-postadresser, hjemmeadresser, telefonnumre og kortopplysninger. Partner API deler informasjon om arrangementer, ikke om medlemmene våre.

Nettstedswidget

Én linje HTML viser arrangementer på hvilket som helst nettsted. Bruk en nettstednøkkel (tt_pk_live_) og legg til nettstedet ditt i nøkkelens liste over tillatte nettsteder. Uten nøkkel viser den eksempelarrangementer.

<script src="https://timtim.live/widget/events.js"
        data-key="tt_pk_live_YOUR_WEBSITE_KEY"
        data-city="Washington" data-category="music" async></script>

Valg: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang og data-color.

OAuth 2.0 (store integrasjoner)

Valgfritt. Lag en OAuth-klient i oversikten din. Bytt så klient-ID-en og hemmeligheten mot et tilgangstoken som varer én time, og send det tokenet i stedet for en nøkkel. Hemmeligheten følger aldri med API-kallene dine, og du kan be om færre rettigheter (scopes) enn klienten har.

# 1. Trade the client ID and secret for a one-hour token
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=events:read events:details" \
  https://api.timtim.live/v1/oauth/token
# → {"access_token":"tt_at_…","token_type":"Bearer","expires_in":3600,"scope":"events:read events:details"}

# 2. Use the token exactly like a key
curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.timtim.live/v1/events?city=Washington"

Vil du stoppe et token tidligere, send det med POST til /v1/oauth/revoke med samme klient-ID og hemmelighet. Slår du av klienten i oversikten din, stopper alle tokenene dens på én gang.

Lås en nøkkel til serverne dine

Valgfritt. Åpne "Lås til mine servere" i oversikten din under en servernøkkel, testnøkkel eller OAuth-klient, og skriv inn de offentlige adressene til serverne dine. Kall — og token-forespørsler — fra alle andre steder blir avvist med ip_not_allowed, selv med riktig nøkkel.

Klientsertifikater (mTLS): knytt TLS-klientsertifikatet ditt til en nøkkel, og kall så https://api.timtim.live med det. Hvert kall må vise det sertifikatet; TLS-håndtrykket beviser at du har den private nøkkelen.

# Your certificate's SHA-256 — paste this (or the PEM) under "Lock to my servers"
openssl x509 -in client.crt -noout -fingerprint -sha256

# Every call then presents the certificate
curl --cert client.crt --key client.key \
  -H "Authorization: Bearer $KEY" "https://api.timtim.live/v1/events?city=Washington"

WordPress-utvidelse

Bruker du WordPress? Installer TimTim.Live Events: en blokk og en kortkode som viser arrangementer med dine egne billettlenker fra TimTim.Live. Den er laget av TimTim.Live, snakker bare med timtim.live og oppdateres bare fra timtim.live.

Last opp filen under Utvidelser → Legg til ny → Last opp utvidelse. Lim inn nettstednøkkelen din under Innstillinger → TimTim.Live Events og trykk på Test Connection. Legg så til blokken TimTim.Live Events på en hvilken som helst side.

Last ned WordPress-utvidelsen

[timtim_events city="Washington" category="music" limit="6"]

Feeder

De samme arrangementene som JSON Feed, RSS, XML, CSV eller en kalender (.ics) som Google Calendar, Apple Calendar og Outlook kan abonnere på. Feedlesere kan ikke sende headere, så legg en nettstednøkkel eller en testnøkkel i ?key=. Legg aldri en servernøkkel i en lenke.

https://timtim.live/v1/feeds/events.json?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.rss?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.xml?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.csv?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.ics?key=tt_pk_live_YOUR_KEY&city=Paris

Webhooks

Trykk på «Legg til adresse» på kontrollpanelet ditt, så sender vi en melding dit når noe endres: event.changed eller earnings.changed. Webhooks er valgfrie — changed_since gir deg den samme informasjonen.

{
  "id": "whd_8Fk2mQxR7tLp",
  "type": "event.changed",
  "created_at": "2026-10-06T15:04:05.000Z",
  "mode": "live",
  "data": {
    "event": {
      "id": "ev_…",
      "name": "…",
      "status": "cancelled",
      "tickets": {
        "availability": "ended",
        "buy_url": "https://timtim.live/b/…"
      },
      "…": "the same event object as GET /v1/events"
    }
  }
}

Sjekk hver melding: den er signert med hemmeligheten din. Avvis alt som er eldre enn fem minutter, og ignorer en TimTim-Delivery-Id du allerede har håndtert.

// 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);
});

Svar med en hvilken som helst 2xx innen 10 sekunder. Hvis ikke, prøver vi igjen etter 1 minutt, 5 minutter, 30 minutter, så etter 2, 6, 12 og 24 timer, og så stopper vi. Vi følger aldri omdirigeringer.

Sandkassen

Testnøkler får eksempelarrangementer merket TESTARRANGEMENT — INGEN EKTE PENGER. Åpne en buy_url, trykk på Kjøp testbillett, og be så om inntektene dine. Prøv en refusjon og se at den trekkes tilbake.

Når noe går galt

Feilmeldinger forklarer seg selv med enkle ord, med en tittel og hva du skal gjøre videre. Hvert svar har en TimTim-Request-Id. Send den til oss, så finner vi forespørselen din.

401missing_keyPlease add your TimTim.Live key. Send it as: Authorization: Bearer tt_test_… — get a test key at /partners/dashboard.
401invalid_keyWe do not recognise that key. Check you copied the whole key, or make a new one at /partners/dashboard.
401revoked_keyThat key was switched off. Make a new key at /partners/dashboard.
403partner_inactiveThis partner account cannot use live keys right now. Your test key still works. Contact TimTim.Live partnerships to review the account.
403missing_scopeThis key is not allowed to do that. Earnings need a secret key (tt_sk_live_…) or a test key, used from your server.
403domain_not_allowedThis website is not allowed to use this key. Add the website to the key's allowed domains at /partners/dashboard.
400unknown_parameterWe do not know one of those parameters. See /partners/docs for the list.
400invalid_countryWe could not read that country. Use a two-letter code, for example country=US or country=FR.
400invalid_dateWe could not read that date. Dates look like 2026-10-20.
400invalid_changed_sinceWe could not read changed_since. Use a full time, for example changed_since=2026-10-06T10:00:00Z.
400invalid_booleanThat value must be true or false. For example commissioned=true.
400invalid_numberThat value must be a number. For example minimum_earnings=5.
400invalid_nearWe could not find that place. Try near=Paris,FR or city=Paris&country=FR.
400invalid_locationWe could not read that location. Send lat, lng and optionally radius in kilometres.
400invalid_limitlimit must be between 1 and 100. Leave it out to get 20.
400invalid_cursorThat cursor is not one we gave you. Use the `next` value from the previous page exactly as it came.
404event_not_foundWe could not find that event. It may have been removed, or it is not shared with partners.
403capability_requiredCard-linked offers are not switched on for your account. Offers are an enterprise feature. Your test key shows sample offers now; ask TimTim.Live partnerships to review your account for live offers.
403server_key_requiredThis is for your server only. Use a secret key (tt_sk_live_…) or a test key from your server, never a website key in a web page.
403commerce_not_enabledSelling tickets in your own app is not switched on for your account. This is an enterprise feature (EMBEDDED_CHECKOUT). Your test key can try it now; ask TimTim.Live partnerships to review your account. Until then, use each event's buy_url.
503checkout_not_openCard payments are not open on TimTim.Live yet. Send the buyer to the event's buy_url instead. Your test key can still rehearse orders.
409ticket_not_availableThat ticket cannot be bought right now. It may be sold out, not on sale yet, or no longer on sale. Ask /v1/events/{id}/tickets for what is on sale now.
400order_invalidWe could not read that order. See /partners/docs for the fields an order needs.
400idempotency_key_requiredPlease send an Idempotency-Key header. 8 to 80 letters, digits, - or _. Send the same key again to retry safely — you will get the same order, never a second one.
404order_not_foundWe could not find that order. Only orders your company began with this kind of key (test or live) can be read here.
403bulk_not_enabledBulk feeds are not switched on for your account. This is an enterprise feature (BULK_FEEDS). Your test key can try it now; ask TimTim.Live partnerships to review your account. Until then, page through /v1/events or the feeds.
404bulk_not_foundWe could not find that bulk feed. Use the address shown on /partners/dashboard: /v1/bulk/<subscription id>.ndjson.gz or .csv.gz.
429bulk_too_soonA full file was made for this feed a few minutes ago. Full files can be made every 15 minutes. For what changed since, add changed_since=<time> — that is not limited.
410event_withdrawnThis event is no longer shared with partners. Stop showing it and remove its buy_url. Nothing else is needed — your old link still takes people to the event page.
400invalid_trackWe could not read that tracking signal. Send {"type":"impression"}, {"type":"event_view","event_id":"…"} or {"type":"event_click","event_id":"…"}. Sales are recorded by TimTim.Live, never sent from a page.
404not_foundThere is nothing at this address. The Partner API lives at /v1/events, /v1/events/{id}, /v1/offers and /v1/earnings.
405method_not_allowedThis address does not answer that method. The Allow header lists the methods it answers.
401key_in_urlSend your key in the Authorization header. Only /v1/feeds reads a key from the URL (?key=). Everywhere else use Authorization: Bearer <key> — keys in URLs end up in logs.
403ip_not_allowedThis key only works from your listed servers. Call from an address on the key's allowlist, or change the list at /partners/dashboard.
401certificate_requiredThis key needs your client certificate. Connect to https://api.timtim.live with the TLS client certificate pinned to this key.
401certificate_mismatchThat is not the certificate pinned to this key. Use the certificate whose SHA-256 is on your dashboard, or pin the new one there.
429rate_limitedToo many requests — please slow down. Wait the number of seconds in Retry-After, then try again.
503unavailableThe Partner API is resting for a moment. Please try again in a minute.
500server_errorSomething went wrong on our side. Please try again. If it keeps happening, send us your TimTim Request ID.

Kontrakten

Full beskrivelse av hvert felt, i OpenAPI-formatet som verktøyene dine kan lese.

Last ned openapi.yaml

Slik åpner live-nøkler

Testnøkkelen din virker med en gang. For live-nøkler ser en person hos TimTim.Live på firmanavnet ditt, nettstedet ditt og hvordan du skal vise arrangementer. Du ser svaret i oversikten din.

Oppdateringer av TimTim.Live API

Versjon 1 blir bare større. Vi legger til nye ting. Vi fjerner ikke og gir ikke nytt navn til det som allerede finnes.

2026-10-08 — Svar om arrangementer har nå en ETag. Send den tilbake i If-None-Match for å få en rask 304 når ingenting er endret. Valgfritt.
2026-10-08 — Nettstednøkler teller nå hver besøkende for seg, så travle nettsteder fortsetter å virke. Ingen handling nødvendig.
2026-10-07 — Klientsertifikater (mTLS) er åpne: knytt sertifikatet ditt til en nøkkel i oversikten din. Valgfritt. Ingen handling nødvendig.
2026-10-07 — Bulkfeeder: alle arrangementer du får vise, i én fil, på GET /v1/bulk. Valgfritt. Ingen handling nødvendig.
2026-10-07 — API-et har sin egen adresse: https://api.timtim.live/v1. https://timtim.live/v1 fungerer fortsatt. Ingen handling nødvendig.
2026-10-06 — Din egen betalingsside med ditt merke på timtim.live/checkout. Valgfritt. Ingen handling nødvendig.
2026-10-06 — Selg billetter i din egen app: GET /v1/events/EVENT_ID/tickets og POST /v1/orders. Valgfritt. Ingen handling nødvendig.
2026-10-06 — En offentlig statusside på /partners/status, sjekket hvert minutt. Ingen handling nødvendig.
2026-10-06 — Månedlige oppgjør for bedrifter: GET /v1/settlements. Ingen handling nødvendig.
2026-10-06 — Postbacks: legg ?sub_id= til en kjøpslenke, så sender vi den tilbake til deg sammen med salget. Valgfritt. Ingen handling nødvendig.
2026-10-06 — Kortkoblede tilbud for banker og fordelsprogrammer: GET /v1/offers. Valgfritt. Ingen handling nødvendig.
2026-10-06 — Kalenderfeed: /v1/feeds/events.ics for Google Calendar, Apple Calendar og Outlook. Du trenger ikke gjøre noe.
2026-10-06 — Lås en nøkkel til serverne dine: lister over tillatte IP-er nå, klientsertifikater (mTLS) på api.timtim.live. Valgfritt. Du trenger ikke gjøre noe.
2026-10-06 — OAuth 2.0 client credentials for store integrasjoner: POST /v1/oauth/token og /v1/oauth/revoke. Nøkler virker fortsatt. Du trenger ikke gjøre noe.
2026-10-06 — WordPress-utvidelse 1.0.0: en blokk, en kortkode og en innstillingsside. Den oppdaterer seg selv fra timtim.live. Du trenger ikke gjøre noe.
2026-10-06 — Nettstedswidget, JSON/RSS/XML/CSV-feeder og webhooks (event.changed, earnings.changed). Du trenger ikke gjøre noe.
2026-10-06 — Partner API v1: arrangementer, ett arrangement, inntekter og sandkassen. Du trenger ikke gjøre noe.