API & webhooks

Voor ontwikkelaars biedt Cleartix een REST API (Studio en Pro) en webhooks (Pro), zodat je ticketing aan je eigen systemen kunt koppelen. Liever met je evenementen praten dan programmeren? Koppel een AI-assistent via MCP — dat werkt op elk plan.

API-sleutels

Maak API-sleutels aan onder Settings om de Cleartix REST API te gebruiken. Met een sleutel kun je je data uitlezen vanuit je eigen code of tools — je bestellingen, deelnemers en verkoopstatistieken per evenement (verkochte tickets, check-ins en omzet, uitgesplitst per tickettype, zonder deelnemersgegevens) — om dashboards te voeden, een CRM te synchroniseren of een eigen rapport te bouwen. De API kan je evenementen, eventtemplates, tickettypes, datums, toegangscodes, add-ons, capaciteitspools, gates, event-e-mails en locaties ook aanmaken en beheren, zodat een formulier op je eigen website, een intern planningstool of een AI-assistent evenementen kan opzetten zonder dat iemand door het dashboard klikt.

Elke sleutel krijgt eigen scopes, zodat je een integratie precies de toegang geeft die ze nodig heeft — bijvoorbeeld alleen de geaggregeerde verkoopcijfers:

Je kunt de rechten van een sleutel op dezelfde pagina altijd aanpassen (Rechten aanpassen); de wijziging geldt meteen voor elke integratie die de sleutel gebruikt, zonder een nieuwe sleutel uit te geven.

Webhooks

In plaats van de API te pollen, registreer je webhooks zodat Cleartix je endpoint verwittigt wanneer er iets gebeurt, bijvoorbeeld:

• Een verkocht ticket
• Een ingecheckte deelnemer
• Een terugbetaalde bestelling
• Een product met lage voorraad

Wanneer de gebeurtenis zich voordoet, stuurt Cleartix een verzoek naar je URL. Leveringen zijn ondertekend, zodat je kunt verifiëren dat ze echt van Cleartix komen, en ze worden opnieuw geprobeerd als je endpoint tijdelijk onbereikbaar is — zo gaat een korte storing geen gebeurtenis verloren.

Webhook-payloads

Elke webhook is een HTTP POST waarvan de JSON-body steeds dezelfde envelope gebruikt — alleen event en data verschillen:

{
  "id": "evt_3f9a2b7c1d4e5f60",
  "event": "ticket.sold",
  "created_at": "2026-06-12T14:05:00.000Z",
  "organization_id": "org_abc123",
  "data": {}
}

Bij elk verzoek horen twee headers:

• X-ClearTix-Signature — sha256= gevolgd door de HMAC-SHA256 van de ruwe request-body, met de ondertekeningssleutel van je endpoint. Verifieer dit voor je een payload vertrouwt.
• X-ClearTix-Event — het event-type, bv. ticket.sold.

Het data-object hangt af van het event. Elk event hieronder toont een voorbeeld-data en het bijbehorende JSON Schema.

ticket.sold — ticket gekocht en betaald

Verstuurd wanneer er tickets worden uitgegeven op een betaalde bestelling: een online betaling, een gratis of POS-bestelling, gasttickets, een inwisseling met een pass, of een overschrijving, POS-betaling of factuur die je als betaald boekte. totalAmount is "0" voor bestellingen van € 0.

{ "orderId": "ord_9f8e7d6c", "ticketCount": 2, "totalAmount": "50.00" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.sold · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "ticketCount", "totalAmount"],
  "properties": {
    "orderId": { "type": "string" },
    "ticketCount": { "type": "integer", "minimum": 0 },
    "totalAmount": { "type": "string", "description": "Decimal total as a string, e.g. \"50.00\" (\"0\" for free orders)" }
  }
}

ticket.checked_in — deelnemer ingecheckt op event

Verstuurd bij elke check-in: via de scanner-app (ook scans die na een onderbreking van de verbinding later gesynchroniseerd worden), handmatig inchecken in het dashboard, en check-ins via de API of een AI-assistent.

{ "ticketId": "tkt_1a2b3c4d", "eventId": "ev_5e6f7a8b", "checkedInAt": "2026-06-12T14:05:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.checked_in · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["ticketId", "eventId", "checkedInAt"],
  "properties": {
    "ticketId": { "type": "string" },
    "eventId": { "type": "string" },
    "checkedInAt": { "type": "string", "format": "date-time" }
  }
}

