Appearance
Orders
We import the full history when the organiser connects, then keep reading changes, as often as your reconciliation.minDelay allows. With webhooks changes arrive within seconds, and this reconciliation can run slowly, or be turned off.
| Endpoint | Returns | Notes |
|---|---|---|
GET /v1/orders | The account's orders: the order, its buyer, the voucher used, and one item per product sold, with its holder. | Sorted by order.updatedAt, then order.id. Supports updatedSince. |
GET /v1/fields | Every key you can send in a person's fields, with a name and a type. | Optional: answer 404 when you don't offer it. Not paged. We read it when the organiser connects and a few times per day. |
json
{
"order": {
"id": "ord_991",
"orderedAt": "2026-11-10T21:03:00+01:00",
"updatedAt": "2026-11-10T21:03:00+01:00"
},
"buyer": {
"email": "sam@example.com",
"firstName": "Sam",
"lastName": "Jansen",
"phone": "+31612345678",
"fields": { "dob": "1995-07-12" }
},
"voucher": { "code": "SAMJANSEN015" },
"items": [
{
"product": {
"id": "tkt_1",
"status": "active",
"price": { "amount": 2500, "currency": "EUR" }
},
"event": { "id": "evt_123" },
"productType": { "id": "tt_1" },
"holder": {
"email": "kim@example.com",
"firstName": "Kim",
"lastName": null,
"phone": null,
"fields": { "newsletterOptIn": true, "whatsappOptIn": false }
}
}
]
}json
{
"fields": [
{ "key": "dob", "name": "Date of birth", "type": "date" },
{
"key": "newsletterOptIn",
"name": "Newsletter",
"description": "Opted in to the organiser's newsletter",
"type": "boolean"
},
{ "key": "postalCode", "name": "Postal code", "type": "string" }
]
}Vouchers
voucher.code is the code used on the order. We attribute the order's products to the ambassador who shared that code. Send it whenever your platform knows it, and null when no voucher was used.
Buyer and holder
The buyer placed the order; each product, usually an admission ticket, may have its own holder. All person fields are optional: send what you have. holder may be null.
Marketing consent
An opt-in is a boolean in fields, under your own key. Leave the key out when you don't know. That is different from a consent that was refused (false). Organisers choose which of your fields count as their marketing consent, for email or WhatsApp.
Cancellations
A product's status becomes canceled. Move the order's updatedAt on every change, a refund or a new holder included, so we pick it up.
Custom fields
fields carries everything about a person beyond name, email and phone: a date of birth, a postal code, an answer to a custom question, an opt-in. Organisers map your keys to their own Innercrowd fields and consents. With /v1/fields they see a name, description and type for each key, even before the first order arrives; without it they map the keys as they appear in your orders.
Field types
string, number, boolean, date, email or phone. Organisers can only map a field to one of their own fields of a compatible type. Phone numbers, in a person's phone and in phone fields, preferably come in E.164 format (+31612345678). We try to parse other formats into E.164, but a number without a country code may not parse.
Configuration
In capabilities.orders of /v1/account.
| Option | Type | Default | What it does |
|---|---|---|---|
version | string | "v1" | The version you implement, and the prefix of the paths we call. |
reconciliation.enabled | boolean | true | Whether we read /v1/orders?updatedSince=… at all after the first import. We recommend leaving it on unless your webhooks are extremely stable: without it, a webhook that never arrives means a change we never see. We only accept false together with webhooks. |
reconciliation.minDelay | seconds | 300 | The least time between two reads of /v1/orders?updatedSince=…. We recommend 300 (5 minutes) or less; go higher only with webhooks, which bring changes in within seconds. |
reconciliation.overlap | seconds | 300 | How far before the previous read we start the next one, to catch orders that changed while it ran or were committed late. Duplicates are fine: we process an order once per change. |