Partner API — Mabilis na Simula

Kasya sa isang screen ang una mong integration.

Subukan ngayon — walang key, walang sign-up

Buksan ang address na ito sa browser mo. Makikita mo agad ang mga halimbawang event.

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

1
Kumuha ng test key
Mag-sign in, sabihin sa amin kung sino ka, at pindutin ang Gumawa ng Test Key. Nagsisimula ito sa tt_test_ at halimbawang event lang ang nakikita.

Maghanap ng event

Humingi ng mga event sa isang lungsod.

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

3
Ipakita ang event
Bawat event ay may pangalan, petsa, lugar, larawan, presyo at handang label para sa card mo.
4
Gamitin ang buy_url
Gamitin ang buy_url na ibinibigay namin. Iyon na iyon. Ang TimTim.Live ang nagtatala kung saan galing ang benta sa loob ng link na iyon.
5
Tingnan ang resulta
Tingnan ang mga taong naipadala, tiket na nabenta at kita sa dashboard mo, o hingin ang mga ito.
GET https://api.timtim.live/v1/earnings

Kunin ang Aking Test Key Subukan Nang Walang Key

Status ng TimTim.Live

Sanggunian

Saan ipapadala ang mga request

https://api.timtim.live/v1

Ang Iyong Connection Key

Ipadala ang key mo sa Authorization header. Halimbawang event lang ang nakikita ng test key (tt_test_). Puwedeng ilagay sa web page ang website key (tt_pk_live_) at event lang ang nababasa nito. Nananatili sa server mo ang server key (tt_sk_live_) at nababasa rin nito ang kita. Isang beses lang namin ipinapakita ang key — ingatan ito.

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

Mga Filter

city: Mga event sa lungsod na ito.
country: Dalawang-letrang code ng bansa, halimbawa US.
category: Halimbawa: musika, festival o kumperensya.
from: Mga event sa o pagkatapos ng petsang ito (2026-10-20).
to: Mga event sa o bago ang petsang ito.
changed_since: Mga event lang na nagbago pagkatapos ng oras na ito.
commissioned: true = mga event lang na may gantimpala.
minimum_earnings: Mga event lang na nagbabayad ng hindi bababa rito bawat tiket.
near: Isang lugar, halimbawa near=Paris,FR.
limit: Ilang event bawat pahina, 1 hanggang 100 (20 kung hindi mo ilalagay).

Sabihin lang ang nagbago

I-save ang oras ng huli mong sync at ipadala ito bilang changed_since. Ang makukuha mo lang ay mga event na nagbago — kasama ang mga kinansela at sold-out na show. Hindi kailangan ng webhook. Ang mga event na dapat mo nang itigil ipakita ay darating sa listahang withdrawn.

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

Higit sa isang pahina

Kung may next ang sagot, ibalik ito bilang cursor= para makuha ang susunod na pahina. Kapag walang laman ang next, nasa iyo na ang lahat.

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

Kita

Bawat event ay may earn. Kung false ang earn.eligible, walang gantimpala ang event — sulit pa rin itong ipakita. Kung true, sinasabi ng earn.description kung ano ang makukuha mo, halimbawa "$5 bawat kwalipikadong tiket". Kapag na-refund ang pagbili, babawiin ang gantimpala.

Bulk feed (lahat sa iisang file)

Mag-save ng bulk feed sa dashboard mo, saka i-download ang lahat ng event nito sa iisang naka-compress na file: GET /v1/bulk/FEED_ID.ndjson.gz o .csv.gz, gamit ang server key mo. Idagdag ang ?changed_since= para lang sa nagbago, kasama ang mga event na tinanggal. Puwede na itong subukan ng test key ngayon; ang tunay na paggamit ay kailangan ng review ng TimTim.Live.

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

Magbenta ng tiket sa sarili mong app (naka-embed na pagbebenta)

Puwedeng panatilihin ng malalaking partner ang mga mamimili sa sarili nilang app. Itanong ang GET /v1/events/EVENT_ID/tickets para makita kung ano ang ibinebenta, saka ipadala ang POST /v1/orders kasama ang pinili ng mamimili. Makakakuha ka ng link ng bayad ng TimTim.Live na bubuksan mo para sa mamimili; direktang ibinibilang ang benta sa kompanya mo. Puwede na itong subukan ng mga test key ngayon. Ang totoong paggamit ay nangangailangan ng pagsusuri ng TimTim.Live at nakabukas na bayad sa card.

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

Mga alok na naka-link sa card (mga bangko at programa ng gantimpala)

