Management API reference

Use this page to choose scopes, collections, and query arguments. The generated reference lists every field, filter, input, and enum.

Endpoint and authentication

Send JSON requests to POST https://<api-host>/api/graphql/management/v1 with Content-Type: application/json and Authorization: Bearer <management-token>. The credential selects one account; omit X-Tenant-Domain. A conflicting account header is rejected. Legacy user API keys, JWTs, and Booking credentials do not authenticate Management requests.

account { id name currency timeZone } returns the selected account and its reporting time zone. Account currency is a default, not a guarantee that every financial record shares that currency.

Data categories and scopes

Each collection also has a singular lookup, such as order(id: "..."), invoiceItem(id: "..."), or customFieldValue(id: "..."). A missing or other-account ID returns null. The same scope is required for collection and lookup.

Scopes grant account-wide access within their category. Relationship IDs can refer to another category; reading that category requires its own scope. For example, orders:read includes order totals and contact IDs, while retrieving contact email addresses requires contacts:read.

Collection arguments

Every filter supports ids, createdSince, createdBefore, updatedSince, updatedBefore, and discarded. Lower time bounds are inclusive; upper bounds are exclusive. Omitting discarded includes active and discarded records; true selects discarded records, false selects active records. Types without discard support return no rows for discarded: true.

Additional filters follow the relationship: orderItems(filter: {orderIds: [...]}), pricings(filter: {orderItemIds: [...]}), invoiceItems(filter: {invoiceIds: [...]}), payments(filter: {invoiceIds: [...]}), and customFieldValues(filter: {responseIds: [...]}). Attendance filters accept eventIds and orderIds. Consult the generated input types for the full list; filters differ by collection.

Results contain nodes and pageInfo { endCursor hasNextPage }, ordered by updatedAt ascending and then ID. All records expose id, name, number, createdAt, updatedAt, discardedAt, and tombstone; nullable fields can be absent for a particular record type. Timestamps preserve microseconds. Amounts ending in Cents use minor currency units and are serialized as decimal strings; retain their currency and parse without 32-bit truncation. For EUR, "12500" means EUR 125.00.

Business filters

The same filter input is accepted by a collection and its corresponding report. Lists generally match any entry; separate fields match together. The tagIds exception is described below. Empty lists match nothing. Reports default to discarded: false; set that explicitly on the export when comparing counts.

tagIds requires all selected tags for orders, invoices, and attendances. For orders, all tags must match one non-discarded item’s offering; event tags include inherited event-template tags. For invoices, tags may match different line offerings or products, including embedded sub-items. For attendances, tags can come from the event or admission (including inherited event-template tags) and the effective product; an explicit attendance product takes precedence over the pricing product. Customer tagIds matches any selected tag.

text is a case-insensitive literal substring of the record's own identifiers or descriptive fields. It does not search linked records; use their IDs for relationships. % and _ are literal characters. Text filters accept 1–255 characters. Country, locale, shipping state, and other enum filters use the exact values in the generated reference.

visitDates and ticketScanDates accept half-open account-local date ranges such as "[2026-10-01,2026-11-01)". Visit dates describe the booked offering, not order creation. Order offering and visit conditions can match different items within the same order, following the back-office order filters. checkedInSince/checkedInBefore filter the attendance check-in timestamp; ticketScanDates filters its linked check-in scan event and excludes records without one.

customAnswers requires custom-fields:read and custom fields enabled. Supported scopes are BOOKING/CONTACT on orders, CONTACT on contacts, and ATTENDEE/BOOKING/CONTACT on attendances. Supply an inputId and either values or missing: true; omitting both selects any nonblank answer. Values match normalized answers with surrounding whitespace removed; stored answer exports preserve their original text. Up to ten answer conditions are combined with AND; each condition accepts up to 100 alternative values. Repeated matching answers do not duplicate the parent record or its count. missing: true cannot be combined with values. Supported input types are text, telephone, email, date, select, radio, and checkbox; file uploads are excluded.

Orders expose billingAddressSnapshot and shippingAddressSnapshot; invoices expose billingAddressSnapshot. These return the stored address at the time of the transaction, where available, while address IDs lead to current address records. Selecting a snapshot additionally requires contacts:read.

Reports and scopes

All reports require reporting to be enabled for the account, reports:read, and these source scopes:

The four count reports support primary and secondary grouping, including time grouping for timestamp dimensions. Invoice counts are not revenue; answer counts count stored answer records, not distinct respondents. Use revenueReport for invoice/receipt-line amounts.

Monetary measures and grouping by sold amounts or revenue buckets require finance:read and an explicit currency, such as "EUR". Only source amounts in that currency contribute. Currency is rejected on nonmonetary reports without a monetary grouping. Grouping revenue by contact_id additionally requires contacts:read; event purchase-time metrics require orders:read; order attendee counts require attendance:read. Custom-field grouping requires custom-fields:read and custom fields enabled for the account.

Pass one required metric object with measure, a dimension or supported customFieldDimension, and a nonempty aggregations list. Choose compatible values from the generated enums. secondaryDimension adds a second grouping; timeFunction and secondaryTimeFunction group temporal dimensions in the account's time zone. Report filter applies before aggregation over the entire matching dataset, independently of record pagination. Reports exclude discarded source records by default.

Reports return data rows with grouping identifiers, labels, and requested aggregates. count and sum are decimal strings; avg, min, and max are numbers. Inapplicable fields are null. Keep group IDs as keys rather than translated labels. Reports are limited to 10,000 groups and a 15-second database statement timeout; an exceeded limit returns an error rather than a partial report. Narrow the source filters or split by period. Do not add averages from different periods.

Errors and limits

Check both HTTP status and top-level GraphQL errors. Never accept an errored page or report as a complete result. Authentication failures return HTTP 401. Rate limiting returns HTTP 429 with Retry-After. Missing scopes produce Not authorized; invalid report definitions produce GraphQL errors. A report failure can leave other selected fields available, but that report is incomplete.

Default query limits are depth 8, complexity 1,000, and 2,000 query tokens. Report fields have a higher complexity cost; send one report per request for predictable execution. There are no mutations or subscriptions.