TicketsHere for developers

Sell tickets on your own website, with your own design and order form. TicketsHere.nl handles prices, stock, reservations, the Stripe payment, creating and e-mailing the tickets with QR code, and scanning at the door.

Base URL: https://www.ticketshere.nl/api/v1

Sell tickets on your own website

  1. Create your event and ticket types in your organiser portal and publish it. Prices, quantities and the maximum per order are set there; the API uses them.
  2. Connect your Stripe account under Stripe. You remain the seller on the payment page and receive the money through Stripe.
  3. Go to API & integrations, create a key and enter your website address (e.g. https://yoursite.com). Copy the key right away: it is shown only once.
  4. Give the key to your web developer, who stores it as a secret environment variable on your website's server (never in the browser or in HTML/JavaScript visitors can see).
  5. Your website shows the events and ticket types (GET /events), asks for the buyer's name and e-mail, creates an order (POST /checkout) and sends the buyer to the payment page. After paying, the buyer returns to your thank-you page and automatically receives the tickets from TicketsHere by e-mail.
  6. Optional: set a webhook URL so your website hears immediately when an order is paid, refunded or expired.
  7. At the door you scan as usual with the TicketsHere scanner. All sales also appear in your portal.

How it works

Flow

1. Your server   GET  /api/v1/events            → events, ticket types, prices, availability
2. Buyer         fills in your order form
3. Your server   POST /api/v1/checkout          → reservation (30 min) + order_id + checkout_url
4. Your server   redirects the buyer to checkout_url (Stripe payment page)
5. Buyer         pays → Stripe → back to your success_url (?order=TH-…)
6. TicketsHere   creates the tickets and e-mails them with QR code to the buyer
7. Your server   receives webhook order.paid  (or calls GET /api/v1/orders/:id)

The success_url is not proof of payment: anyone can open that URL. Always use the webhook or GET /orders/:id for the status. It becomes paid as soon as Stripe has confirmed the payment to us (usually within seconds).

Authentication

Send the header Authorization: Bearer th_live_… with every request. A key belongs to exactly one organiser and only sees that organiser's events and orders. The API is for server-to-server traffic only: there are no CORS headers, and cookies or login sessions are ignored.

Leaked? Revoke the key right away under API & integrations and create a new one. A revoked key stops working immediately.

GET /events

GET/api/v1/events

All published, upcoming events of your organisation that are on sale now, by date. Amounts are in cents.

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
        }
      ]
    }
  ]
}
FieldMeaning
descriptionPlain text as the organiser typed it (line breaks as \n). Not HTML: escape it when you put it into HTML.
starts_at / ends_atISO 8601 with time-zone offset (Europe/Amsterdam). ends_at may be null.
image_urlFull URL of the event image uploaded by the organiser (preferably 16:9), or null when there is none. The logo is in organizer.logo_url.
sales_statuson_sale · not_started · sold_out · ended · unavailable
ticket_types[].descriptionShort description of the ticket type (plain text, at most 300 characters), or null.
price_centsPrice per ticket including VAT, what the buyer pays.
buyer_fee_centsService fee for the buyer. Always 0: the buyer pays exactly the ticket price.
availableStill on sale now. Running (unpaid) reservations are already deducted.
min_per_order / max_per_orderMinimum (always 1) and maximum quantity per order.
sales_start / sales_endSales period of the ticket type. sales_start is null when sales run right away; sales_end is the configured end, otherwise the end of the event (never later).
ticket_types[].sales_statuson_sale · not_started · ended · sold_out: only on_sale can be ordered now.

GET /events/:id

GET/api/v1/events/:id

The same object for one event, in data. An event that has ended is still returned (with sales_status: "ended") so old links keep working. Drafts and other organisers' events return 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

Creates an order with a 30-minute reservation and a Stripe payment page. This is exactly the same process as the order form on TicketsHere.nl: same prices, stock, maximum per order and fees. The body never contains prices: the amount comes from our database. Unknown fields are refused.

