Partner API — Kom hurtigt i gang

Din første integration kan være på én skærm.

Prøv det nu — ingen nøgle, ingen tilmelding

Åbn denne adresse i din browser. Du ser eksempelbegivenheder med det samme.

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

1
Hent en testnøgle
Log ind, fortæl os, hvem du er, og tryk på Opret testnøgle. Den starter med tt_test_ og ser kun eksempelbegivenheder.

Find begivenheder

Bed om begivenheder i en by.

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

3
Vis begivenheden
Hver begivenhed har navn, dato, sted, billede, pris og færdige etiketter til dit kort.
4
Brug buy_url
Brug den buy_url, vi giver dig. Det er det hele. TimTim.Live holder styr på, hvor salget kom fra, inde i det link.
5
Se resultater
Se, hvor mange du har sendt, solgte billetter og indtjening i dit overblik, eller bed om dem.
GET https://api.timtim.live/v1/earnings

Hent min testnøgle Prøv uden nøgle

TimTim.Live-status

Reference

Hvor du sender forespørgsler

https://api.timtim.live/v1

Din forbindelsesnøgle

Send din nøgle i Authorization-headeren. Testnøgler (tt_test_) ser kun eksempelbegivenheder. Websitenøgler (tt_pk_live_) kan ligge på en webside og læser kun begivenheder. Servernøgler (tt_sk_live_) bliver på din server og kan også læse indtjening. Vi viser en nøgle én gang — pas godt 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: Begivenheder i denne by.
country: Landekode med to bogstaver, for eksempel US.
category: For eksempel musik, festival eller konference.
from: Begivenheder på eller efter denne dato (2026-10-20).
to: Begivenheder på eller før denne dato.
changed_since: Kun begivenheder, der er ændret efter dette tidspunkt.
commissioned: true = kun begivenheder, der giver en belønning.
minimum_earnings: Kun begivenheder, der betaler mindst så meget pr. billet.
near: Et sted, for eksempel near=Paris,FR.
limit: Hvor mange begivenheder pr. side, 1 til 100 (20, hvis du ikke angiver noget).

Fortæl mig kun, hvad der er ændret

Gem tidspunktet for din seneste synkronisering, og send det som changed_since. Du får kun begivenheder, der er ændret — også aflysninger og udsolgte forestillinger. Du behøver ingen webhook. Begivenheder, du skal holde op med at vise, kommer i listen withdrawn.

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

Mere end én side

Hvis svaret har next, så send det tilbage som cursor= for at få næste side. Når next er tom, har du det hele.

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

Indtjening

Hver begivenhed har earn. Hvis earn.eligible er false, har begivenheden ingen belønning — den er stadig værd at vise. Hvis den er true, fortæller earn.description, hvad du får, for eksempel »$5 pr. billet, der opfylder kravene«. Hvis købet bliver refunderet, trækkes belønningen tilbage.

Bulk-feeds (alt i én fil)

Gem et bulk-feed i dit overblik, og hent så alle dets begivenheder i én komprimeret fil: GET /v1/bulk/FEED_ID.ndjson.gz eller .csv.gz, med din servernøgle. Tilføj ?changed_since= for kun ændringerne, også fjernede begivenheder. Testnøgler kan prøve det nu; rigtig brug kræver en gennemgang fra TimTim.Live.

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

Sælg billetter i din egen app (indbygget handel)

Store partnere kan holde købere i deres egen app. Spørg GET /v1/events/EVENT_ID/tickets om, hvad der er til salg, og send så POST /v1/orders med køberens valg. Du får et TimTim.Live-betalingslink, som du åbner for køberen; salget krediteres direkte til din virksomhed. Testnøgler kan prøve det nu. Rigtig brug kræver en gennemgang fra TimTim.Live og at kortbetalinger er slået til.

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 giver hver begivenhed, der udbetaler en belønning, som et tilbud: arrangøren, de datoer man kan købe, prisen, stedet og belønningen. Din kunde aktiverer det via dit sporede link, og belønningen udbetales til din virksomhed via /v1/earnings. Testnøgler ser eksempeltilbud. Rigtige tilbud kræver en gennemgang fra TimTim.Live. At matche kortbetalinger direkte kræver en aftale med et kortnetværk eller en bank, og det er ikke tilsluttet.

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

