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.

Read-only Bearer tokens 600–3000 req/hourv1

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

  1. Sign in to the dashboard and open Instellingen → API-tokens (admin role required, and your shop must be fully set up).
  2. Create a token, give it a name you will recognize later, and copy the ctk_… value — it is shown exactly once.
  3. Call an endpoint with the token in the Authorization header:
curl -H "Authorization: Bearer ctk_YOUR_TOKEN" \
  https://captainticket.nl/api/v1/events

A 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_TOKEN

A 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.

ParameterDescriptionDefault
readThe shop, events, live availability and payment methods. Every token has it.—
orders:readOrders, order lines and refunds, including the buyer's name, e-mail and phone. Includes personal data.—
tickets:readTickets per event: status, holder name, seat and check-in state. Never the QR code. Includes personal data.—
checkins:readDoor scans and the checked-in counters per event and time slot.—
stats:readTickets sold and revenue per event and per day.—
guestlist:writeAdd guests to an event's guest list (free tickets, mailed when an address is given).—
orders:writeResend a paid order's ticket e-mail to the address on the order.—
discounts:writeList, 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." }
ParameterDescriptionDefault
400 invalid_requestMalformed parameters (for example a non-numeric event id).—
401 unauthorizedMissing, invalid, expired or revoked token.—
403 forbiddenThe token is valid but lacks the scope this endpoint needs.—
404 not_foundThe resource does not exist — or belongs to another shop; the API does not distinguish.—
409 conflictA write that cannot be done as asked (no places left, a code that exists), or an Idempotency-Key clash.—
429 rate_limitedToo many requests with this token; see Retry-After.—
503 service_unavailableMaintenance: 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: 1500 is €15.00. Never parse it as a float.
  • Null means unlimited: a null capacity 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 hasMore instead of a total; raise offset by limit until 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).

ParameterDescriptionDefault
limitPage size, 1–100.50
offsetPage 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.

ParameterDescriptionDefault
statusComma-separated statuses, for example paid,refunded. An unknown value is a 400.—
eventIdOnly this event's orders.—
since / untilISO 8601 bounds on the purchase moment. For a sync, keep the last purchasedAt you stored and pass it as since.—
limitPage size, 1–100.50
offsetPage 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.

ParameterDescriptionDefault
ticketTypeIdOnly tickets of this ticket type.—
checkedIntrue for tickets with a valid scan, false for the rest.—
limitPage size, 1–500.100
offsetPage 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.

ParameterDescriptionDefault
timeSlotIdOnly scans for this time slot.—
sinceISO 8601: scans at or after this moment.—
includeRefusedAlso list refused scans.false
limitPage size, 1–500.100
offsetPage 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.

ParameterDescriptionDefault
fromFirst day, YYYY-MM-DD.29 days before to
toLast day (inclusive), YYYY-MM-DD.today
eventIdOnly 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.

ParameterDescriptionDefault
firstNameRequired.—
lastNameOptional.""
emailWith an address the guest gets the ticket mail.""
tickets1–50 lines of { ticketTypeId, count }, each tier once.—
countsAsSoldtrue: 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.

ParameterDescriptionDefault
code3–50 letters, digits, - or _. Unique per shop.—
nameOptional label for the dashboard.—
kindpercent, fixed_cents or free_product.—
percentkind percent: 0–100, at most two decimals.—
amountCentskind fixed_cents: integer cents.—
freeTicketTypeId / freeProductIdkind free_product: exactly one.—
appliesToorder_total, or scoped_lines (only the lines the scope names).order_total
minOrderCentsMinimum order value.0
maxUses0 = unlimited.0
validFrom / validUntilISO 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.

EventDescription
order.paidAn order was paid (or completed for free) and its tickets were issued.
order.refundedA refund on an order was confirmed by the payment provider, full or partial.
order.chargebackThe buyer reversed the payment through their bank (chargeback).
order.cancelledA guest-list order was removed, or an order was cancelled by CaptainTicket support.
ticket.checked_inA ticket was admitted at the door, by camera or manual check-in.
ticket.swappedA ticket was resold through TicketSwap and re-issued to the new holder.
event.sold_outEvery 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 ofDescription
order.paidorderId, eventId (null for a shop-only order), status, totalCents, ticketCount
order.refundedorderId, refundId, amountCents, fullyRefunded
order.chargebackorderId, totalCents
order.cancelledorderId, previousStatus, and eventId for a removed guest
ticket.checked_inticketId, eventId, ticketTypeId, timeSlotId, manual, scannedAt
ticket.swappedswapId, eventId, oldTicketId, oldOrderId, newTicketId, newOrderId
event.sold_outeventId
pingmessage — 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/mcp and 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.
ToolDescription
get_shopThe shop (read)
list_eventsAll events, incl. hidden ones (read)
get_eventOne event with tiers and availability (read)
list_payment_methodsPayment methods (read)
event_statsSales and attendance of one event (stats:read)
sales_by_daySales per Amsterdam day (stats:read)
door_countsDoor counters of one event (checkins:read)
list_orders, find_orders, get_orderOrders, search by number, name or e-mail (orders:read)
list_tickets, get_ticketTickets (tickets:read)
add_guestAdd a guest to the guest list (guestlist:write)
resend_ticket_emailResend an order's ticket mail (orders:write)
list_discount_codes, create_discount_code, set_discount_code_activeDiscount 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:

openapi.json

Point your client generator, Postman or CI contract test at it.

Download

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}/resend and /discounts, the Idempotency-Key header, the conflict and service_unavailable errors, 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.swapped and event.sold_out.
  • v1.1 (2026-11-01) — token scopes; /orders, /orders/{orderId}, /events/{eventId}/tickets, /tickets/{ticketId}, /events/{eventId}/checkins, /events/{eventId}/stats and /stats/sales; the forbidden error; 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.