Event

An Event (e.g., a concert, game, conference, workshop, festival, meetup, show…) is the fundamental unit of what organizers create on Billy's platform. They have a specific name, a single venue and configuration.

Session

A Session is a scheduled occurrence within an Event, and a resource in its own right: it has its own id, start/end times, capacity rules, and optional context (e.g., show, performance, workshop session, talk…). Events have at least one session and can have multiple sessions. Sessions are listed via GET /events/{event_id}/sessions, and Tickets and OrderItems reference them by id. From release 2026-09-01, the Event carries only summary fields (sessionCount, firstSessionStartAt, lastSessionStartAt, nextSessionStartAt, nextSessionId); before that date, or when pinned to an earlier version, the Event still embeds its sessions in an eventSessions array.

Tag

A Tag is a free-form label organizers attach to their Events (e.g., jazz, rap music, Électro) for filtering and grouping. Tags form a single vocabulary per organization: when you send a tag whose normalized form matches an existing one, the existing tag is reused. Normalization is case-insensitive and collapses surrounding/repeated whitespace, but keeps accents (Café ≠ Cafe); the displayed label keeps the casing of the first writer. Commas are not allowed in tags, as they separate values in query string filters. Tags are set at event creation, replaced as a whole set when updating an event, and usable as a filter on the events endpoint.

Ticket

A Ticket represents a permission for an attendee to access a specific Event (or Session). It always has a category name (e.g., VIP, General Admission) and a unique scannable code. It may also contain a pricing and a seat assignment. When a ticket is explicitly assigned, it also displays the attendee registration answers (e.g. first name, last name etc.). Tickets are issued when purchased by a customer, or when a guest is added.

Event
 ├── Session* (1…N)
 │     └── TicketInventory or TicketAvailability Logic**
 └── Tickets

* Number of sessions depend on the event type.
** Tickets may have session-specific allocation.

Order

An Order is a customer's request to purchase items through a specific sales channel. It groups one or more OrderItems along with pricing details (subtotal, fees, discounts, VAT) and payment information. An order progresses through three statuses: PENDING (placed but not yet fulfilled), FULFILLED (tickets emitted), and CANCELLED.

OrderItem

An OrderItem represents a single line within an Order, a quantity of a specific offer (ticket or product). Each item traces back to an Event and, when applicable, a Session. Bundle offers are unpacked into their constituent items. An OrderItem carries its own unit pricing, discount, and VAT information.