Status for begivenhed 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 en begivenhed bliver aflyst, så fjern den.

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

Hvor hurtigt du kan spørge

Testnøgler: 60 forespørgsler i minuttet. Livenøgler: 120 i minuttet. Går du hurtigere, får du svaret 429 med Retry-After, som er det antal sekunder, du skal vente.

Hvilke begivenheder du får

Begivenheder, som TimTim.Live-arrangører opretter og vælger at dele. Begivenheder, vi har hentet fra andre billetsider, er aldrig med, fordi vi ikke har ret til at dele dem.

Det sender vi aldrig

Købernes navne, e-mailadresser, hjemmeadresser, telefonnumre og kortoplysninger. Partner API deler oplysninger om begivenheder, ikke om vores medlemmer.

Widget til websites

Én linje HTML viser begivenheder på ethvert website. Brug en websitenøgle (tt_pk_live_), og føj dit website til nøglens liste over tilladte websites. Uden nøgle viser den eksempelbegivenheder.

<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 integrationer)

Valgfrit. Opret en OAuth-klient i dit overblik. Byt så dens klient-id og hemmelighed til et adgangstoken, der gælder i én time, og send det token i stedet for en nøgle. Hemmeligheden følger aldrig med dine API-kald, og du kan bede om færre rettigheder (scopes), end 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 før tid, så send det med POST til /v1/oauth/revoke med samme klient-id og hemmelighed. Slår du klienten fra i dit overblik, stopper alle dens tokens på én gang.

Lås en nøgle til dine servere

Valgfrit. Åbn "Lås til mine servere" i dit overblik under en servernøgle, testnøgle eller OAuth-klient, og skriv dine serveres offentlige adresser. Kald — og token-anmodninger — fra alle andre steder bliver afvist med ip_not_allowed, selv med den rigtige nøgle.

Klientcertifikater (mTLS): knyt dit TLS-klientcertifikat til en nøgle, og kald så https://api.timtim.live med det. Hvert kald skal vise det certifikat; TLS-handshaket beviser, at du har dets private nøgle.

# 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-plugin

Bruger du WordPress? Installér TimTim.Live Events: en blok og en shortcode, der viser begivenheder med dine egne TimTim.Live-billetlinks. Den er lavet af TimTim.Live, taler kun med timtim.live og opdateres kun fra timtim.live.

Upload filen i Plugins → Tilføj nyt → Upload plugin. Indsæt din websitenøgle i Indstillinger → TimTim.Live Events, og tryk på Test Connection. Tilføj så blokken TimTim.Live Events til en hvilken som helst side.

Download WordPress-pluginnet

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

Feeds

De samme begivenheder som JSON Feed, RSS, XML, CSV eller en kalender (.ics), som Google Calendar, Apple Calendar og Outlook kan abonnere på. Feedlæsere kan ikke sende headers, så sæt en websitenøgle eller en testnøgle i ?key=. Sæt aldrig en servernøgle i et link.

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

Tilføj en adresse i dit overblik, så sender vi en besked dertil, når noget ændrer sig: event.changed eller earnings.changed. Webhooks er frivillige — changed_since giver dig de samme oplysninger.

{
  "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"
    }
  }
}

Tjek hver besked: den er signeret med din hemmelige nøgle. Afvis alt, der er ældre end fem minutter, og ignorer et TimTim-Delivery-Id, du allerede har håndteret.

// 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 inden for 10 sekunder. Ellers prøver vi igen efter 1 minut, 5 minutter og 30 minutter, derefter efter 2, 6, 12 og 24 timer, og så stopper vi. Vi følger aldrig omdirigeringer.

