Partner API — Kòmanse vit

Premye koneksyon w kenbe sou yon sèl ekran.

Eseye l kounye a — pa bezwen kle, pa bezwen enskri

Louvri adrès sa a nan navigatè w. W ap wè evènman egzanp touswit.

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

1
Pran yon kle tès
Konekte, di nou kiyès ou ye, epi peze Kreye kle tès. Li kòmanse ak tt_test_ epi li wè sèlman evènman egzanp.

Jwenn evènman

Mande evènman nan yon vil.

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

3
Montre evènman an
Chak evènman gen yon non, yon dat, yon kote, yon imaj, yon pri ak etikèt tou pare pou kat ou.
4
Itilize buy_url la
Itilize buy_url nou ba ou a. Se tout. TimTim.Live make anndan lyen sa a ke achtè a soti nan ou.
5
Gade rezilta yo
Gade konbyen moun ou voye, konbyen tikè vann ak konbyen lajan ou fè sou tablo w, oswa mande yo.
GET https://api.timtim.live/v1/earnings

Pran kle tès mwen Eseye l san kle

Estati TimTim.Live

Referans

Ki kote pou voye demann yo

https://api.timtim.live/v1

Kle koneksyon w

Voye kle w nan header Authorization. Kle tès (tt_test_) wè sèlman evènman egzanp. Kle sit (tt_pk_live_) ka rete nan yon paj wèb epi yo sèlman li evènman. Kle sèvè (tt_sk_live_) rete sou sèvè w epi yo ka li lajan ou fè tou. Nou montre yon kle yon sèl fwa — kenbe l an sekirite.

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

Filt

city: Evènman nan vil sa a.
country: Kòd peyi ak de lèt, pa egzanp US.
category: Pa egzanp music, festival oswa conference.
from: Evènman nan dat sa a oswa apre (2026-10-20).
to: Evènman nan dat sa a oswa avan.
changed_since: Sèlman evènman ki chanje apre lè sa a.
commissioned: true = sèlman evènman ki peye yon rekonpans.
minimum_earnings: Sèlman evènman ki peye omwen kantite sa a pou chak tikè.
near: Yon kote, pa egzanp near=Paris,FR.
limit: Konbyen evènman pa paj, 1 rive 100 (20 si ou pa mete anyen).

Di m sèlman sa ki chanje

Sere lè dènye senkronizasyon w epi voye l kòm changed_since. Ou resevwa sèlman evènman ki chanje — tankou sa yo anile ak sa ki fin vann. Ou pa bezwen webhook. Evènman ou dwe sispann montre yo vini nan lis withdrawn lan.

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

Plis pase yon paj

Si repons lan gen next, voye l tounen kòm cursor= pou w jwenn paj apre a. Lè next vid, ou gen tout bagay.

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

Fè lajan

Chak evènman gen earn. Si earn.eligible se false, evènman an pa gen rekonpans — li toujou vo lapenn montre l. Si se true, earn.description di sa ou resevwa, pa egzanp "$5 pou chak tikè ki kalifye". Si yo ranbouse acha a, yo retire rekonpans lan.

Fil done konplè (tout bagay nan yon sèl fichye)

Anrejistre yon fil done konplè sou tablo w, epi telechaje tout evènman li kouvri nan yon sèl fichye konprese: GET /v1/bulk/FEED_ID.ndjson.gz oswa .csv.gz, ak kle sèvè ou. Ajoute ?changed_since= pou jwenn sèlman sa ki chanje, ansanm ak evènman yo retire. Kle tès ka eseye l kounye a; pou sèvi ak li tout bon, fòk TimTim.Live fè yon revizyon.

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

Vann tikè nan pwòp app ou (komès entegre)

Gwo patnè yo ka kenbe achtè yo nan pwòp app yo. Mande GET /v1/events/EVENT_ID/tickets pou wè sa ki an vant, epi voye POST /v1/orders ak chwa achtè a. Ou resevwa yon lyen peman TimTim.Live pou w louvri pou achtè a; vant lan konte dirèkteman pou konpayi ou. Kle tès yo ka eseye l kounye a. Vrè itilizasyon bezwen yon revizyon TimTim.Live ak peman kat ki limen.

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": "…"}

Òf ki konekte ak kat (bank ak pwogram rekonpans)