Ibinibigay ng GET /v1/offers ang bawat event na nagbabayad ng gantimpala bilang alok: ang organizer, ang mga petsang puwedeng bumili, ang presyo, ang lugar at ang gantimpala. Ina-activate ito ng customer mo sa pamamagitan ng sinusubaybayang link mo, at ibinabayad ang gantimpala sa kompanya mo sa pamamagitan ng /v1/earnings. Nakakakita ang mga test key ng mga halimbawang alok. Kailangan ng pagsusuri ng TimTim.Live ang mga totoong alok. Ang direktang pagtutugma ng mga bayad sa card ay nangangailangan ng kasunduan sa isang card network o bangko, at hindi pa ito nakakonekta.

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

Status ng event at mga tiket

Ang status ay scheduled, postponed, rescheduled, cancelled, sold_out o completed. Ang tickets.availability ay available, limited, sold_out, not_on_sale o ended. Kapag kinansela ang event, alisin ito.

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

Gaano kabilis ka puwedeng magtanong

Test key: 60 request kada minuto. Live key: 120 kada minuto. Kapag mas mabilis, makakatanggap ka ng sagot na 429 na may Retry-After, ang bilang ng segundong maghihintay.

Aling mga event ang makukuha mo

Mga event na ginawa ng mga organizer ng TimTim.Live at piniling ibahagi. Hindi kailanman kasama ang mga event na kinuha namin mula sa ibang ticket site, dahil wala kaming karapatang ibahagi ang mga ito.

Ang hindi namin kailanman ipinapadala

Pangalan ng mamimili, email address, address ng bahay, numero ng telepono at detalye ng card. Impormasyon ng event ang ibinabahagi ng Partner API, hindi ang aming mga miyembro.

Website widget

Isang linya ng HTML ang nagpapakita ng mga event sa kahit anong website. Gumamit ng website key (tt_pk_live_) at idagdag ang website mo sa listahan ng mga pinapayagang website ng key. Kapag walang key, halimbawang event ang ipinapakita nito.

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

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

OAuth 2.0 (malalaking integration)

Opsyonal. Gumawa ng OAuth client sa dashboard mo, tapos ipalit ang client ID at secret nito sa access token na tatagal nang isang oras, at ipadala ang token na iyon sa halip na key. Hindi kailanman sumasama ang secret sa mga API call mo, at puwede kang humingi ng mas kaunting scope kaysa sa meron ang client.

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

Para tapusin nang maaga ang isang token, i-POST ito sa /v1/oauth/revoke gamit ang parehong client ID at secret. Kapag pinatay mo ang client sa dashboard mo, sabay-sabay na matatapos ang lahat ng token nito.

I-lock ang key sa mga server mo

Opsyonal. Sa dashboard mo, buksan ang "I-lock sa aking mga server" sa ilalim ng server key, test key o OAuth client at ilista ang mga pampublikong address ng mga server mo. Tinatanggihan gamit ang ip_not_allowed ang mga tawag — at mga token request — mula sa ibang lugar, kahit tama ang key.

Mga client certificate (mTLS): ikabit ang TLS client certificate mo sa isang key, saka tawagan ang https://api.timtim.live gamit ito. Dapat ipakita ng bawat tawag ang certificate na iyon; pinapatunayan ng TLS handshake na hawak mo ang private key nito.

# 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

Gumagamit ka ng WordPress? I-install ang TimTim.Live Events: isang block at isang shortcode na nagpapakita ng mga event gamit ang sarili mong TimTim.Live ticket link. Gawa ito ng TimTim.Live, sa timtim.live lang ito kumakausap, at sa timtim.live lang ito nag-a-update.

I-upload ang file sa Plugins → Add New → Upload Plugin. I-paste ang website key mo sa Settings → TimTim.Live Events at pindutin ang Test Connection. Pagkatapos, idagdag ang TimTim.Live Events block sa kahit anong page.

I-download ang WordPress Plugin

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

Mga feed

Ang parehong mga event bilang JSON Feed, RSS, XML, CSV o isang kalendaryo (.ics) na puwedeng i-subscribe ng Google Calendar, Apple Calendar at Outlook. Hindi kayang magpadala ng header ng mga feed reader, kaya ilagay ang website key o test key sa ?key=. Huwag kailanman maglagay ng server key sa isang 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

Mga webhook

Magdagdag ng address sa dashboard mo at magpapadala kami roon ng mensahe kapag may nagbago: event.changed o earnings.changed. Hindi sapilitan ang mga webhook — pareho ring impormasyon ang ibinibigay ng changed_since.

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

