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-18, 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.

Catalog

The Catalog is what an organizer has put on sale: their Offers and the extras attached to a checkout. It is a namespace rather than a payload — each list under /catalog is homogeneous, so GET /catalog/offers returns Offers and nothing else. Internally Billy calls this the offers catalog; in the API, /catalog is the public name.

Offer

An Offer is something an organizer sells. It comes in three types, told apart by type:

• TICKET — an admission to an Event. Always Event-scoped — it is the only type that reports an eventId — and carries a VAT rate, a default capacity, and one stock line per Session.

• PRODUCT — a thing rather than an admission (merchandise, a vinyl…). Carries a VAT rate and variant axes such as size and colour, with one stock line per variant combination. It reports no eventId: merchandise is attached to an Event today, but is planned to move to the organization, so the field is not part of the contract.

• BUNDLE — a pack of other Offers, sold as one. It lists its components in contains — one entry per distinct component, with a quantity and the unit price the organizer set for it inside the pack — and carries a single flat pricingId and price rather than a list of Pricings. The pack's price is the sum of quantity × price over those entries: the same money at two granularities, the total and its breakdown. A Bundle has no VAT rate, no stock and no eventId of its own: all three come from, or follow, its components.

  A Bundle that carries no Pricing at all reports pricingId, price and every contains[].price as null — never 0 — while still listing what it contains.

Every stock line carries both totalStock, what the line was opened with, and availableStock, what is still sellable — the difference is what has been sold or is held in a pending basket.

eventId is reported on Ticket Offers only. GET /catalog/offers?eventId= still narrows the list to everything the Event currently holds, products and bundles included — so a filtered response can contain items that do not echo the value you filtered on. See Filtering.

compareAtPrice is a reference price the organizer types by hand to be shown struck through beside the real one. Nothing derives or validates it, so it is not guaranteed to be higher than what the Offer actually costs, and it is usually null — no route sets it when an Offer is created. What it is struck through against depends on the type: a Pricing's price on a Ticket or Product Offer, the pack's price on a Bundle.

The offerId returned here is exactly the one a Ticket carries, which is what lets you resolve a sold Ticket against the catalog. Offers have no archived or unpublished state, so an Offer never disappears from the list — the pair carried by an already-sold Ticket always resolves.

Pricing

A Pricing is what a given Offer costs under a given plan — "Tarif plein", "Tarif étudiant". The price is carried by the pair (Offer, Pricing), not by the Offer alone, so one Offer commonly has several. The pricingId is exactly the one a Ticket carries.

A Ticket Offer's pricing holds two kinds of entry, told apart by bundleOfferId:

• its own pricings (bundleOfferId: null), and
• the Bundle pricings it takes part in as a component (bundleOfferId set to the Bundle's offerId), each with the price the organizer set for it inside that pack.

The second kind matters because a Ticket bought inside a Bundle carries the component's offerId and the Bundle's pricingId; without those entries, that pair would resolve to nothing.

Resale is opted into per Pricing, on pricing[].resaleEnabled, and nowhere else: an Offer's full price can be resellable while its student price is not. The field exists only on the pricings of a TICKET Offer — a product is never resellable, and a Bundle is a way to buy rather than something that circulates on a resale market. What a Bundle pricing opens is visible on its Ticket components, where that same pricingId comes back with resaleEnabled: true.

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.