Sandkassen

Testnøgler får eksempelbegivenheder mærket TESTBEGIVENHED — INGEN RIGTIGE PENGE. Åbn en buy_url, tryk på Køb testbillet, og bed så om din indtjening. Prøv en refusion, og se den blive trukket tilbage.

Når noget går galt

Fejl forklarer sig selv med enkle ord, med en titel og hvad du skal gøre bagefter. Hvert svar har et TimTim-Request-Id. Send det til os, så kan vi finde din forespørgsel.

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

Den fulde beskrivelse af hvert felt i OpenAPI-formatet, som dine værktøjer kan læse.

Download openapi.yaml

Sådan åbner live-nøgler

Din testnøgle virker med det samme. Ved live-nøgler kigger en person hos TimTim.Live på dit firmanavn, dit website og hvordan du vil vise begivenheder. Du ser svaret i dit overblik.

Opdateringer til TimTim.Live API

Version 1 vokser kun. Vi tilføjer nye ting. Vi fjerner eller omdøber ikke det, der allerede er der.

2026-10-08 — Svar om begivenheder har nu et ETag. Send det tilbage i If-None-Match for at få et hurtigt 304, når intet er ændret. Valgfrit.
2026-10-08 — Webstednøgler tæller nu hver besøgende for sig, så travle websteder bliver ved med at virke. Du skal ikke gøre noget.
2026-10-07 — Klientcertifikater (mTLS) er åbne: knyt dit certifikat til en nøgle i dit overblik. Valgfrit. Du skal ikke gøre noget.
2026-10-07 — Bulk-feeds: alle begivenheder, du må vise, i én fil, på GET /v1/bulk. Valgfrit. Du skal ikke gøre noget.
2026-10-07 — API'et har sin egen adresse: https://api.timtim.live/v1. https://timtim.live/v1 virker stadig. Ingen handling nødvendig.
2026-10-06 — Din egen betalingsside med dit brand på timtim.live/checkout. Valgfrit. Du skal ikke gøre noget.
2026-10-06 — Sælg billetter i din egen app: GET /v1/events/EVENT_ID/tickets og POST /v1/orders. Valgfrit. Du skal ikke gøre noget.
2026-10-06 — En offentlig statusside på /partners/status, tjekket hvert minut. Du skal ikke gøre noget.
2026-10-06 — Månedlige opgørelser til virksomheder: GET /v1/settlements. Du skal ikke gøre noget.
2026-10-06 — Postbacks: sæt ?sub_id= på et købslink, så sender vi det tilbage til dig sammen med salget. Valgfrit. Du skal ikke gøre noget.
2026-10-06 — Kortkoblede tilbud til banker og fordelsprogrammer: GET /v1/offers. Valgfrit. Du skal ikke gøre noget.
2026-10-06 — Kalenderfeed: /v1/feeds/events.ics til Google Calendar, Apple Calendar og Outlook. Du skal ikke gøre noget.
2026-10-06 — Lås en nøgle til dine servere: IP-tilladelseslister nu, klientcertifikater (mTLS) på api.timtim.live. Valgfrit. Du skal ikke gøre noget.
2026-10-06 — OAuth 2.0 client credentials til store integrationer: POST /v1/oauth/token og /v1/oauth/revoke. Nøgler virker stadig. Du skal ikke gøre noget.
2026-10-06 — WordPress-plugin 1.0.0: en blok, en shortcode og en side med indstillinger. Den opdaterer sig selv fra timtim.live. Du skal ikke gøre noget.
2026-10-06 — Widget til websites, feeds i JSON/RSS/XML/CSV og webhooks (event.changed, earnings.changed). Du skal ikke gøre noget.
2026-10-06 — Partner API v1: begivenheder, én begivenhed, indtjening og sandkassen. Du skal ikke gøre noget.