ticket.refunded — ticket terugbetaald

Verstuurd bij elke terugbetaling in Cleartix — een losse terugbetaling vanuit het dashboard, de API of een AI-assistent, en elke bestelling die automatisch terugbetaald wordt wanneer je een evenement annuleert.

{ "orderId": "ord_9f8e7d6c", "refundRef": "re_4d3c2b1a", "refundAmount": 2500 }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.refunded · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "refundRef", "refundAmount"],
  "properties": {
    "orderId": { "type": "string" },
    "refundRef": { "type": "string", "description": "Provider refund reference" },
    "refundAmount": { "type": "integer", "description": "Refunded amount in cents" }
  }
}

order.created — order bevestigd (inclusief gratis)

Verstuurd wanneer een bestelling betaald wordt, samen met ticket.sold (een passaankoop stuurt enkel order.created). Ook een betaalde factuur wordt gemeld met status: "paid".

{ "orderId": "ord_9f8e7d6c", "kind": "tickets", "status": "paid" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "order.created · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "status"],
  "properties": {
    "orderId": { "type": "string" },
    "kind": { "type": "string", "enum": ["tickets", "pass", "shop"] },
    "status": { "type": "string", "enum": ["paid"] }
  }
}

order.shipped — shopbestelling verzonden

Verstuurd wanneer je een bestelling als verzonden markeert (dashboard, API of AI-assistent), met de vervoerder en de trackingcode als die ingevuld werd.

{ "orderId": "ord_9f8e7d6c", "carrier": "bpost", "trackingCode": "323212345678901234", "shippedAt": "2026-06-12T14:05:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "order.shipped · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "carrier", "trackingCode", "shippedAt"],
  "properties": {
    "orderId": { "type": "string" },
    "carrier": { "type": "string", "enum": ["bpost", "postnl", "dhl", "dpd", "gls", "ups", "other"] },
    "trackingCode": { "type": ["string", "null"] },
    "shippedAt": { "type": "string", "format": "date-time" }
  }
}

order.refunded — producten of verzending terugbetaald

Verstuurd bij een terugbetaling van productlijnen of de verzendlijn (shopbestellingen en verzonden extra's), met elke terugbetaalde lijn. Ticketterugbetalingen blijven ticket.refunded sturen.

{ "orderId": "ord_9f8e7d6c", "refundRef": "re_1a2b3c", "amountCents": 3095, "lines": [{ "orderAddOnId": "oao_1", "productId": "prod_1", "shipping": false, "quantity": 1, "amountCents": 2500, "restocked": true }, { "orderAddOnId": null, "productId": null, "shipping": true, "quantity": 1, "amountCents": 595, "restocked": false }] }

product.stock_low — een product is bijna uitverkocht

Wordt één keer verstuurd wanneer een bestelling de beschikbare voorraad van een fysiek product op 5 stuks of minder brengt (en pas opnieuw nadat de voorraad weer boven de drempel kwam en er opnieuw onder zakte). Gebruik het om merchandise bij te bestellen of je team te verwittigen.

{ "productId": "prod_1", "stock": 200, "stockAvailable": 4, "threshold": 5 }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "product.stock_low · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["productId", "stock", "stockAvailable", "threshold"],
  "properties": {
    "productId": { "type": "string" },
    "stock": { "type": "integer", "description": "Totale voorraad ingesteld op het product" },
    "stockAvailable": { "type": "integer", "description": "Stuks nog beschikbaar na deze bestelling" },
    "threshold": { "type": "integer", "const": 5 }
  }
}

event.published — event gepubliceerd en live

{ "eventId": "ev_5e6f7a8b", "eventName": "Summer Yoga Retreat", "startAt": "2026-07-01T09:00:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "event.published · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["eventId", "eventName", "startAt"],
  "properties": {
    "eventId": { "type": "string" },
    "eventName": { "type": "string" },
    "startAt": { "type": "string", "format": "date-time" }
  }
}

consent.opted_in — koper gaf toestemming voor marketing

Verstuurd wanneer een koper bij het afrekenen het vakje voor marketing aanvinkt (evenementen en passes).

