Partner API v1
TicketsHere voor ontwikkelaars
Verkoop tickets via je eigen website, met je eigen opmaak en bestelformulier. TicketsHere.nl regelt prijzen, voorraad, reserveringen, de betaling via Stripe, het maken en mailen van de tickets met QR-code en het scannen aan de deur.
Base URL: https://www.ticketshere.nl/api/v1
Verkoop tickets op je eigen website
- Maak je event en ticketsoorten aan in je organisatorportaal en zet het event live. Prijzen, aantallen en het maximum per bestelling stel je daar in; de API neemt ze over.
- Koppel je Stripe-account onder Stripe. Jij blijft de verkoper op de betaalpagina en ontvangt het geld via Stripe.
- Ga naar API & integraties, maak een sleutel aan en vul het adres van je website in (bijv.
https://jouwsite.nl). Kopieer de sleutel direct: hij wordt maar één keer getoond. - Geef de sleutel aan je webbouwer. Die zet hem als geheime omgevingsvariabele op de server van je website (nooit in de browser of in HTML/JavaScript die bezoekers zien).
- Je website toont de events en ticketsoorten (GET /events), vraagt naam en e-mail van de koper, maakt een bestelling aan (POST /checkout) en stuurt de koper door naar de betaalpagina. Na betaling komt de koper terug op jouw bedankpagina en krijgt hij automatisch de tickets van TicketsHere per e-mail.
- Optioneel: stel een webhook-adres in, zodat je website direct hoort dat een bestelling betaald, terugbetaald of verlopen is.
- Aan de deur scan je zoals altijd met de TicketsHere-scanner. Alle verkopen staan ook in je portaal.
Hoe het werkt
Verloop
1. Jouw server GET /api/v1/events → events, ticketsoorten, prijzen, beschikbaarheid
2. Koper vult jouw bestelformulier in
3. Jouw server POST /api/v1/checkout → reservering (30 min) + order_id + checkout_url
4. Jouw server redirect koper naar checkout_url (Stripe-betaalpagina)
5. Koper betaalt → Stripe → terug naar jouw success_url (?order=TH-…)
6. TicketsHere maakt de tickets, mailt ze met QR-code naar de koper
7. Jouw server ontvangt webhook order.paid (of vraagt GET /api/v1/orders/:id)De success_url is géén betaalbewijs: iedereen kan die URL openen. Kijk voor de status altijd naar de webhook of GET /orders/:id. De status wordt paid zodra Stripe de betaling aan ons heeft bevestigd (meestal binnen een paar seconden).
Authenticatie
Stuur bij elk verzoek de header Authorization: Bearer th_live_… mee. Een sleutel hoort bij precies één organisator en ziet alleen diens events en bestellingen. De API is alleen bedoeld voor server-naar-server-verkeer: er zijn geen CORS-headers en cookies of inlogsessies worden genegeerd.
Uitgelekt? Trek de sleutel direct in onder API & integraties en maak een nieuwe. Een ingetrokken sleutel werkt meteen niet meer.
GET /events
GET/api/v1/events
Alle gepubliceerde, toekomstige events van jouw organisatie die nu te koop zijn, op datum. Bedragen zijn in centen.
curl
curl https://www.ticketshere.nl/api/v1/events \
-H "Authorization: Bearer $TICKETSHERE_API_KEY"Response 200
{
"data": [
{
"id": "cmwdunlnm0009m48r9q717ib1",
"slug": "mr-bear-netherlands-2027-election",
"title": "Mr Bear Netherlands 2027 Election",
"description": "Plain text, line breaks as \n",
"description_format": "text",
"starts_at": "2027-06-18T20:00:00+02:00",
"ends_at": "2027-06-18T23:00:00+02:00",
"timezone": "Europe/Amsterdam",
"location": "Amsterdam",
"image_url": null,
"url": "https://www.ticketshere.nl/evenementen/mr-bear-netherlands-2027-election",
"organizer": { "name": "Amsterdam Bear Pride", "logo_url": "https://www.ticketshere.nl/uploads/…" },
"sales_status": "on_sale",
"ticket_types": [
{
"id": "cmwduos2r000bm48rn0d3huz6",
"name": "Early Bird",
"description": null,
"price_cents": 1500,
"currency": "EUR",
"buyer_fee_cents": 0,
"available": 50,
"min_per_order": 1,
"max_per_order": 2,
"sales_start": null,
"sales_end": "2027-06-18T23:00:00+02:00",
"sales_status": "on_sale",
"sold_out": false
}
]
}
]
}| Veld | Betekenis |
|---|---|
description | Platte tekst zoals de organisator hem typte (regeleinden als \n). Geen HTML: escape hem zelf als je hem in HTML zet. |
starts_at / ends_at | ISO 8601 met tijdzone-offset (Europe/Amsterdam). ends_at kan null zijn. |
image_url | Volledige URL van de eventafbeelding die de organisator heeft geüpload (liefst 16:9), of null als er geen is. Het logo staat in organizer.logo_url. |
sales_status | on_sale · not_started · sold_out · ended · unavailable |
ticket_types[].description | Korte omschrijving van de ticketsoort (platte tekst, maximaal 300 tekens), of null. |
price_cents | Prijs per kaart inclusief btw, wat de koper betaalt. |
buyer_fee_cents | Servicekosten voor de koper. Altijd 0: de koper betaalt precies de ticketprijs. |
available | Nu nog te koop. Lopende (onbetaalde) reserveringen zijn er al af. |
min_per_order / max_per_order | Minimum (altijd 1) en maximum aantal per bestelling. |
sales_start / sales_end | Verkoopperiode van de ticketsoort. sales_start is null als de verkoop direct loopt; sales_end is het ingestelde einde, of anders het einde van het event (nooit later). |
ticket_types[].sales_status | on_sale · not_started · ended · sold_out: alleen on_sale kun je nu bestellen. |
GET /events/:id
GET/api/v1/events/:id
Hetzelfde object voor één event, in data. Ook een voorbij event wordt nog getoond (met sales_status: "ended"), zodat oude links blijven werken. Concepten en events van andere organisatoren geven 404 event_not_found.
curl
curl https://www.ticketshere.nl/api/v1/events/cmwdunlnm0009m48r9q717ib1 \
-H "Authorization: Bearer $TICKETSHERE_API_KEY"POST /checkout
POST/api/v1/checkout
Maakt een bestelling met een reservering van 30 minuten en een Stripe-betaalpagina. Dit is precies hetzelfde proces als het bestelformulier op TicketsHere.nl: dezelfde prijzen, voorraad, maximum per bestelling en kosten. De body bevat nooit prijzen: het bedrag komt uit onze database. Onbekende velden worden geweigerd.
| Veld | Verplicht | Betekenis |
|---|---|---|
event_id | ja | Id uit GET /events. |
items[] | ja | 1–20 regels { ticket_type_id, quantity }; elke ticketsoort maximaal één keer. |
customer.name | ja | 2–100 tekens; komt op de tickets. |
customer.email | ja | Hier sturen we de tickets heen. |
customer.ip | nee, aanbevolen | IP-adres van de koper. Daarmee beperken we openstaande reserveringen per koper in plaats van per server. |
locale | nee | nl (standaard) of en: taal van de betaalpagina. |
success_url | ja | https-URL op een toegestane origin van je sleutel. Mag {ORDER_ID} bevatten; die vullen wij in. |
cancel_url | ja | Waar de koper heen gaat als hij de betaling afbreekt. Zelfde regels. |
metadata | nee | Max. 20 eigen sleutels/waarden (tekst, ≤ 500 tekens). Komt terug in GET /orders en webhooks. |
Header Idempotency-Key is verplicht (1–255 zichtbare ASCII-tekens, bijv. een UUID per bestelpoging). Hetzelfde verzoek met dezelfde key binnen 24 uur geeft precies hetzelfde antwoord (met header Idempotent-Replayed: true) en maakt nooit een tweede bestelling. Dezelfde key met een andere body geeft 422 idempotency_key_reused.
curl
curl https://www.ticketshere.nl/api/v1/checkout \
-X POST \
-H "Authorization: Bearer $TICKETSHERE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f1c2a9e-0d7b-4c1e-9a43-2b8f6e7d1c00" \
-d '{
"event_id": "cmwdunlnm0009m48r9q717ib1",
"items": [
{ "ticket_type_id": "cmwduo5wa000am48rexcdal80", "quantity": 2 }
],
"customer": { "name": "Jan Jansen", "email": "jan@example.com", "ip": "203.0.113.7" },
"locale": "en",
"success_url": "https://amsterdambearpride.com/tickets/thanks?order={ORDER_ID}",
"cancel_url": "https://amsterdambearpride.com/tickets",
"metadata": { "cart_id": "abc123" }
}'Response 201
HTTP/1.1 201 Created
{
"order_id": "TH-2026-000042",
"status": "pending",
"checkout_url": "https://checkout.stripe.com/c/pay/cs_live_…",
"expires_at": "2026-11-12T20:31:00+01:00",
"total_cents": 3500,
"currency": "EUR"
}Stuur de koper door naar checkout_url. De betaalpagina verloopt op expires_at; daarna komen de kaarten weer vrij en wordt de bestelling expired.
Node.js (fetch, Express)
// Server-side only (e.g. an Express route). Never call the API from the browser.
import { randomUUID } from "node:crypto";
const API = "https://www.ticketshere.nl/api/v1";
const KEY = process.env.TICKETSHERE_API_KEY; // th_live_…
app.post("/tickets/order", async (req, res) => {
const response = await fetch(`${API}/checkout`, {
method: "POST",
headers: {
Authorization: `Bearer ${KEY}`,
"Content-Type": "application/json",
// One key per order attempt: a retry with the same key never creates a second order.
"Idempotency-Key": req.body.attemptId ?? randomUUID(),
},
body: JSON.stringify({
event_id: req.body.eventId,
items: req.body.items, // [{ ticket_type_id, quantity }]
customer: { name: req.body.name, email: req.body.email, ip: req.ip },
locale: "en",
success_url: "https://amsterdambearpride.com/tickets/thanks?order={ORDER_ID}",
cancel_url: "https://amsterdambearpride.com/tickets",
}),
});
const result = await response.json();
if (!response.ok) {
// e.g. { error: { code: "sold_out", message: "…", ticket_type_id: "…" } }
return res.status(response.status).json(result.error);
}
res.redirect(303, result.checkout_url); // to the Stripe payment page
});GET /orders/:id
GET/api/v1/orders/:id
Status en inhoud van een bestelling van jouw events (id = order_id, bijv. TH-2026-000042). Het e-mailadres is gemaskeerd. Status: pending · paid · expired · cancelled · refunded.
curl
curl https://www.ticketshere.nl/api/v1/orders/TH-2026-000042 \
-H "Authorization: Bearer $TICKETSHERE_API_KEY"Response 200
{
"data": {
"id": "TH-2026-000042",
"status": "paid",
"event_id": "cmwdunlnm0009m48r9q717ib1",
"currency": "EUR",
"total_cents": 3500,
"items": [
{
"ticket_type_id": "cmwduo5wa000am48rexcdal80",
"name": "Regular Ticket",
"quantity": 2,
"unit_price_cents": 1750,
"total_cents": 3500
}
],
"tickets_issued": 2,
"customer": { "email": "j**@example.com" },
"metadata": { "cart_id": "abc123" },
"created_at": "2026-11-12T20:00:04+01:00",
"paid_at": "2026-11-12T20:02:31+01:00",
"refunded_at": null
}
}Node.js
const response = await fetch(`${API}/orders/${encodeURIComponent(orderId)}`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await response.json();
if (data.status === "paid") {
// Tickets (PDF + QR codes) have been e-mailed to the buyer by TicketsHere.
}Foutcodes
Elke fout heeft dezelfde vorm, met soms extra velden (zoals ticket_type_id, max_per_order, field of scope). Reageer op code, niet op message.
Response 409
HTTP/1.1 409 Conflict
{
"error": {
"code": "sold_out",
"message": "Not enough tickets available for this ticket type.",
"ticket_type_id": "cmwduos2r000bm48rn0d3huz6"
}
}| HTTP | code | Betekenis |
|---|---|---|
| 400 | duplicate_ticket_type | Een ticket_type_id staat twee keer in items. |
| 400 | idempotency_key_missing | Header Idempotency-Key ontbreekt of is ongeldig. |
| 400 | invalid_quantity | quantity is geen geheel getal ≥ 1. |
| 400 | invalid_request | Ongeldige JSON, ontbrekend of onbekend veld (bijv. een prijs). |
| 400 | invalid_return_url | success_url/cancel_url niet op een toegestane origin van de sleutel (veld in `field`). |
| 400 | max_per_order | Meer dan max_per_order voor een ticketsoort. |
| 400 | no_items | Geen kaarten gekozen. |
| 400 | ticket_type_not_found | ticket_type_id hoort niet bij dit event. |
| 401 | unauthorized | Geen, ongeldige of ingetrokken API-sleutel. |
| 404 | event_not_found | Event bestaat niet, is niet gepubliceerd of is van een andere organisator. |
| 404 | not_found | Onbekend endpoint of onbekende bestelling. |
| 409 | idempotency_in_progress | Een verzoek met deze key loopt nog; probeer het zo opnieuw. |
| 409 | sales_closed | Het event is voorbij of de verkoop staat (tijdelijk) dicht. |
| 409 | sold_out | Niet genoeg kaarten meer beschikbaar (ticket_type_id in de fout). |
| 409 | ticket_sales_closed | De verkoopperiode van deze ticketsoort is nog niet begonnen of al voorbij (ticket_type_id, reason en evt. sales_start in de fout). |
| 409 | too_many_open_orders | Te veel onbetaalde bestellingen of gereserveerde tickets open (per e-mail, koper-IP of sleutel; zie `scope`: email, customer_ip, api_key of api_key_tickets, en `limit`). |
| 422 | idempotency_key_reused | Zelfde Idempotency-Key met een andere body. |
| 429 | rate_limited | Te veel verzoeken; wacht het aantal seconden uit Retry-After. |
| 500 | internal_error | Fout bij ons; opnieuw proberen met dezelfde Idempotency-Key is veilig. |
| 503 | payment_unavailable | Betalen is tijdelijk niet mogelijk; de reservering is vrijgegeven. |
Rate limits
| Wat | Limiet |
|---|---|
| GET-verzoeken per sleutel | 300 per minuut |
| GET-verzoeken per IP | 600 per minuut |
| POST /checkout per sleutel | 30 per minuut |
| POST /checkout per IP | 60 per minuut |
| POST /checkout per customer.ip | 10 per 15 minuten |
| Mislukte authenticatie per IP | 30 per 15 minuten |
| Onbetaalde bestellingen per e-mailadres | 3 |
| Onbetaalde bestellingen per customer.ip | 5 |
| Onbetaalde bestellingen per sleutel | 100 |
| Gereserveerde tickets (in onbetaalde bestellingen) per sleutel | 200 in totaal, en per event 20% van alle tickets van dat event |
Boven een maximum voor onbetaalde bestellingen krijg je 409 too_many_open_orders met scope en limit. Bij api_key_tickets telt het aantal tickets dat je sleutel op dat moment in onbetaalde bestellingen vasthoudt, plus de nieuwe bestelling: dat mag niet boven min(200, 20% van alle tickets van het event) komen. Zodra bestellingen betaald zijn of verlopen (na 30 minuten) komt er weer ruimte vrij. Raakt je sleutel een rate limit of een van deze maxima, dan mailen we de organisator en support (hooguit één keer per uur per sleutel).
Boven een limiet krijg je 429 rate_limited met header Retry-After (seconden). Cache GET /events gerust een minuut op je server; available is altijd actueel bij ons.
Webhooks
Stel per sleutel een https-adres in onder API & integraties. Je krijgt dan één keer een geheim (whsec_…). Wij sturen een POST met JSON bij order.paid, order.refunded, order.expired en order.cancelled voor bestellingen die via die sleutel zijn gemaakt. order.paid gaat pas de deur uit nadat Stripe de betaling aan ons heeft bevestigd en de tickets zijn aangemaakt.
Voorbeeld
POST /webhooks/ticketshere HTTP/1.1
Content-Type: application/json
User-Agent: TicketsHere-Webhooks/1.0
TicketsHere-Webhook-Id: whd_Xb3…
TicketsHere-Webhook-Event: order.paid
TicketsHere-Webhook-Timestamp: 1794517351
TicketsHere-Webhook-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
{
"id": "whd_Xb3…",
"type": "order.paid",
"api_version": "v1",
"created_at": "2026-11-12T19:02:31.512Z",
"data": {
"order": { "id": "TH-2026-000042", "status": "paid", "…": "same fields as GET /orders/:id" }
}
}De handtekening is HMAC-SHA256 (hex) met je geheim over `${timestamp}.${body}`, waarbij body de ruwe request-body is. Antwoord binnen 10 seconden met een 2xx-status. Anders proberen we het opnieuw na 1 min, 5 min, 30 min, 2 uur, 6 uur, 12 uur, 24 uur; daarna staat de melding op ‘mislukt’ in je logboek (daar kun je hem opnieuw versturen). Een melding kan meer dan eens aankomen: ontdubbel op id. Redirects volgen we niet.
Verificatie in Node.js (Express)
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const SECRET = process.env.TICKETSHERE_WEBHOOK_SECRET; // whsec_…
function verify(rawBody, timestamp, signature) {
if (!timestamp || !signature || !/^\d+$/.test(timestamp)) return false;
// Reject messages older than 5 minutes (replay protection).
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = "v1=" + createHmac("sha256", SECRET)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && timingSafeEqual(a, b);
}
// Use the RAW body: re-serialised JSON does not match the signature.
app.post("/webhooks/ticketshere", express.raw({ type: "application/json" }), async (req, res) => {
const raw = req.body.toString("utf8");
if (!verify(raw, req.get("TicketsHere-Webhook-Timestamp"), req.get("TicketsHere-Webhook-Signature"))) {
return res.status(400).send("invalid signature");
}
const event = JSON.parse(raw);
// Deliveries can arrive more than once: deduplicate on event.id.
switch (event.type) {
case "order.paid": /* mark the order paid in your own database */ break;
case "order.refunded": /* tickets are no longer valid */ break;
case "order.expired": /* not paid in time; stock was released */ break;
case "order.cancelled": /* payment cancelled; stock was released */ break;
}
res.sendStatus(200); // answer 2xx within 10 seconds
});Goed om te weten
- Bewaar de API-sleutel en het webhookgeheim alleen op je server. Roep de API nooit aan vanuit de browser.
- Je bent zelf de verkoper op de Stripe-betaalpagina; de koper krijgt de gewone TicketsHere-ticketmail met QR-codes en scant aan de deur met TicketsHere.
- Terugbetalen gaat zoals altijd via je organisatorportaal; daarna volgt order.refunded en zijn de tickets ongeldig.
- Bedragen zijn hele centen (integer). Tijden zijn ISO 8601 met tijdzone.
- v1 blijft stabiel: we voegen hooguit velden toe. Negeer velden die je niet kent.
- Vragen? Mail support@ticketshere.nl.