GET /v1/offers bay chak evènman ki peye yon rekonpans kòm yon òf: òganizatè a, dat ou ka achte yo, pri a, kote a ak rekonpans lan. Kliyan ou aktive l atravè lyen ki swiv ou a, epi yo peye rekonpans lan bay konpayi ou atravè /v1/earnings. Kle tès yo wè òf egzanp. Vrè òf bezwen yon revizyon TimTim.Live. Pou fè match peman kat dirèkteman, fòk gen yon akò ak yon rezo kat oswa yon bank, e sa pa konekte.

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

Estati evènman ak tikè

status se scheduled, postponed, rescheduled, cancelled, sold_out oswa completed. tickets.availability se available, limited, sold_out, not_on_sale oswa ended. Lè yo anile yon evènman, retire l.

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

Ki vitès ou ka mande

Kle tès: 60 demann pa minit. Kle live: 120 pa minit. Si ou ale pi vit, w ap resevwa yon repons 429 ak Retry-After, kantite segonn pou w tann.

Ki evènman ou resevwa

Evènman òganizatè TimTim.Live kreye epi chwazi pataje. Evènman nou pran sou lòt sit tikè pa janm ladan, paske nou pa gen dwa pou pataje yo.

Sa nou pa janm voye

Non achtè yo, adrès imel, adrès kay, nimewo telefòn ak enfòmasyon kat. Partner API pataje enfòmasyon sou evènman, pa sou manm nou yo.

Widget pou sit

Yon sèl liy HTML montre evènman sou nenpòt sit. Itilize yon kle sit (tt_pk_live_) epi mete sit ou nan lis sit kle a pèmèt. San kle, li montre evènman egzanp.

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

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

OAuth 2.0 (gwo entegrasyon)

Si ou vle sèlman. Kreye yon kliyan OAuth sou tablo w, apre sa bay ID kliyan ak sekrè li pou w jwenn yon token aksè pou inèdtan, epi voye token sa a olye yon kle. Sekrè a pa janm vwayaje ak apèl API ou yo, epi ou ka mande mwens dwa (scopes) pase sa kliyan an genyen.

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

Pou fini yon token pi bonè, voye l ak POST bay /v1/oauth/revoke avèk menm ID kliyan ak sekrè a. Si ou fèmen kliyan an sou tablo w, tout token li yo fini an menm tan.

Fèmen yon kle sou sèvè ou

Ou pa oblije. Sou tablo w, louvri "Fèmen l sou sèvè pa m" anba yon kle sèvè, kle tès oswa kliyan OAuth, epi ekri adrès piblik sèvè ou yo. Apèl — ak demann token — ki soti nenpòt lòt kote yo refize ak ip_not_allowed, menm avèk bon kle a.

Sètifika kliyan (mTLS): mare sètifika kliyan TLS ou a ak yon kle, epi rele https://api.timtim.live avè l. Chak apèl dwe montre sètifika sa a; handshake TLS la pwouve se ou ki gen kle prive li.

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

Plugin WordPress

Ou sèvi ak WordPress? Enstale TimTim.Live Events: yon blòk ak yon shortcode ki montre evènman ak pwòp lyen tikè TimTim.Live ou. Se TimTim.Live ki fè l, li pale sèlman ak timtim.live, epi li mete tèt li ajou sèlman depi timtim.live.

Voye fichye a nan Plugins → Add New → Upload Plugin. Kole kle sit ou nan Settings → TimTim.Live Events epi peze Test Connection. Apre sa, mete blòk TimTim.Live Events la sou nenpòt paj.

Telechaje Plugin WordPress la

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

Fil done

Menm evènman yo an JSON Feed, RSS, XML, CSV oswa yon kalandriye (.ics) Google Calendar, Apple Calendar ak Outlook ka abòne ladan l. Lektè fil done pa ka voye header, kidonk mete yon kle sit oswa yon kle tès nan ?key=. Pa janm mete yon kle sèvè nan yon lyen.

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

Webhook

Mete yon adrès sou tablo ou epi n ap voye yon mesaj ba li lè yon bagay chanje: event.changed oswa earnings.changed. Webhook pa obligatwa — changed_since ba ou menm enfòmasyon an.

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

Verifye chak mesaj: li siyen ak sekrè ou. Refize nenpòt mesaj ki gen plis pase senk minit, epi pa okipe yon TimTim-Delivery-Id ou te deja trete.

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

