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

  1. 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.
  2. Koppel je Stripe-account onder Stripe. Jij blijft de verkoper op de betaalpagina en ontvangt het geld via Stripe.
  3. 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.
  4. 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).
  5. 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.
  6. Optioneel: stel een webhook-adres in, zodat je website direct hoort dat een bestelling betaald, terugbetaald of verlopen is.
  7. 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
        }
      ]
    }
  ]
}
VeldBetekenis
descriptionPlatte tekst zoals de organisator hem typte (regeleinden als \n). Geen HTML: escape hem zelf als je hem in HTML zet.
starts_at / ends_atISO 8601 met tijdzone-offset (Europe/Amsterdam). ends_at kan null zijn.
image_urlVolledige 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_statuson_sale · not_started · sold_out · ended · unavailable
ticket_types[].descriptionKorte omschrijving van de ticketsoort (platte tekst, maximaal 300 tekens), of null.
price_centsPrijs per kaart inclusief btw, wat de koper betaalt.
buyer_fee_centsServicekosten voor de koper. Altijd 0: de koper betaalt precies de ticketprijs.
availableNu nog te koop. Lopende (onbetaalde) reserveringen zijn er al af.
min_per_order / max_per_orderMinimum (altijd 1) en maximum aantal per bestelling.
sales_start / sales_endVerkoopperiode 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_statuson_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.

VeldVerplichtBetekenis
event_idjaId uit GET /events.
items[]ja1–20 regels { ticket_type_id, quantity }; elke ticketsoort maximaal één keer.
customer.nameja2–100 tekens; komt op de tickets.
customer.emailjaHier sturen we de tickets heen.
customer.ipnee, aanbevolenIP-adres van de koper. Daarmee beperken we openstaande reserveringen per koper in plaats van per server.
localeneenl (standaard) of en: taal van de betaalpagina.
success_urljahttps-URL op een toegestane origin van je sleutel. Mag {ORDER_ID} bevatten; die vullen wij in.
cancel_urljaWaar de koper heen gaat als hij de betaling afbreekt. Zelfde regels.
metadataneeMax. 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"
  }
}
HTTPcodeBetekenis
400duplicate_ticket_typeEen ticket_type_id staat twee keer in items.
400idempotency_key_missingHeader Idempotency-Key ontbreekt of is ongeldig.
400invalid_quantityquantity is geen geheel getal ≥ 1.
400invalid_requestOngeldige JSON, ontbrekend of onbekend veld (bijv. een prijs).
400invalid_return_urlsuccess_url/cancel_url niet op een toegestane origin van de sleutel (veld in `field`).
400max_per_orderMeer dan max_per_order voor een ticketsoort.
400no_itemsGeen kaarten gekozen.
400ticket_type_not_foundticket_type_id hoort niet bij dit event.
401unauthorizedGeen, ongeldige of ingetrokken API-sleutel.
404event_not_foundEvent bestaat niet, is niet gepubliceerd of is van een andere organisator.
404not_foundOnbekend endpoint of onbekende bestelling.
409idempotency_in_progressEen verzoek met deze key loopt nog; probeer het zo opnieuw.
409sales_closedHet event is voorbij of de verkoop staat (tijdelijk) dicht.
409sold_outNiet genoeg kaarten meer beschikbaar (ticket_type_id in de fout).
409ticket_sales_closedDe verkoopperiode van deze ticketsoort is nog niet begonnen of al voorbij (ticket_type_id, reason en evt. sales_start in de fout).
409too_many_open_ordersTe 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`).
422idempotency_key_reusedZelfde Idempotency-Key met een andere body.
429rate_limitedTe veel verzoeken; wacht het aantal seconden uit Retry-After.
500internal_errorFout bij ons; opnieuw proberen met dezelfde Idempotency-Key is veilig.
503payment_unavailableBetalen is tijdelijk niet mogelijk; de reservering is vrijgegeven.

Rate limits

WatLimiet
GET-verzoeken per sleutel300 per minuut
GET-verzoeken per IP600 per minuut
POST /checkout per sleutel30 per minuut
POST /checkout per IP60 per minuut
POST /checkout per customer.ip10 per 15 minuten
Mislukte authenticatie per IP30 per 15 minuten
Onbetaalde bestellingen per e-mailadres3
Onbetaalde bestellingen per customer.ip5
Onbetaalde bestellingen per sleutel100
Gereserveerde tickets (in onbetaalde bestellingen) per sleutel200 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