{ "buyerEmail": "buyer@example.com", "consentPurpose": "Event checkout for event ev_5e6f7a8b", "consentedAt": "2026-06-15T09:00:00.000Z", "eventId": "ev_5e6f7a8b" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "consent.opted_in · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["buyerEmail", "consentPurpose", "consentedAt"],
  "properties": {
    "buyerEmail": { "type": "string", "format": "email" },
    "consentPurpose": { "type": "string" },
    "consentedAt": { "type": "string", "format": "date-time" },
    "eventId": { "type": "string", "description": "Present for event checkout; omitted for pass purchases" }
  }
}

consent.withdrawn — koper trok toestemming voor marketing in

Verstuurd wanneer iemand zich uitschrijft via de link in een e-mail, en wanneer een actieve toestemming verdwijnt door een GDPR-verzoek tot wissing — zodat ook je mailingtool stopt met mailen.

{ "buyerEmail": "buyer@example.com", "withdrawnAt": "2026-06-15T09:00:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "consent.withdrawn · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["buyerEmail", "withdrawnAt"],
  "properties": {
    "buyerEmail": { "type": "string", "format": "email" },
    "withdrawnAt": { "type": "string", "format": "date-time" }
  }
}

Widgets via de API

Alles wat je in het dashboard met eventwidgets kunt doen, kan ook via de API. Zo kan een website-integratie — bijvoorbeeld een WordPress-plugin — widgets aanmaken en plaatsen zonder dat iemand fragmenten met de hand kopieert. Sleutels hebben de scope widgets:read nodig om widgets op te vragen en widgets:write om ze aan te maken, te wijzigen of te verwijderen.

Een widget-body gebruikt dezelfde velden als het formulier in het dashboard:

{
  "name": "Homepage",
  "view": "list",
  "selectionMode": "templates",
  "eventTemplateIds": ["tpl_abc123"],
  "dateFrom": "2026-10-01T00:00:00.000Z",
  "theme": { "primaryColor": "#4f46e5", "borderRadius": "md" },
  "defaultLocale": "nl"
}

selectionMode is all_upcoming, templates (met eventTemplateIds), manual (met eventIds) of location (met locationIds); view is list of calendar. Elke widget die de API teruggeeft bevat een embed-blok met de URL van het laadscript, de iframe-URL, een kant-en-klaar snippet en de data-*-attributen die het script leest — plaats het fragment of bouw je eigen <script>/<iframe> op basis van die waarden. Omdat het fragment enkel naar het widget-ID verwijst, zijn latere wijzigingen via de API of het dashboard meteen zichtbaar op de website.

Een shopwidget zet "type": "shop" en somt de getoonde categorieën op in productCategoryIds (leeg = de volledige shop, met de categoriefilter); eventvelden zoals selectionMode gelden er niet voor. Widgets zonder type zijn eventwidgets ("type": "events"). Zie Shopwidgets.

Evenementen beheren via de API

Elke request stuurt je sleutel mee als bearer-token, JSON-bodies gebruiken dezelfde velden als de formulieren in het dashboard, en antwoorden zitten in { "data": … } (fouten in { "error", "message" }). De voorbeelden hieronder brengen een evenement in drie oproepen van concept naar gepubliceerd.

1. Een conceptevenement met één tickettype aanmaken (events:write):

curl -X POST https://cleartix.io/api/v1/events \
  -H "Authorization: Bearer ctk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": { "nl": "Quizavond" },
    "description": {},
    "locales": ["nl"],
    "startAt": "2026-11-14T18:30:00.000Z",
    "endAt": "2026-11-14T22:00:00.000Z",
    "timezone": "Europe/Brussels",
    "ticketTypes": [
      { "name": { "nl": "Team (max. 4 personen)" }, "basePrice": 20, "capacity": 40 }
    ]
  }'

Het antwoord bevat het id van het nieuwe evenement en status: "draft". Tickettypes kun je ook later toevoegen of wijzigen via POST /api/v1/events/{id}/ticket-types en PATCH …/ticket-types/{ttId}; GET /api/v1/events/{id}/readiness vertelt je wat er nog ontbreekt voor het evenement live kan.

2. Publiceren (events:write):

curl -X POST https://cleartix.io/api/v1/events/ev_5e6f7a8b/publish \
  -H "Authorization: Bearer ctk_live_…"

3. De herinneringsmail voor dit evenement instellen (emails:write):

curl -X PUT https://cleartix.io/api/v1/events/ev_5e6f7a8b/emails/event_reminder \
  -H "Authorization: Bearer ctk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "nl": "Tot morgen op de quizavond!" },
    "body": { "nl": "De deuren gaan open om 19:00. Breng je teamnaam en je denkpet mee." },
    "isActive": true
  }'