FieldRequiredMeaning
event_idyesId from GET /events.
items[]yes1–20 lines { ticket_type_id, quantity }; each ticket type at most once.
customer.nameyes2–100 characters; printed on the tickets.
customer.emailyesWhere we send the tickets.
customer.ipno, recommendedBuyer's IP address. Lets us limit open reservations per buyer instead of per server.
localenonl (default) or en: language of the payment page.
success_urlyeshttps URL on an allowed origin of your key. May contain {ORDER_ID} which we fill in.
cancel_urlyesWhere the buyer goes when cancelling the payment. Same rules.
metadatanoUp to 20 own keys/values (text, ≤ 500 chars). Returned in GET /orders and webhooks.

The Idempotency-Key header is required (1–255 visible ASCII characters, e.g. a UUID per order attempt). The same request with the same key within 24 hours returns exactly the same response (with header Idempotent-Replayed: true) and never creates a second order. The same key with a different body returns 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"
}

Redirect the buyer to checkout_url. The payment page expires at expires_at; after that the tickets are released and the order becomes 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 and contents of an order for your events (id = order_id, e.g. TH-2026-000042). The e-mail address is masked. 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.
}

Error codes

Every error has the same shape, sometimes with extra fields (such as ticket_type_id, max_per_order, field or scope). Act on code, not on 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"
  }
}
HTTPcodeMeaning
400duplicate_ticket_typeA ticket_type_id appears twice in items.
400idempotency_key_missingIdempotency-Key header missing or invalid.
400invalid_quantityquantity is not a whole number ≥ 1.
400invalid_requestInvalid JSON, missing or unknown field (e.g. a price).
400invalid_return_urlsuccess_url/cancel_url not on an allowed origin of the key (see `field`).
400max_per_orderMore than max_per_order for a ticket type.
400no_itemsNo tickets chosen.
400ticket_type_not_foundticket_type_id does not belong to this event.
401unauthorizedMissing, invalid or revoked API key.
404event_not_foundEvent does not exist, is not published or belongs to another organiser.
404not_foundUnknown endpoint or order.
409idempotency_in_progressA request with this key is still running; retry shortly.
409sales_closedThe event has ended or sales are (temporarily) closed.
409sold_outNot enough tickets left (ticket_type_id in the error).
409ticket_sales_closedThe sales period of this ticket type has not started yet or has ended (ticket_type_id, reason and possibly sales_start in the error).
409too_many_open_ordersToo many unpaid orders or reserved tickets open (per e-mail, buyer IP or key; see `scope`: email, customer_ip, api_key or api_key_tickets, and `limit`).
422idempotency_key_reusedSame Idempotency-Key with a different body.
429rate_limitedToo many requests; wait the seconds in Retry-After.
500internal_errorError on our side; retrying with the same Idempotency-Key is safe.
503payment_unavailablePayment is temporarily unavailable; the reservation was released.

Rate limits

WhatLimit
GET requests per key300 per minute
GET requests per IP600 per minute
POST /checkout per key30 per minute
POST /checkout per IP60 per minute
POST /checkout per customer.ip10 per 15 minutes
Failed authentication per IP30 per 15 minutes
Unpaid orders per e-mail address3
Unpaid orders per customer.ip5
Unpaid orders per key100
Reserved tickets (in unpaid orders) per key200 in total, and per event 20% of all tickets of that event

Above a cap on unpaid orders you get 409 too_many_open_orders with scope and limit. For api_key_tickets we count the tickets your key currently holds in unpaid orders plus the new order: that may not exceed min(200, 20% of all tickets of the event). Room frees up as soon as orders are paid or expire (after 30 minutes). When your key hits a rate limit or one of these caps, we e-mail the organiser and our support (at most once per hour per key).

Above a limit you get 429 rate_limited with a Retry-After header (seconds). Feel free to cache GET /events for a minute on your server; available is always current on our side.

Webhooks

Set an https URL per key under API & integrations. You receive a secret once (whsec_…). We send a JSON POST on order.paid, order.refunded, order.expired and order.cancelled for orders created with that key. order.paid is only sent after Stripe has confirmed the payment to us and the tickets were created.

Example

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

The signature is HMAC-SHA256 (hex) with your secret over `${timestamp}.${body}`, where body is the raw request body. Answer within 10 seconds with a 2xx status. Otherwise we retry after 1 min, 5 min, 30 min, 2 hours, 6 hours, 12 hours, 24 hours; after that the delivery is marked failed in your log (where you can resend it). A delivery can arrive more than once: deduplicate on id. Redirects are not followed.

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

Good to know