CaptainTicket API
Read the live state of your ticket shop
A token-authenticated, read-only REST API: your events with live availability, ticket shop URLs and payment methods, and — when you allow it per token — your orders, tickets, door check-ins and sales figures. Built for the website, CRM, accounting sync or LED wall that needs your shop's data without scraping or exports.
Overview
A new token reads what your ticket shop already publishes: the same events, prices and availability a visitor sees on /t/<slug>, and the payment methods your shop is configured to offer. Orders, tickets, check-ins and statistics are only readable with a token you gave the matching scope; two of those scopes include your buyers' personal data. Three more scopes allow a few safe changes: adding guests, resending the ticket mail and managing discount codes. The API never refunds, pays out, or changes payment settings or members.
The base URL is your CaptainTicket site (https://captainticket.nl in production). All endpoints are under /api/v1 and respond with JSON.
Quickstart
- Sign in to the dashboard and open Instellingen → API-tokens (admin role required, and your shop must be fully set up).
- Create a token, give it a name you will recognize later, and copy the
ctk_…value — it is shown exactly once. - Call an endpoint with the token in the Authorization header:
curl -H "Authorization: Bearer ctk_YOUR_TOKEN" \
https://captainticket.nl/api/v1/eventsA shop with one upcoming festival will get something like:
{
"events": [
{
"id": 482,
"name": "Zomersessie 2026",
"startsAt": "2026-08-15T18:00:00.000Z",
"endsAt": "2026-08-15T23:00:00.000Z",
"onSale": true,
"soldOut": false,
"url": "https://captainticket.nl/t/vereniging-voorbeeld/e/482",
"location": { "name": "Sporthal De Sluis", "address": "Sluisstraat 1, Voorburg" }
}
],
"total": 1,
"limit": 50,
"offset": 0
}Authentication
All endpoints require an API token. Send it as a bearer token:
Authorization: Bearer ctk_YOUR_TOKENA token belongs to exactly one shop and reads that shop only — it cannot name, list or read another shop. What it may read within the shop is set by its scopes. Tokens can carry an expiry date, and can be revoked at any time from the dashboard; both take effect on the very next request.
Missing, invalid, expired and revoked tokens all answer the same 401: the API never confirms whether a token ever existed. Treat the token like a password; it is only shown once at creation.
Scopes
You choose a token's scopes when you create it; they cannot be changed afterwards (create a new token instead). Calling an endpoint the token has no scope for answers 403 forbidden, naming the scope it needs.
| Parameter | Description | Default |
|---|---|---|
| read | The shop, events, live availability and payment methods. Every token has it. | — |
| orders:read | Orders, order lines and refunds, including the buyer's name, e-mail and phone. Includes personal data. | — |
| tickets:read | Tickets per event: status, holder name, seat and check-in state. Never the QR code. Includes personal data. | — |
| checkins:read | Door scans and the checked-in counters per event and time slot. | — |
| stats:read | Tickets sold and revenue per event and per day. | — |
| guestlist:write | Add guests to an event's guest list (free tickets, mailed when an address is given). | — |
| orders:write | Resend a paid order's ticket e-mail to the address on the order. | — |
| discounts:write | List, create, activate and deactivate discount codes. | — |
The scopes with personal data hand your buyers' names and contact details to whatever system holds the token. Give them only to integrations that need them, and revoke a token the moment it is no longer used. The QR code of a ticket and the buyer's ticket link are never returned by any scope: they would let whoever reads the integration's database walk in.
Rate limits
Each token may make 600 requests per rolling hour — about ten per minute sustained, which is far more than a display or website needs. A token with the orders:read or tickets:read scope may make 3000, because a sync job pages through every order of a busy event. When the limit is exceeded the API answers 429 with a Retry-After: 60 header.
Polling sold-out status once a minute per event is well within the limit. If you need more, contact us before working around it.
Errors
Every failure has the same JSON shape: a stable error code to branch on and a human-readable message:
{ "error": "not_found", "message": "Event not found." }| Parameter | Description | Default |
|---|---|---|
| 400 invalid_request | Malformed parameters (for example a non-numeric event id). | — |
| 401 unauthorized | Missing, invalid, expired or revoked token. | — |
| 403 forbidden | The token is valid but lacks the scope this endpoint needs. | — |
| 404 not_found | The resource does not exist — or belongs to another shop; the API does not distinguish. | — |
| 409 conflict | A write that cannot be done as asked (no places left, a code that exists), or an Idempotency-Key clash. | — |
| 429 rate_limited | Too many requests with this token; see Retry-After. | — |
| 503 service_unavailable | Maintenance: writes are paused; see Retry-After. | — |
Conventions
- Timestamps are ISO 8601 strings. Event times are Europe/Amsterdam — that is the time at the door, regardless of your server's timezone.
- Money is integer cents:
priceCents: 1500is €15.00. Never parse it as a float. - Null means unlimited: a
nullcapacity or availability is a tier without a ceiling. - URLs are absolute. Dutch (
nl) is each shop's canonical locale; a shop may enable more, and per-locale URLs are included where relevant. - Paging: the order, ticket and check-in lists answer
hasMoreinstead of a total; raiseoffsetbylimituntil it is false. - Caching: responses are
no-store— availability is live. Do not cache payloads longer than your polling interval.
The shop
GET/api/v1/shop#
Your shop's public identity: name, slug, enabled locales and the absolute ticket shop URL per locale. testMode is true while the platform has your shop in Pay.nl test mode — worth surfacing so nobody is confused about money not moving.
Example response
{
"id": "259",
"slug": "vereniging-voorbeeld",
"name": "Vereniging Voorbeeld",
"urls": {
"nl": "https://captainticket.nl/t/vereniging-voorbeeld",
"en": "https://captainticket.nl/t/vereniging-voorbeeld/en"
},
"locales": ["nl", "en"],
"testMode": false
}Events overview
GET/api/v1/events#
The shop's public events — visible, not archived, not an unpublished draft — each with a live soldOut flag computed the same moment the public shop page computes it (paid tickets plus unexpired reservations count as taken).
| Parameter | Description | Default |
|---|---|---|
| limit | Page size, 1–100. | 50 |
| offset | Page offset; page through until offset + length reaches total. | 0 |
Events are ordered by startsAt (undated events last). See the quickstart for a full example response.
Event details
GET/api/v1/events/{eventId}#
One event in full: description (HTML), sale window, location, per-tier prices and live availability, time slots, and the public URL per enabled locale. The id comes from the list endpoint.
Example response (abridged)
{
"id": 482,
"name": "Zomersessie 2026",
"description": "<p>De jaarlijkse zomersessie…</p>",
"startsAt": "2026-08-15T18:00:00.000Z",
"endsAt": "2026-08-15T23:00:00.000Z",
"saleStartsAt": "2026-06-01T00:00:00.000Z",
"onSale": true,
"soldOut": false,
"queue": false,
"seated": false,
"url": "https://captainticket.nl/t/vereniging-voorbeeld/e/482",
"urls": { "nl": "https://captainticket.nl/t/vereniging-voorbeeld/e/482" },
"location": {
"name": "Sporthal De Sluis",
"address": "Sluisstraat 1, Voorburg",
"latitude": 52.077,
"longitude": 4.359
},
"presale": { "enabled": false, "startsAt": null },
"tiers": [
{
"id": 1201,
"name": "Normaal",
"description": null,
"priceCents": 1500,
"vatRate": "low",
"capacity": 200,
"available": 63,
"soldOut": false,
"onSale": true,
"waitingForTierId": null,
"seated": false,
"freeSeats": null,
"minimumOrderCount": 1,
"maximumOrderCount": 6,
"increment": 1,
"timeSlots": []
}
],
"timeSlots": []
}vatRate is a semantic category (free, zero, low = 9%, high = 21%). available honors shared time-slot pools — it is the number a buyer can actually still reserve, which can be lower than capacity. waitingForTierId is set while a tier waits for another tier to sell out (for example a regular tier that opens after the early bird); a waiting tier cannot be bought yet. A tier with seated: true sells seats on a seat map; its freeSeats counts the free seats of its price category and is already included in available and soldOut. The events overview does not count seats, so a seated event can read as available there until its detail says sold out.
Payment methods
GET/api/v1/payment-methods#
The payment methods your shop is configured to offer: your allowlist intersected with the methods CaptainTicket has enabled platform-wide (iDEAL only until you pick more). Vouchers (gift cards) are typed separately so you can group them in a UI.
Example response
{
"methods": [
{ "id": 1, "name": "iDEAL", "type": "standard" },
{ "id": 706, "name": "Podium Cadeaukaart", "type": "voucher" }
]
}This reads your configuration — it makes no live call to the payment provider. The exact set a buyer can pick is re-resolved at checkout, so a method can disappear from a real payment if the provider stops offering it. Use this endpoint for display, not for payment validation.
Orders
GET/api/v1/orders#
Scope orders:read. Your orders with the buyer, oldest purchase first. Without status the list holds every real order: paid, free, guest list, imported, swapped, cancelled and refund-shaped. Carts and failed payments only appear when you ask for their status explicitly.
| Parameter | Description | Default |
|---|---|---|
| status | Comma-separated statuses, for example paid,refunded. An unknown value is a 400. | — |
| eventId | Only this event's orders. | — |
| since / until | ISO 8601 bounds on the purchase moment. For a sync, keep the last purchasedAt you stored and pass it as since. | — |
| limit | Page size, 1–100. | 50 |
| offset | Page offset. | 0 |
Example response (abridged)
{
"orders": [
{
"id": 950111,
"eventId": 482,
"eventName": "Zomersessie 2026",
"status": "paid",
"paid": true,
"purchasedAt": "2026-07-02T19:14:03.000Z",
"locale": "nl",
"ticketCount": 2,
"totals": {
"totalCents": 3150, "ticketsCents": 3000, "serviceCostsCents": 150,
"productsCents": 0, "donationCents": 0, "shippingCents": 0,
"paymentCostsCents": 0, "discountCents": 0
},
"discountCode": null,
"channel": "online",
"customer": {
"firstName": "Sanne", "lastName": "Jansen", "email": "sanne@example.nl",
"phone": null, "address": null, "zipcode": null, "city": null, "country": null
}
}
],
"hasMore": false,
"limit": 50,
"offset": 0
}paid says the order counts as completed; a refunded or charged-back order keeps paid: true with its own status. channel is online, door (sold at the door), guestlist or internal (a TicketSwap resale or an import). An order without a real e-mail address (a name-only guest) has email: null.
One order
GET/api/v1/orders/{orderId}#
Scope orders:read. The order as in the list, plus its lines (tickets, merchandise and vouchers, with unit price, service costs and discount), its refunds (with confirmed once the payment provider confirmed them) and the ticketIds it holds.
An event's tickets
GET/api/v1/events/{eventId}/tickets#
Scope tickets:read. Every ticket of the event by id, also for an archived or hidden event of your shop.
| Parameter | Description | Default |
|---|---|---|
| ticketTypeId | Only tickets of this ticket type. | — |
| checkedIn | true for tickets with a valid scan, false for the rest. | — |
| limit | Page size, 1–500. | 100 |
| offset | Page offset. | 0 |
Example ticket
{
"id": 3120044,
"orderId": 950111,
"eventId": 482,
"ticketTypeId": 1201,
"ticketTypeName": "Normaal",
"status": "valid",
"holderName": "Sanne Jansen",
"seat": null,
"checkedIn": true,
"firstCheckInAt": "2026-08-15T18:21:40.000Z",
"createdAt": "2026-07-02T19:14:05.000Z"
}status is one value: valid (the door admits it), invalidated, refunded, swapped (resold through TicketSwap; the buyer's new ticket is another id) or unpaid. holderName is set once the ticket was put on a name.
One ticket
GET/api/v1/tickets/{ticketId}#
Scope tickets:read. The same ticket object as in the list.
Check-ins
GET/api/v1/events/{eventId}/checkins#
Scope checkins:read. The door counters and a page of scans, oldest first. Poll it with since for a live counter on a screen. Refused scans are left out unless you pass includeRefused=true; who scanned is never returned.
| Parameter | Description | Default |
|---|---|---|
| timeSlotId | Only scans for this time slot. | — |
| since | ISO 8601: scans at or after this moment. | — |
| includeRefused | Also list refused scans. | false |
| limit | Page size, 1–500. | 100 |
| offset | Page offset. | 0 |
Example response (abridged)
{
"summary": {
"checkedIn": 412,
"admissible": 640,
"timeSlots": [{ "id": 77, "name": "Middag", "checkedIn": 230 }]
},
"checkins": [
{
"id": 5501234, "ticketId": 3120044, "ticketTypeId": 1201, "timeSlotId": 77,
"valid": true, "manual": false, "scannedAt": "2026-08-15T18:21:40.000Z"
}
],
"hasMore": true,
"limit": 100,
"offset": 0
}checkedIn counts distinct tickets (a ticket scanned into two time slots counts once); admissible is every ticket the door would let in.
Event statistics
GET/api/v1/events/{eventId}/stats#
Scope stats:read. The numbers your dashboard shows: tickets sold, on the guest list, refunded, swapped and charged back, tickets checked in, revenue (tickets after discounts, service costs, goods, confirmed refunds) and paid orders — for the event and per ticket type.
Sales per day
GET/api/v1/stats/sales#
Scope stats:read. Orders, tickets and revenue per Europe/Amsterdam day, for the whole shop or one event. Paid orders only, without the guest list and resales; days without sales are left out.
| Parameter | Description | Default |
|---|---|---|
| from | First day, YYYY-MM-DD. | 29 days before to |
| to | Last day (inclusive), YYYY-MM-DD. | today |
| eventId | Only this event's sales. | — |
At most 366 days per request.
Writes & idempotency
Writes need their own scope (guestlist:write, orders:write, discounts:write) and take a JSON body (Content-Type: application/json, at most 64 KB). Unknown fields are refused rather than ignored, so a typo never silently does less than you meant. Every write runs through the same rules as the dashboard.
Send an Idempotency-Key header (any unique string, a UUID is fine) to make a retry safe: the same key with the same request within 24 hours gets the first answer back, marked Idempotent-Replayed: true, instead of a second guest or a second mail. The same key on a different request is a 409. Rate limits and maintenance answers are not stored, so a retry after them runs again.
curl -X POST https://captainticket.nl/api/v1/events/482/guestlist -H "Authorization: Bearer ctk_YOUR_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: 6f1c2a8e-3b0d-4e7a-9a51-2d4c8b7e1f30" -d '{"firstName":"Sam","lastName":"de Vries","email":"sam@example.nl",
"tickets":[{"ticketTypeId":1201,"count":2}]}'Add a guest
POST/api/v1/events/{eventId}/guestlist#
Scope guestlist:write. Creates a free guest-list order, the same as the dashboard's Gastenlijst tab, and answers 201 with orderId, ticketIds and emailQueued. At most 500 guests per shop per hour.
| Parameter | Description | Default |
|---|---|---|
| firstName | Required. | — |
| lastName | Optional. | "" |
| With an address the guest gets the ticket mail. | "" | |
| tickets | 1–50 lines of { ticketTypeId, count }, each tier once. | — |
| countsAsSold | true: the places count against capacity (a full event answers 409). false: capacity is left alone. | true |
Resend the ticket mail
POST/api/v1/orders/{orderId}/resend#
Scope orders:write. Sends the ordinary ticket mail (a link to the tickets) to the order's own address again. Only paid orders with a real address; the address cannot be changed through the API. An optional message (up to 1000 characters) shows under the mail's heading. At most 200 mails per shop per hour.
Discount codes
GET/api/v1/discounts#
POST/api/v1/discounts#
PATCH/api/v1/discounts/{discountId}#
Scope discounts:write. List the shop's codes (newest first, with used), create one, or switch one on or off with { "active": false }. Other changes and deleting stay in the dashboard. A code that already exists answers 409.
| Parameter | Description | Default |
|---|---|---|
| code | 3–50 letters, digits, - or _. Unique per shop. | — |
| name | Optional label for the dashboard. | — |
| kind | percent, fixed_cents or free_product. | — |
| percent | kind percent: 0–100, at most two decimals. | — |
| amountCents | kind fixed_cents: integer cents. | — |
| freeTicketTypeId / freeProductId | kind free_product: exactly one. | — |
| appliesTo | order_total, or scoped_lines (only the lines the scope names). | order_total |
| minOrderCents | Minimum order value. | 0 |
| maxUses | 0 = unlimited. | 0 |
| validFrom / validUntil | ISO 8601 with an offset, e.g. 2026-12-01T00:00:00+01:00. | — |
| scope | { eventIds, ticketTypeIds, productIds }; empty = the whole shop. Ids must be this shop's. | — |
Webhooks
Instead of polling, let CaptainTicket call you. Add an HTTPS address under Settings → Webhooks (shop admins, up to five per shop), choose the events, and copy the signing secret (whsec_…, shown once). Every event is sent as a POST with a JSON body.
| Event | Description |
|---|---|
| order.paid | An order was paid (or completed for free) and its tickets were issued. |
| order.refunded | A refund on an order was confirmed by the payment provider, full or partial. |
| order.chargeback | The buyer reversed the payment through their bank (chargeback). |
| order.cancelled | A guest-list order was removed, or an order was cancelled by CaptainTicket support. |
| ticket.checked_in | A ticket was admitted at the door, by camera or manual check-in. |
| ticket.swapped | A ticket was resold through TicketSwap and re-issued to the new holder. |
| event.sold_out | Every ticket of an event is sold. |
The body is a small envelope. data carries ids and a few numbers — never a name or an e-mail address: read the rest through the API with your own token (for example GET /orders/{orderId}).
Body
{
"id": "evt_0f8fad5bd9cb469fa16570867728950e",
"type": "order.paid",
"createdAt": "2026-11-01T10:00:00.000Z",
"shopId": "259",
"data": {
"orderId": 950111,
"eventId": 1235,
"status": "paid",
"totalCents": 4250,
"ticketCount": 2
}
}| data of | Description |
|---|---|
| order.paid | orderId, eventId (null for a shop-only order), status, totalCents, ticketCount |
| order.refunded | orderId, refundId, amountCents, fullyRefunded |
| order.chargeback | orderId, totalCents |
| order.cancelled | orderId, previousStatus, and eventId for a removed guest |
| ticket.checked_in | ticketId, eventId, ticketTypeId, timeSlotId, manual, scannedAt |
| ticket.swapped | swapId, eventId, oldTicketId, oldOrderId, newTicketId, newOrderId |
| event.sold_out | eventId |
| ping | message — the dashboard's “Test versturen” button |
Each request carries X-CaptainTicket-Event (the type), X-CaptainTicket-Delivery (the event id, the same on every retry and every endpoint — use it to ignore duplicates), X-CaptainTicket-Attempt and X-CaptainTicket-Signature: t=<unix seconds>,v1=<hex>. The signature is the HMAC-SHA256 of t + "." + body with your secret. Verify it over the RAW body, before parsing, and refuse a timestamp more than five minutes off.
Verify (Node.js)
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === 32 && timingSafeEqual(given, Buffer.from(expected, "hex"));
}Answer with any 2xx within 10 seconds; do the work afterwards. Anything else — a timeout, an error status, a redirect — is retried after 1, 5 and 15 minutes, then 1, 3, 6 and 12 hours, for up to 24 hours. Order is not guaranteed. When an event is given up and nothing reached the endpoint since, the endpoint is switched off and the shop is notified; switching it back on sends what was still waiting. Addresses must be public HTTPS on port 443.
MCP server
The same read-only data is available to AI assistants through the Model Context Protocol, at /api/v1/mcp (Streamable HTTP, stateless JSON: POST only). Organizers add it in claude.ai or Claude Desktop as a custom connector; the Settings → Claude page shows the link and every connection.
Two ways to authenticate:
- OAuth 2.1 (what Claude uses): dynamic client registration, PKCE (S256) and refresh tokens. The authorization server's metadata is at
/.well-known/oauth-authorization-server/api/v1/mcpand the resource's at/.well-known/oauth-protected-resource/api/v1/mcp. On the consent page the member picks one shop and whether orders and tickets may be read; the grant acts as that member, whose membership is checked on every call. Redirect URIs must be on claude.ai, claude.com or loopback. - An API token, as
Authorization: Bearer ctk_…: tools follow the token's scopes and calls count against its hourly limit.
| Tool | Description |
|---|---|
| get_shop | The shop (read) |
| list_events | All events, incl. hidden ones (read) |
| get_event | One event with tiers and availability (read) |
| list_payment_methods | Payment methods (read) |
| event_stats | Sales and attendance of one event (stats:read) |
| sales_by_day | Sales per Amsterdam day (stats:read) |
| door_counts | Door counters of one event (checkins:read) |
| list_orders, find_orders, get_order | Orders, search by number, name or e-mail (orders:read) |
| list_tickets, get_ticket | Tickets (tickets:read) |
| add_guest | Add a guest to the guest list (guestlist:write) |
| resend_ticket_email | Resend an order's ticket mail (orders:write) |
| list_discount_codes, create_discount_code, set_discount_code_active | Discount codes (discounts:write) |
Tools a connection has no scope for are not listed. Answers are JSON in the API's own shapes. The write tools appear only when the member ticked “Wijzigingen” on the consent page and is a manager or above in the shop (checked on every call), or when the API token has the write scope.
OpenAPI & tooling
The complete contract is published as an OpenAPI 3.1 document, generated from the same schemas that shape the responses — it cannot drift from the implementation:
AI agents: this documentation, the spec and /llms.txt describe the same API.
Changelog
- v1.4 (2026-11-01) — safe writes:
POST /events/{eventId}/guestlist,POST /orders/{orderId}/resendand/discounts, theIdempotency-Keyheader, theconflictandservice_unavailableerrors, and MCP write tools. - v1.3 (2026-11-01) — the MCP server at
/api/v1/mcp, with OAuth or an API token. - v1.2 (2026-11-01) — signed webhooks for
order.paid,order.refunded,order.chargeback,order.cancelled,ticket.checked_in,ticket.swappedandevent.sold_out. - v1.1 (2026-11-01) — token scopes;
/orders,/orders/{orderId},/events/{eventId}/tickets,/tickets/{ticketId},/events/{eventId}/checkins,/events/{eventId}/statsand/stats/sales; theforbiddenerror; 3000 requests per hour for tokens with an order or ticket scope. - v1 (2026-10-03) — read-only API with
/shop,/events,/events/{eventId}and/payment-methods; API tokens with expiry and revocation.
Questions or missing data for your integration? Contact us via our support page.