GET /api/v1/events/{id}/emails toont de effectieve mail per type (je override of de standaard van de organisatie), POST …/emails/{type}/preview rendert ze met voorbeeldvariabelen, en DELETE …/emails/{type} verwijdert de override weer.

Ticketlayout. GET/PUT /api/v1/ticket-layout leest en vervangt de standaardinhoud van je organisatie voor het onderste derde van PDF-tickets (sponsors, reclame); GET/PUT /api/v1/events/{id}/ticket-layout leest en zet de mode van een event (inherit, custom of hidden) en zijn eigen content. De inhoud is per taal Tiptap-JSON, net als bij mails. Lezen vraagt events:read, wijzigen events:write. Zie Sponsors en reclame op je tickets.

Templates werken op dezelfde manier onder /api/v1/templates: maak er een aan met POST, plan tot 50 datums in één keer met POST /api/v1/templates/{id}/schedule (stuur dryRun: true mee om de datums en de controle op de maandlimiet te bekijken zonder iets aan te maken), of pas hem toe op een bestaand evenement met POST /api/v1/templates/{id}/apply. Een PATCH op een template (of een evenement) is een gedeeltelijke update: alleen de velden die je meestuurt veranderen — al de rest, inclusief tickettypes en e-mails, blijft zoals het was. Event-responses geven de ingestelde plaatsenlimiet terug als capacity en de nog vrije plaatsen als availableCapacity; het oudere veld eventCapacity is verouderd (wordt bij invoer nog aanvaard en voorlopig nog als alias teruggegeven).

Bestellingen, tickets en check-in. GET /api/v1/orders toont de bestellingen van je hele organisatie (filter met eventId, status, paymentMethod, email, vrije tekst q of een periode from/to), POST /api/v1/orders/{id}/refund betaalt een volledige bestelling of specifieke tickets terug, en POST /api/v1/orders/{id}/cancel annuleert een bestelling die nog op betaling wacht (beide orders:write). Om je rekeninguittreksels af te punten stuur je de inkomende betalingen (bedrag, mededeling, naam van de betaler) naar POST /api/v1/orders/reconcile (orders:read): je krijgt per lijn de bestelling die op die overschrijving of factuurbetaling wacht, zonder dat er iets geboekt wordt. POST /api/v1/orders/mark-paid boekt daarna tot 50 bestellingen als betaald en POST /api/v1/orders/{id}/mark-paid één bestelling (orders:write); geef expectedAmount mee, dan wordt een bestelling waarvan het totaal afwijkt geweigerd met 409 AMOUNT_MISMATCH. GET /api/v1/orders/{id} bevat ook de mededeling (wireTransferReference) en het factuurnummer (invoiceNumber). GET /api/v1/tickets zoekt tickets over alle evenementen heen op e-mail, naam, ticket- of bestel-ID, en POST /api/v1/tickets/{id}/resend maakt de tickets opnieuw aan en mailt de bevestiging opnieuw naar de koper (tickets:write). POST /api/v1/events/{id}/guest-tickets geeft gratis gasttickets uit — een bestelling van € 0 voor pers, sponsors of vrijwilligers die capaciteit verbruikt zoals een verkoop en de tickets mailt (orders:write); PATCH /api/v1/tickets/{id} vervangt de deelnemersgegevens van een ticket en POST /api/v1/tickets/{id}/transfer draagt een ticket over aan iemand anders, met een nieuwe QR-code en een e-mail om het te aanvaarden (beide tickets:write). Voor aan de deur geeft GET /api/v1/tickets/{id} de check-in-status en scanhistoriek van een ticket, checkt POST /api/v1/tickets/{id}/check-in het in en maakt POST /api/v1/tickets/{id}/undo-check-in dat weer ongedaan (checkin:write). POST /api/v1/events/{id}/unpublish haalt een gepubliceerd evenement zonder bestellingen weer uit de verkoop. Terugbetalingen worden geregistreerd op naam van wie ze aanvroeg, dus /refund werkt alleen voor een AI-assistent die zich via OAuth heeft aangemeld — een gewone API-sleutel krijgt 409 CONFLICT en dan betaal je terug vanuit het dashboard.

