{ "components": { "schemas": { "dto.PartnerEvent": { "properties": { "createdAt": { "example": "2026-09-01T09:30:00Z", "type": "string", "format": "date-time" }, "currency": { "description": "Currency is the ISO 4217 code all of the event's amounts are in.", "example": "CZK", "type": "string" }, "doorsOpenAt": { "example": "2027-02-19T18:00:00Z", "type": "string", "format": "date-time" }, "endsAt": { "example": "2027-02-20T02:00:00Z", "type": "string", "format": "date-time" }, "id": { "example": "723480938765152257", "type": "string" }, "locationName": { "example": "Kulturní dům Vltava", "type": "string" }, "name": { "example": "Ples 2027", "type": "string" }, "slug": { "example": "ples-2027", "type": "string" }, "startsAt": { "example": "2027-02-19T19:00:00Z", "type": "string", "format": "date-time" }, "status": { "description": "Status is one of: draft, on_sale, past, cancelled.", "example": "on_sale", "type": "string" }, "updatedAt": { "example": "2026-09-13T14:02:11Z", "type": "string", "format": "date-time" } }, "type": "object" }, "dto.PartnerEventDetail": { "properties": { "createdAt": { "example": "2026-09-01T09:30:00Z", "type": "string", "format": "date-time" }, "currency": { "description": "Currency is the ISO 4217 code all of the event's amounts are in.", "example": "CZK", "type": "string" }, "doorsOpenAt": { "example": "2027-02-19T18:00:00Z", "type": "string", "format": "date-time" }, "endsAt": { "example": "2027-02-20T02:00:00Z", "type": "string", "format": "date-time" }, "id": { "example": "723480938765152257", "type": "string" }, "locationName": { "example": "Kulturní dům Vltava", "type": "string" }, "name": { "example": "Ples 2027", "type": "string" }, "slug": { "example": "ples-2027", "type": "string" }, "startsAt": { "example": "2027-02-19T19:00:00Z", "type": "string", "format": "date-time" }, "status": { "description": "Status is one of: draft, on_sale, past, cancelled.", "example": "on_sale", "type": "string" }, "ticketTypes": { "items": { "$ref": "#/components/schemas/dto.PartnerTicketType" }, "type": "array", "uniqueItems": false }, "updatedAt": { "example": "2026-09-13T14:02:11Z", "type": "string", "format": "date-time" } }, "type": "object" }, "dto.PartnerOrder": { "properties": { "createdAt": { "example": "2026-09-13T18:44:59Z", "type": "string", "format": "date-time" }, "currency": { "example": "CZK", "type": "string" }, "customerEmail": { "example": "jana@example.com", "type": "string" }, "customerName": { "example": "Jana Nová", "type": "string" }, "customerPhone": { "example": "+420777123456", "type": "string" }, "discountCents": { "example": 5000, "type": "integer" }, "discountCode": { "description": "DiscountCode is the promo code redeemed on this order (null = none);\nDiscountCents the concrete amount it took off the total.", "example": "EARLYBIRD", "type": "string" }, "eventId": { "example": "723480938765152257", "type": "string" }, "expiresAt": { "example": "2026-09-20T23:59:59Z", "type": "string", "format": "date-time" }, "id": { "example": "723480938765152300", "type": "string" }, "paidAt": { "example": "2026-09-14T10:12:45Z", "type": "string", "format": "date-time" }, "paymentMethod": { "description": "PaymentMethod is one of: cash, card, bank_transfer, on_site,\ncomplimentary; null while unset.", "example": "bank_transfer", "type": "string" }, "reference": { "description": "Reference is the human order code (doubles as the bank-transfer\nvariable symbol).", "example": "20270042", "type": "string" }, "status": { "description": "Status is one of: pending, pending_review, paid, cancelled, expired.", "example": "paid", "type": "string" }, "totalCents": { "example": 98000, "type": "integer" }, "updatedAt": { "example": "2026-09-14T10:12:45Z", "type": "string", "format": "date-time" } }, "type": "object" }, "dto.PartnerOrderDetail": { "properties": { "createdAt": { "example": "2026-09-13T18:44:59Z", "type": "string", "format": "date-time" }, "currency": { "example": "CZK", "type": "string" }, "customerEmail": { "example": "jana@example.com", "type": "string" }, "customerName": { "example": "Jana Nová", "type": "string" }, "customerPhone": { "example": "+420777123456", "type": "string" }, "discountCents": { "example": 5000, "type": "integer" }, "discountCode": { "description": "DiscountCode is the promo code redeemed on this order (null = none);\nDiscountCents the concrete amount it took off the total.", "example": "EARLYBIRD", "type": "string" }, "eventId": { "example": "723480938765152257", "type": "string" }, "expiresAt": { "example": "2026-09-20T23:59:59Z", "type": "string", "format": "date-time" }, "id": { "example": "723480938765152300", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/dto.PartnerOrderItem" }, "type": "array", "uniqueItems": false }, "paidAt": { "example": "2026-09-14T10:12:45Z", "type": "string", "format": "date-time" }, "paymentMethod": { "description": "PaymentMethod is one of: cash, card, bank_transfer, on_site,\ncomplimentary; null while unset.", "example": "bank_transfer", "type": "string" }, "reference": { "description": "Reference is the human order code (doubles as the bank-transfer\nvariable symbol).", "example": "20270042", "type": "string" }, "status": { "description": "Status is one of: pending, pending_review, paid, cancelled, expired.", "example": "paid", "type": "string" }, "tickets": { "items": { "$ref": "#/components/schemas/dto.PartnerTicket" }, "type": "array", "uniqueItems": false }, "totalCents": { "example": 98000, "type": "integer" }, "updatedAt": { "example": "2026-09-14T10:12:45Z", "type": "string", "format": "date-time" } }, "type": "object" }, "dto.PartnerOrderItem": { "properties": { "attendeeNames": { "description": "AttendeeNames holds one name per unit when the event collects them.", "example": [ "Jana Nová", "Petr Dvořák" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "id": { "example": "723480938765152301", "type": "string" }, "priceCents": { "description": "PriceCents is the per-unit price this line was sold at.", "example": 49000, "type": "integer" }, "pricePhase": { "description": "PricePhase names the scheduled price phase active at purchase (e.g.\n\"Early bird\"); null = the regular base price applied.", "example": "Early bird", "type": "string" }, "quantity": { "example": 2, "type": "integer" }, "seatId": { "example": "723480938765152401", "type": "string" }, "ticketTypeId": { "example": "723480938765152258", "type": "string" } }, "type": "object" }, "dto.PartnerOrderList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/dto.PartnerOrder" }, "type": "array", "uniqueItems": false }, "nextCursor": { "example": "eyJpZCI6NzIzNDgwOTM4NzY1MTUyMzAwfQ==", "type": "string" } }, "type": "object" }, "dto.PartnerScanResult": { "properties": { "holderName": { "description": "Display context for gates with a screen; empty on refusals of unknown codes.", "example": "Jana Nová", "type": "string" }, "readmit": { "example": false, "type": "boolean" }, "result": { "enum": [ "valid", "already_scanned", "revoked", "not_found" ], "example": "valid", "type": "string" }, "seatCode": { "example": "A-12", "type": "string" }, "typeName": { "example": "Vystavovatel", "type": "string" } }, "type": "object" }, "dto.PartnerTicket": { "properties": { "checkedInAt": { "description": "CheckedInAt is the moment the ticket was scanned at the door; null =\nnot checked in yet.", "example": "2027-02-19T19:24:31Z", "type": "string", "format": "date-time" }, "code": { "description": "Code is the ticket's QR payload as printed for the buyer.", "example": "H7K2-Q9ZD-4MWP", "type": "string" }, "createdAt": { "example": "2026-09-14T10:12:45Z", "type": "string", "format": "date-time" }, "holderName": { "example": "Jana Nová", "type": "string" }, "id": { "example": "723480938765152500", "type": "string" }, "orderId": { "example": "723480938765152300", "type": "string" }, "orderReference": { "example": "20270042", "type": "string" }, "seatCode": { "example": "A-12", "type": "string" }, "status": { "description": "Status is \"valid\" or \"revoked\" (revoked = the order was cancelled).", "example": "valid", "type": "string" }, "ticketTypeId": { "example": "723480938765152258", "type": "string" }, "ticketTypeName": { "example": "Standard", "type": "string" } }, "type": "object" }, "dto.PartnerTicketList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/dto.PartnerTicket" }, "type": "array", "uniqueItems": false }, "nextCursor": { "example": "eyJpZCI6NzIzNDgwOTM4NzY1MTUyNTAwfQ==", "type": "string" } }, "type": "object" }, "dto.PartnerTicketType": { "properties": { "description": { "example": "Sál + předtančení", "type": "string" }, "id": { "example": "723480938765152258", "type": "string" }, "kind": { "description": "Kind is \"seated\" (units bind to seats) or \"standing\" (quantity-based).", "example": "seated", "type": "string" }, "name": { "example": "Standard", "type": "string" }, "priceCents": { "example": 49000, "type": "integer" }, "quantityTotal": { "description": "QuantityTotal is the sales cap; 0 means the capacity derives from the\nseat map (seated types) or is uncapped.", "example": 200, "type": "integer" }, "saleEndsAt": { "example": "2027-02-19T12:00:00Z", "type": "string", "format": "date-time" }, "salePaused": { "type": "boolean" }, "saleStartsAt": { "example": "2026-10-01T08:00:00Z", "type": "string", "format": "date-time" }, "unitsSold": { "description": "UnitsSold counts live inventory taken: paid plus pending (reserved)\norders.", "example": 137, "type": "integer" } }, "type": "object" }, "partnerhandler.PartnerOrganization": { "properties": { "id": { "example": "723480938765152200", "type": "string" }, "name": { "example": "Bookitive Demo", "type": "string" }, "slug": { "example": "demo", "type": "string" } }, "type": "object" }, "partnerhandler.payloadPartnerScan": { "properties": { "code": { "maxLength": 200, "minLength": 4, "type": "string" }, "gate": { "maxLength": 80, "type": "string" } }, "required": [ "code" ], "type": "object" }, "response.APIError": { "properties": { "data": {}, "fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "msg": { "example": "see fields", "type": "string" }, "timestamp": { "example": "2026-09-13T18:45:12Z", "type": "string", "format": "date-time" }, "traceId": { "example": "2b9c1f0e-6d4a-4a1b-9e0f-3c5d7a8b9c0d", "type": "string" }, "type": { "$ref": "#/components/schemas/response.Type" } }, "required": [ "msg", "type" ], "type": "object" }, "response.Type": { "enum": [ "INVALID_PAYLOAD", "VALIDATION_FAILED", "NOT_FOUND", "NOT_IMPLEMENTED", "CONFLICT", "INTERNAL_ERROR", "UNAUTHORIZED", "FORBIDDEN", "VERIFICATION_REQUIRED", "MISSING_ORGANIZATION_ID", "MISSING_USER_ID", "PER_ORDER_LIMITS", "PER_CUSTOMER_LIMIT", "SOLD_OUT", "SEATS_TAKEN", "CAPACITY_FULL", "SALE_WINDOW", "SALES_PAUSED", "TICKET_TYPE_PAUSED", "NOT_ON_SALE", "DISCOUNT_INVALID", "DISCOUNT_EXHAUSTED", "VERIFICATION_INVALID", "ATTENDEES_REQUIRED", "TRANSFER_LOCKED", "TRANSFER_CODE_REQUIRED", "TRANSFER_CODE_INVALID", "TOO_MANY_REQUESTS" ], "example": "VALIDATION_FAILED", "type": "string", "x-enum-varnames": [ "ErrInvalidPayload", "ErrValidationFailed", "ErrNotFound", "ErrNotImplemented", "ErrConflict", "ErrInternal", "ErrUnauthorized", "ErrForbidden", "ErrVerificationRequired", "ErrMissingOrganizationID", "ErrMissingUserID", "ErrPerOrderLimits", "ErrPerCustomerLimit", "ErrSoldOut", "ErrSeatsTaken", "ErrCapacityFull", "ErrSaleWindow", "ErrSalesPaused", "ErrTicketTypePaused", "ErrNotOnSale", "ErrDiscountInvalid", "ErrDiscountExhausted", "ErrVerificationInvalid", "ErrAttendeesRequired", "ErrTransferLocked", "ErrTransferCodeRequired", "ErrTransferCodeInvalid", "ErrTooManyRequests" ] }, "webhook.order.paid": { "type": "object", "required": [ "id", "type", "createdAt", "data" ], "properties": { "id": { "type": "string", "description": "Unique event id — deduplicate on it, deliveries may occasionally arrive more than once.", "example": "723480938765159001" }, "type": { "type": "string", "enum": [ "order.paid" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-13T18:45:12Z" }, "data": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/dto.PartnerOrderDetail" } } } } }, "webhook.order.cancelled": { "type": "object", "required": [ "id", "type", "createdAt", "data" ], "properties": { "id": { "type": "string", "description": "Unique event id — deduplicate on it, deliveries may occasionally arrive more than once.", "example": "723480938765159002" }, "type": { "type": "string", "enum": [ "order.cancelled" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-13T18:45:12Z" }, "data": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/dto.PartnerOrderDetail" } } } } }, "webhook.ticket.checked_in": { "type": "object", "required": [ "id", "type", "createdAt", "data" ], "properties": { "id": { "type": "string", "description": "Unique event id — deduplicate on it, deliveries may occasionally arrive more than once.", "example": "723480938765159003" }, "type": { "type": "string", "enum": [ "ticket.checked_in" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-13T18:45:12Z" }, "data": { "type": "object", "required": [ "ticket" ], "properties": { "ticket": { "$ref": "#/components/schemas/dto.PartnerTicket" } } } } } }, "securitySchemes": { "ApiKeyAuth": { "description": "Two credential classes, both sent as `Authorization: Bearer …` and managed in Settings → API. An API key (`bk_live_…`) authenticates as its organization and can only ever READ that organization's data. A scanner device secret (`bk_scan_…`) is the door credential: it can only call the scan endpoint — it has no read access, so gate hardware never holds a data-capable secret.", "in": "header", "name": "Authorization", "type": "apiKey" } } }, "info": { "description": "The **Bookitive Partner API** is the organizer-authenticated REST API: read your events, ticket types with live availability, orders (including attendee details) and issued tickets with their check-in state. Use it to sync a CRM or accounting system, print badges, drive an info screen, or reconcile attendance after the event.\n\nAPI keys are **read-only**. Selling happens through the [Public API](https://api.bookitive.com/public/v1/docs) and the hosted checkout; management through the Bookitive admin. For push-style updates, subscribe to [webhooks](#webhooks); for pull-style sync, poll `GET /orders?updatedAfter=…`. The one write in this tier is the [door scan endpoint](#tag/Check-in), and it deliberately uses a separate credential class — [scanner devices](#scanner-devices) — so gate hardware never holds a data-capable secret.\n\n## Base URL\n\n```\nhttps://api.bookitive.com/partner/v1\n```\n\n## Authentication\n\nEvery request carries a secret organization API key:\n\n```\nAuthorization: Bearer bk_live_…\n```\n\nCreate and revoke keys in the Bookitive admin under **Settings → API keys** (organization owners and admins). A key authenticates as its organization and can only ever read that organization's data — there is no way to widen its scope.\n\n## Scanner devices\n\nTurnstiles and third-party entry systems authenticate with a **scanner device** secret instead of an API key:\n\n```\nAuthorization: Bearer bk_scan_…\n```\n\nA scanner device can do exactly one thing — call `POST /events/{eventId}/scan` — and nothing else: no reads, no order data. Mint and revoke devices next to API keys in **Settings → API keys**; the secret is shown once at creation. Recommended setup: **one device per physical gate** (each gate gets its own rate budget, its own row in the check-in analytics, and its own kill switch — revoking a device shuts exactly that lane). Optionally pin a device to your venue's IP ranges (CIDR allowlist, editable any time without changing the secret); requests from other addresses are rejected with the same plain `401` as a bad secret.\n\nThe scan endpoint enforces each ticket's admission mode exactly like the staffed door: single entry, unlimited re-entry, or one entry per day. Open the gate only on `result: \"valid\"`; `readmit: true` marks a returning guest (still an admit). Group/order QR codes are refused — bulk admission is a staffed-door flow.\n\n**Timed anti-passback.** Every device carries an anti-passback window (default **5 minutes**, configurable per device, `0` disables): a ticket admitted within the window — at any lane or by staff — returns `result: \"already_scanned\"` at the device. This is the standard defense against a ticket being passed back outside at unattended gates without exit readers; a genuinely returning guest waits out the window or goes to a staffed lane, where the scanner shows the readmit verdict and a human decides. The window is editable any time without changing the secret.\n\n**Keys are secrets.** Use them from your servers only — never in a browser, mobile app, or public repository. If a key leaks, revoke it in the admin (takes effect immediately) and create a new one. All organization admins are notified by email whenever a key is created.\n\nVerify your setup with `GET /organization` — it returns the organization the key belongs to.\n\n## Rate limits\n\n**120 requests per minute per API key** and **240 per minute per scanner device** (one device per gate means the budget is per lane). Beyond that, requests return `429 TOO_MANY_REQUESTS`; back off and retry. If you need more, talk to us.\n\n## Pagination\n\nList endpoints that can grow unbounded (`/orders`, `/events/{eventId}/tickets`) return pages:\n\n```json\n{ \"data\": [ … ], \"nextCursor\": \"eyJpZCI6…\" }\n```\n\nPass `nextCursor` back as `?cursor=` to fetch the next page; a `null` cursor means the walk is complete. Cursors are opaque — never parse or construct them. Page size is `?limit=` (1–100, default 50).\n\n## Syncing changes\n\nPoll `GET /orders?updatedAfter=` with the timestamp of your last successful run. An order's `updatedAt` moves on every lifecycle change (payment matched, cancellation, expiry), so this returns exactly what changed since.\n\n## Webhooks\n\nFor push-style updates, register webhook endpoints in the Bookitive admin under **Settings → API keys**. We POST a JSON event to your URL whenever something you subscribed to happens:\n\n| Event | Fires when | `data` carries |\n| --- | --- | --- |\n| `order.paid` | An order is paid — instant sale or a matched bank transfer | `order` (full detail incl. items and tickets) |\n| `order.cancelled` | An order is cancelled (tickets revoked) | `order` |\n| `ticket.checked_in` | A ticket is scanned at the door (online or offline sync) | `ticket` |\n\nEvery body is an envelope: `{ \"id\": \"…\", \"type\": \"order.paid\", \"createdAt\": \"…\", \"data\": { … } }`. The `data` objects reuse the response shapes documented here.\n\n**Verify every delivery.** Each request carries a `Bookitive-Signature` header:\n\n```\nBookitive-Signature: t=1757740000,v1=5257a869e7…\n```\n\nRecompute `HMAC-SHA256(secret, t + \".\" + rawBody)` with your endpoint's signing secret (shown once at creation), hex-encode it, and compare against `v1` in constant time. Reject requests whose `t` is older than a few minutes — that closes replay. `Bookitive-Event` and `Bookitive-Delivery` headers carry the event type and a unique delivery id for logging and deduplication.\n\n**Delivery contract.** Respond with any 2xx quickly (do the work async). Anything else is retried with backoff — roughly 1 minute, 10 minutes, 1 hour, 6 hours and 24 hours — then marked dead. After several dead deliveries in a row the endpoint is disabled automatically and your organization's admins are emailed. Deliveries may occasionally arrive more than once or out of order: deduplicate on the envelope `id` and treat payloads as snapshots, not diffs. A per-endpoint delivery log with a \"send test event\" button lives in the admin.\n\n## Conventions\n\n- **IDs** are strings (64-bit snowflakes) — always treat them as opaque.\n- **Money** is an integer count of minor units (`totalCents`, `priceCents`) in the resource's `currency` (ISO 4217). `49000` with `CZK` means 490.00 Kč.\n- **Times** are RFC 3339 / ISO 8601 in UTC.\n- **Errors** share one envelope: a stable `type` code to branch on plus a human-readable `msg`. Authentication failures are always a plain `401 UNAUTHORIZED` regardless of why the key was rejected.\n- **Personal data**: order and ticket reads include buyer and attendee details of your own customers. Handle them under your privacy policy and the data-processing terms.", "title": "Bookitive Partner API", "version": "", "x-logo": { "url": "logo.png", "altText": "Bookitive" } }, "paths": { "/events": { "get": { "description": "All of the organization's events, newest start date first. Deleted events are never included.", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/dto.PartnerEvent" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List events", "tags": [ "Events" ] } }, "/events/{eventId}": { "get": { "description": "One event with every ticket type and its live inventory (unitsSold counts paid plus pending orders).", "parameters": [ { "description": "Event id", "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PartnerEventDetail" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get an event", "tags": [ "Events" ] } }, "/events/{eventId}/scan": { "post": { "description": "Validates a scanned code and admits the guest when the ticket's admission mode allows. Authenticate with a SCANNER DEVICE secret (`Bearer bk_scan_…`) — API keys are read-only and are rejected here. Open the gate only on `result: \"valid\"`; `readmit: true` marks a re-entry or daily pass coming back (still an admit). Group/order QR codes are refused (`not_found`) — bulk admission is a staffed-door flow. Timed anti-passback: when the device has a window configured (default 5 minutes), a ticket admitted within it anywhere at the event returns `already_scanned` — send the guest to a staffed lane. Recommended setup: one device per physical gate, with the lane name in `gate`.", "parameters": [ { "description": "Event id", "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/partnerhandler.payloadPartnerScan" } } }, "description": "Scanned code + optional gate label", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PartnerScanResult" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Scan a ticket (scanner devices)", "tags": [ "Check-in" ] } }, "/events/{eventId}/tickets": { "get": { "description": "Every issued ticket of the event with its check-in state, id-ascending. Page with ?cursor= from the previous response; nextCursor null means the walk is complete.", "parameters": [ { "description": "Event id", "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } }, { "description": "Page size (1–100, default 50)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Opaque cursor from the previous page", "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PartnerTicketList" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List an event's tickets", "tags": [ "Tickets" ] } }, "/orders": { "get": { "description": "The organization's orders, newest first, across all events unless ?eventId narrows it. Filter by ?status and poll for changes with ?updatedAfter (RFC 3339). Page with ?cursor= from the previous response; nextCursor null means the walk is complete.", "parameters": [ { "description": "Only orders of this event", "in": "query", "name": "eventId", "schema": { "type": "string" } }, { "description": "Only this status (pending | pending_review | paid | cancelled | expired)", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Only orders updated after this RFC 3339 timestamp", "in": "query", "name": "updatedAfter", "schema": { "type": "string" } }, { "description": "Page size (1–100, default 50)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Opaque cursor from the previous page", "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PartnerOrderList" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List orders", "tags": [ "Orders" ] } }, "/orders/{orderId}": { "get": { "description": "One order in full: lines (with attendee names when collected), issued tickets with check-in state, and the customer snapshot.", "parameters": [ { "description": "Order id", "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PartnerOrderDetail" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get an order", "tags": [ "Orders" ] } }, "/organization": { "get": { "description": "Returns the organization the presented API key belongs to. Call this first to verify your integration is authenticated correctly.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/partnerhandler.PartnerOrganization" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Verify the key / identify the organization", "tags": [ "Organization" ] } } }, "openapi": "3.1.0", "servers": [ { "url": "https://api.bookitive.com/partner/v1", "description": "Production" } ], "webhooks": { "order.paid": { "post": { "summary": "order.paid", "description": "**Order paid.** An order was paid — an instant box-office sale or a matched bank transfer. `data.order` is the full order detail including items and the freshly issued tickets.\n\nRespond with any 2xx quickly and do the work asynchronously — anything else is retried with backoff (≈1m, 10m, 1h, 6h, 24h) and then marked dead.", "operationId": "webhook-order-paid", "tags": [ "Webhooks" ], "parameters": [ { "name": "Bookitive-Signature", "in": "header", "required": true, "description": "`t=,v1=` — recompute over the RAW body with your endpoint's signing secret and compare in constant time; reject stale timestamps to close replay.", "schema": { "type": "string", "example": "t=1757740000,v1=5257a869e7…" } }, { "name": "Bookitive-Event", "in": "header", "required": true, "description": "The event type, duplicated from the envelope for cheap routing.", "schema": { "type": "string", "example": "order.paid" } }, { "name": "Bookitive-Delivery", "in": "header", "required": true, "description": "Unique delivery id — retries reuse it, so it doubles as a deduplication key alongside the envelope `id`.", "schema": { "type": "string", "example": "723480938765159100" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook.order.paid" } } } }, "responses": { "2XX": { "description": "Acknowledged — the delivery is marked succeeded." } } } }, "order.cancelled": { "post": { "summary": "order.cancelled", "description": "**Order cancelled.** An order was cancelled and its tickets revoked. `data.order` is the full order detail; the tickets it carries have status `revoked`.\n\nRespond with any 2xx quickly and do the work asynchronously — anything else is retried with backoff (≈1m, 10m, 1h, 6h, 24h) and then marked dead.", "operationId": "webhook-order-cancelled", "tags": [ "Webhooks" ], "parameters": [ { "name": "Bookitive-Signature", "in": "header", "required": true, "description": "`t=,v1=` — recompute over the RAW body with your endpoint's signing secret and compare in constant time; reject stale timestamps to close replay.", "schema": { "type": "string", "example": "t=1757740000,v1=5257a869e7…" } }, { "name": "Bookitive-Event", "in": "header", "required": true, "description": "The event type, duplicated from the envelope for cheap routing.", "schema": { "type": "string", "example": "order.paid" } }, { "name": "Bookitive-Delivery", "in": "header", "required": true, "description": "Unique delivery id — retries reuse it, so it doubles as a deduplication key alongside the envelope `id`.", "schema": { "type": "string", "example": "723480938765159100" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook.order.cancelled" } } } }, "responses": { "2XX": { "description": "Acknowledged — the delivery is marked succeeded." } } } }, "ticket.checked_in": { "post": { "summary": "ticket.checked_in", "description": "**Ticket checked in.** A ticket was scanned at the door — a live scan, an offline-device sync, or a group check-in. `data.ticket` carries the check-in timestamp and door context.\n\nRespond with any 2xx quickly and do the work asynchronously — anything else is retried with backoff (≈1m, 10m, 1h, 6h, 24h) and then marked dead.", "operationId": "webhook-ticket-checked_in", "tags": [ "Webhooks" ], "parameters": [ { "name": "Bookitive-Signature", "in": "header", "required": true, "description": "`t=,v1=` — recompute over the RAW body with your endpoint's signing secret and compare in constant time; reject stale timestamps to close replay.", "schema": { "type": "string", "example": "t=1757740000,v1=5257a869e7…" } }, { "name": "Bookitive-Event", "in": "header", "required": true, "description": "The event type, duplicated from the envelope for cheap routing.", "schema": { "type": "string", "example": "order.paid" } }, { "name": "Bookitive-Delivery", "in": "header", "required": true, "description": "Unique delivery id — retries reuse it, so it doubles as a deduplication key alongside the envelope `id`.", "schema": { "type": "string", "example": "723480938765159100" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook.ticket.checked_in" } } } }, "responses": { "2XX": { "description": "Acknowledged — the delivery is marked succeeded." } } } } } }