Suriin ang bawat mensahe: pirmado ito gamit ang secret mo. Tanggihan ang anumang mas luma sa limang minuto, at huwag pansinin ang TimTim-Delivery-Id na naasikaso mo na.

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

Sumagot ng kahit anong 2xx sa loob ng 10 segundo. Kung hindi, susubukan namin ulit pagkalipas ng 1 minuto, 5 minuto, 30 minuto, tapos 2, 6, 12 at 24 na oras, at saka kami titigil. Hindi kami sumusunod sa mga redirect.

Ang sandbox

Nakakakuha ang test key ng mga halimbawang event na may markang TEST NA EVENT — WALANG TOTOONG PERA. Buksan ang buy_url, pindutin ang Bumili ng Test na Tiket, saka hingin ang kita mo. Subukan ang refund at panoorin itong mabawi.

Kapag may nagkamali

Ipinapaliwanag ng mga error ang sarili nila sa simpleng salita, may pamagat at kung ano ang susunod na gagawin. May TimTim-Request-Id ang bawat sagot. Ipadala ito sa amin at mahahanap namin ang request mo.

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.

Ang kontrata

Buong paliwanag ng bawat field, sa OpenAPI format na nababasa ng iyong mga tool.

I-download ang openapi.yaml

Paano nabubuksan ang mga live key

Gumagana agad ang test key mo. Para sa mga live key, may taga-TimTim.Live na titingin sa pangalan ng kompanya mo, sa website mo at kung paano mo ipapakita ang mga event. Makikita mo ang sagot sa dashboard mo.

Mga Update sa TimTim.Live API

Lumalaki lang ang Version 1. Nagdadagdag kami ng bago. Hindi namin inaalis o pinapalitan ang pangalan ng mga nandiyan na.

2026-10-08 — May ETag na ngayon ang mga sagot tungkol sa event. Ibalik ito sa If-None-Match para makakuha ng mabilis na 304 kapag walang nagbago. Opsyonal.
2026-10-08 — Binibilang na ngayon ng mga website key ang bawat bisita nang hiwalay, kaya patuloy na gumagana ang mga abalang site. Walang kailangang gawin.
2026-10-07 — Bukas na ang mga client certificate (mTLS): ikabit ang certificate mo sa isang key sa dashboard mo. Opsyonal. Walang kailangang gawin.
2026-10-07 — Bulk feed: bawat event na puwede mong ipakita, sa iisang file, sa GET /v1/bulk. Opsyonal. Walang kailangang gawin.
2026-10-07 — May sariling address na ang API: https://api.timtim.live/v1. Gumagana pa rin ang https://timtim.live/v1. Walang kailangang gawin.
2026-10-06 — Sarili mong checkout page na may brand mo sa timtim.live/checkout. Opsyonal. Walang kailangang gawin.
2026-10-06 — Magbenta ng tiket sa sarili mong app: GET /v1/events/EVENT_ID/tickets at POST /v1/orders. Opsyonal. Walang kailangang gawin.
2026-10-06 — Pampublikong status page sa /partners/status, sinusuri bawat minuto. Walang kailangang gawin.
2026-10-06 — Buwanang statement para sa mga kompanya: GET /v1/settlements. Walang kailangang gawin.
2026-10-06 — Mga postback: idagdag ang ?sub_id= sa isang buy link at ibabalik namin ito sa iyo kasama ng benta. Opsyonal. Walang kailangang gawin.
2026-10-06 — Mga alok na naka-link sa card para sa mga bangko at programa ng gantimpala: GET /v1/offers. Opsyonal. Walang kailangang gawin.
2026-10-06 — Calendar feed: /v1/feeds/events.ics para sa Google Calendar, Apple Calendar at Outlook. Walang kailangang gawin.
2026-10-06 — I-lock ang key sa mga server mo: mga IP allowlist ngayon, mga client certificate (mTLS) sa api.timtim.live. Opsyonal. Walang kailangang gawin.
2026-10-06 — OAuth 2.0 client credentials para sa malalaking integration: POST /v1/oauth/token at /v1/oauth/revoke. Gumagana pa rin ang mga key. Walang kailangang gawin.
2026-10-06 — WordPress plugin 1.0.0: isang block, isang shortcode at isang settings page. Kusa itong nag-a-update mula sa timtim.live. Walang kailangang gawin.
2026-10-06 — Website widget, mga feed na JSON/RSS/XML/CSV at mga webhook (event.changed, earnings.changed). Walang kailangang gawin.
2026-10-06 — Partner API v1: mga event, isang event, kita, at ang sandbox. Walang kailangang gawin.