Wachtlijst, team, privacy, audit en facturatie. GET /api/v1/events/{id}/waitlist toont de wachtlijst van een evenement en DELETE /api/v1/events/{id}/waitlist/{entryId} verwijdert één inschrijving (waitlist:write). GET/PATCH/DELETE /api/v1/team/members[/{id}] tonen teamleden, veranderen hun rol en verwijderen ze, GET/POST /api/v1/team/invites en DELETE /api/v1/team/invites/{id} (plus POST …/{id}/resend) beheren openstaande uitnodigingen, en POST/DELETE /api/v1/events/{id}/gates/{gateId}/scanners[/{membershipId}] wijzen scanners aan een gate toe of halen ze er weer af (allemaal team:write). POST /api/v1/privacy/export geeft alles terug wat je over een e-mailadres bewaart en POST /api/v1/privacy/anonymize wist dat onomkeerbaar (privacy:write). GET /api/v1/audit-log leest de auditlog (audit:read), en GET /api/v1/billing en GET /api/v1/billing/invoices geven je plan, het maandelijkse eventverbruik en de platformfacturen (billing:read).

Locaties vind je onder /api/v1/locations, starterkits (quiz, eetfestijn, workshopreeks, …) onder GET /api/v1/starter-kits, en POST /api/v1/uploads/presign geeft je een upload-URL voor een event- of templateafbeelding (het antwoord bevat ook een permanente publicUrl). Wil je zelf geen bytes PUT-en, dan laat POST /api/v1/uploads/import met { "url": "https://…/foto.jpg" } (of base64) Cleartix de afbeelding voor jou ophalen en opslaan. Om een afbeelding in de evenementbeschrijving te plaatsen, voeg je een image-node toe aan het Tiptap-document met src gelijk aan die publicUrl; de optionele attributen width (sm, md, full) en align (left, center, right) bepalen grootte en positie, precies zoals in de editor. Elke schrijfoproep wordt met het voorvoegsel van de sleutel in je auditlog vastgelegd, zodat je altijd ziet welke integratie wat heeft gewijzigd.

De shop via de API

De tag Shop van de specificatie dekt de catalogus en de afhandeling: GET /api/v1/products (filter met ?kind=physical|digital en ?active=true|false), POST/PATCH voor producten, POST /api/v1/products/{id}/file/presign + PUT /api/v1/products/{id}/file om het bestand van een digitaal product te uploaden, /api/v1/shipping-methods, GET /api/v1/shipments voor de werklijst, POST /api/v1/orders/{id}/ship en POST /api/v1/orders/{id}/lines/{lineId}/fulfil om een bestelling als verzonden of een afgehaalde lijn als afgegeven te markeren. GET /api/v1/orders/{id} geeft de kind van de bestelling (tickets, pass of shop), haar lines[] met afhandelingsstatus, downloadteller en terugbetaalde stuks, en een blok shipping (methode, adres, vervoerder, tracking). GET /api/v1/stats/products (scope stats:read, Studio/Pro) geeft stuks, bestellingen en omzet per product, opgesplitst per kanaal (shop / event) en met terugbetalingen; AI-assistenten krijgen hetzelfde via de tool get_product_sales.

Ook de rest van de shop beheer je via de API: categorieën onder /api/v1/product-categories (opvragen, aanmaken, wijzigen, verwijderen en herschikken; de categorie van een product stel je in met categoryId op het product), de volgorde van de catalogus met POST /api/v1/products/reorder ({ "ids": [...] }) en de shopinstellingen — shop open of dicht, introtekst, verzend- en retourbeleid, toestemmingstekst digitale inhoud, afzenderadres en weergave categorieën — met GET/PATCH /api/v1/shop/settings. Shopwidgets zijn gewone widgets onder /api/v1/widgets (zie hierboven).

OpenAPI-specificatie

De volledige API is beschreven in een machineleesbaar OpenAPI 3.1-document op https://cleartix.io/api/v1/openapi.json. Importeer het in Postman of Swagger UI om de endpoints te verkennen, of geef het aan een clientgenerator voor je programmeertaal. Elke operatie vermeldt de vereiste scope en de exacte vorm van request en response — het is de volledige referentie voor de endpoints die hierboven samengevat zijn.

Houd sleutels veilig

Een API-sleutel handelt in naam van je organisatie, dus behandel hem als een wachtwoord:

1. Zet hem nooit in versiebeheer en deel hem niet publiek.
2. Gebruik waar mogelijk een aparte sleutel per integratie.
3. Roteer een sleutel meteen als hij uitlekt, en verwijder sleutels die je niet meer gebruikt.