Reponn ak nenpòt 2xx nan 10 segonn. Si se pa sa, n ap eseye ankò apre 1 minit, 5 minit, 30 minit, apre sa 2, 6, 12 ak 24 èdtan, epi nou kanpe. Nou pa janm swiv redireksyon.

Sandbox la

Kle tès yo resevwa evènman egzanp ki make EVÈNMAN TÈS — PA GEN VRÈ LAJAN. Louvri yon buy_url, peze Achte tikè tès, epi mande lajan ou fè. Fè sanblan yon ranbousman epi gade yo retire l.

Lè yon bagay mal pase

Erè yo eksplike tèt yo ak mo senp, ak yon tit ak sa pou w fè apre. Chak repons gen yon TimTim-Request-Id. Voye l ban nou epi n ap jwenn demann ou.

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.

Kontra a

Deskripsyon konplè chak chan, nan fòma OpenAPI zouti w yo ka li.

Telechaje openapi.yaml

Kijan kle live yo louvri

Kle tès ou mache touswit. Pou kle live, yon moun nan TimTim.Live gade non konpayi w, sit entènèt ou ak kijan w ap montre evènman yo. Ou wè repons lan sou tablo w.

Nouvèl TimTim.Live API

Vèsyon 1 sèlman ap grandi. Nou ajoute nouvo bagay. Nou pa retire ni chanje non sa ki deja la.

2026-10-08 — Repons sou evènman yo kounye a gen yon ETag. Voye l tounen nan If-None-Match pou w jwenn yon 304 rapid lè anyen pa chanje. Si w vle.
2026-10-08 — Kle sit wèb yo kounye a konte chak vizitè apa, konsa sit ki gen anpil moun kontinye mache. Ou pa bezwen fè anyen.
2026-10-07 — Sètifika kliyan (mTLS) louvri: tache sètifika w ak yon kle sou tablo w. Si w vle. Ou pa bezwen fè anyen.
2026-10-07 — Fil done konplè: chak evènman ou gen dwa montre, nan yon sèl fichye, nan GET /v1/bulk. Si w vle. Ou pa bezwen fè anyen.
2026-10-07 — API a gen pwòp adrès li: https://api.timtim.live/v1. https://timtim.live/v1 kontinye mache. Ou pa bezwen fè anyen.
2026-10-06 — Pwòp paj peman w ak mak ou, nan timtim.live/checkout. Si w vle. Ou pa bezwen fè anyen.
2026-10-06 — Vann tikè nan pwòp aplikasyon w: GET /v1/events/EVENT_ID/tickets ak POST /v1/orders. Si w vle. Ou pa bezwen fè anyen.
2026-10-06 — Yon paj estati piblik nan /partners/status, yo tcheke l chak minit. Ou pa bezwen fè anyen.
2026-10-06 — Rapò chak mwa pou konpayi yo: GET /v1/settlements. Ou pa bezwen fè anyen.
2026-10-06 — Postback: ajoute ?sub_id= nan yon lyen achte epi n ap voye l tounen ba ou ak vant lan. Si w vle. Ou pa bezwen fè anyen.
2026-10-06 — Òf ki mache ak kat bank pou bank ak pwogram rekonpans: GET /v1/offers. Si w vle. Ou pa bezwen fè anyen.
2026-10-06 — Fil kalandriye: /v1/feeds/events.ics pou Google Calendar, Apple Calendar ak Outlook. Ou pa bezwen fè anyen.
2026-10-06 — Fèmen yon kle sou sèvè ou: lis IP ki gen dwa kounye a, sètifika kliyan (mTLS) sou api.timtim.live. Ou pa oblije. Ou pa bezwen fè anyen.
2026-10-06 — OAuth 2.0 client credentials pou gwo entegrasyon: POST /v1/oauth/token ak /v1/oauth/revoke. Kle yo kontinye mache. Ou pa bezwen fè anyen.
2026-10-06 — Plugin WordPress 1.0.0: yon blòk, yon shortcode ak yon paj paramèt. Li mete tèt li ajou depi timtim.live. Ou pa bezwen fè anyen.
2026-10-06 — Widget pou sit, fil done JSON/RSS/XML/CSV ak webhook (event.changed, earnings.changed). Ou pa bezwen fè anyen.
2026-10-06 — Partner API v1: evènman, yon sèl evènman, lajan ou fè, ak sandbox la. Ou pa bezwen fè anyen.