Partner API v1
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
- 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.
- Connect your Stripe account under Stripe. You remain the seller on the payment page and receive the money through Stripe.
- 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. - 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).
- 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.
- Optional: set a webhook URL so your website hears immediately when an order is paid, refunded or expired.
- 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
}
]
}
]
}| Field | Meaning |
|---|---|
description | Plain text as the organiser typed it (line breaks as \n). Not HTML: escape it when you put it into HTML. |
starts_at / ends_at | ISO 8601 with time-zone offset (Europe/Amsterdam). ends_at may be null. |
image_url | Full 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_status | on_sale · not_started · sold_out · ended · unavailable |
ticket_types[].description | Short description of the ticket type (plain text, at most 300 characters), or null. |
price_cents | Price per ticket including VAT, what the buyer pays. |
buyer_fee_cents | Service fee for the buyer. Always 0: the buyer pays exactly the ticket price. |
available | Still on sale now. Running (unpaid) reservations are already deducted. |
min_per_order / max_per_order | Minimum (always 1) and maximum quantity per order. |
sales_start / sales_end | Sales 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_status | on_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.
| Field | Required | Meaning |
|---|---|---|
event_id | yes | Id from GET /events. |
items[] | yes | 1–20 lines { ticket_type_id, quantity }; each ticket type at most once. |
customer.name | yes | 2–100 characters; printed on the tickets. |
customer.email | yes | Where we send the tickets. |
customer.ip | no, recommended | Buyer's IP address. Lets us limit open reservations per buyer instead of per server. |
locale | no | nl (default) or en: language of the payment page. |
success_url | yes | https URL on an allowed origin of your key. May contain {ORDER_ID} which we fill in. |
cancel_url | yes | Where the buyer goes when cancelling the payment. Same rules. |
metadata | no | Up 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"
}
}| HTTP | code | Meaning |
|---|---|---|
| 400 | duplicate_ticket_type | A ticket_type_id appears twice in items. |
| 400 | idempotency_key_missing | Idempotency-Key header missing or invalid. |
| 400 | invalid_quantity | quantity is not a whole number ≥ 1. |
| 400 | invalid_request | Invalid JSON, missing or unknown field (e.g. a price). |
| 400 | invalid_return_url | success_url/cancel_url not on an allowed origin of the key (see `field`). |
| 400 | max_per_order | More than max_per_order for a ticket type. |
| 400 | no_items | No tickets chosen. |
| 400 | ticket_type_not_found | ticket_type_id does not belong to this event. |
| 401 | unauthorized | Missing, invalid or revoked API key. |
| 404 | event_not_found | Event does not exist, is not published or belongs to another organiser. |
| 404 | not_found | Unknown endpoint or order. |
| 409 | idempotency_in_progress | A request with this key is still running; retry shortly. |
| 409 | sales_closed | The event has ended or sales are (temporarily) closed. |
| 409 | sold_out | Not enough tickets left (ticket_type_id in the error). |
| 409 | ticket_sales_closed | The sales period of this ticket type has not started yet or has ended (ticket_type_id, reason and possibly sales_start in the error). |
| 409 | too_many_open_orders | Too 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`). |
| 422 | idempotency_key_reused | Same Idempotency-Key with a different body. |
| 429 | rate_limited | Too many requests; wait the seconds in Retry-After. |
| 500 | internal_error | Error on our side; retrying with the same Idempotency-Key is safe. |
| 503 | payment_unavailable | Payment is temporarily unavailable; the reservation was released. |
Rate limits
| What | Limit |
|---|---|
| GET requests per key | 300 per minute |
| GET requests per IP | 600 per minute |
| POST /checkout per key | 30 per minute |
| POST /checkout per IP | 60 per minute |
| POST /checkout per customer.ip | 10 per 15 minutes |
| Failed authentication per IP | 30 per 15 minutes |
| Unpaid orders per e-mail address | 3 |
| Unpaid orders per customer.ip | 5 |
| Unpaid orders per key | 100 |
| Reserved tickets (in unpaid orders) per key | 200 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
- Keep the API key and webhook secret on your server only. Never call the API from the browser.
- You are the seller on the Stripe payment page; the buyer gets the regular TicketsHere ticket e-mail with QR codes and is scanned at the door with TicketsHere.
- Refunds work as always through your organiser portal; then order.refunded follows and the tickets become invalid.
- Amounts are whole cents (integers). Times are ISO 8601 with time zone.
- v1 stays stable: we only ever add fields. Ignore fields you do not know.
- Questions? E-mail support@ticketshere.nl.