Choose an inventory model

Choose the inventory model before choosing an SDK component. An Event, a Performance Group, and a Fixed Renewable Season solve different concurrency and entitlement problems; they are not three names for the same bundle.

This page owns the decision between inventory models. The child integration guides own complete workflows, buyer pages own UI configuration, and API pages own exact trusted operations. Return to the SeatLayer product model when the open question is commerce ownership, audience access, pricing, or SDK choice instead.

This decision applies to the Platform / SDK product. Your platform keeps buyer identity, pricing, tax, checkout, payment, the commercial order, tickets or passes, refunds, and fulfilment. SeatLayer coordinates seating inventory.

Compare the three models

How the inventory documentation is organized

Choose an Event

Use one Event when the buyer is purchasing one occurrence, such as one match, concert, screening, or performance date.

The buyer SDK creates a temporary hold. Your trusted backend retrieves that hold, calculates the commercial order from trusted data, takes payment under your own rules, and books the inventory with a stable bookingRef.

An Event remains the underlying inventory occurrence even when it later joins a Performance Group or Season. Do not duplicate it merely to build a second buyer journey.

Choose Event when all of these are true:

• one booking affects one dated occurrence;
• the buyer does not need an atomic choice across several dates; and
• no retained same-seat renewal right is required.

Continue with how the Platform flow works and the booking endpoint.

Choose a Performance Group

Use a Performance Group for one fixed multi-performance run of 2–8 compatible Events. The group is an inventory primitive, not a season ticket or commercial package.

The host selects one mode before the picker opens:

• same_seat: the buyer chooses one assigned seat set used for every Event; or
• per_performance: the buyer chooses an equal party size separately for each Event.

The group also stores a server-owned inclusion policy. fixed requires every activated Event. flexible_dates applies to the same_seat flow: when a seat is unavailable on some dates, the buyer may hold it for the dates where it is available. It does not turn the fixed 2–8 Event membership into an arbitrary build-your-own package. per_performance still requires the configured equal party size on every dated tab.

SeatLayer performs one atomic group operation. Do not intersect availability in the browser, issue one independent hold per Event, or attempt to roll back a partially successful loop yourself.

Choose Performance Group when all of these are true:

• the run contains 2–8 compatible Events;
• the offer uses either mandatory fixed inclusion or the explicitly availability-based flexible_dates same-seat policy;
• the purchase must succeed or fail as one inventory action; and
• the buyer receives no durable renewal right.

The REST API supports both inclusion policies. All seven typed server SDK 0.7.0 create methods currently omit the inclusionMode field, so create a flexible_dates group through REST or a raw request until a later typed release adds that field. This is a field-level version boundary, not missing Performance Group operation coverage.

Performance Groups are module-gated. Start with Integrate a Performance Group for the complete backend and buyer handoff, or inspect the Performance Groups server API.

Choose a Fixed Renewable Season

Use a Fixed Renewable Season when a buyer should retain the same assigned seats across an immutable 2–20-Event Plan and may renew those rights into a successor Plan.

The durable model adds concepts that a Performance Group deliberately does not have:

• a Plan fixes occurrence membership and publication identity;
• a Contract records the holder’s Season relationship;
• a Seat Right fences the assigned seat set across the Plan; and
• a Renewal Offer gives that holder a time-bounded path into a successor Plan.

Choose a Season when all of these are true:

• the offer contains 2–20 compatible Events;
• the same assigned seat must be coordinated across every included Event;
• published Plan identity and operational recovery must be retained; and
• incumbent import or future renewal rights are part of the product.

SeatLayer Season holds contain inventory identity, not an authoritative package amount. Your trusted commerce system owns package pricing, payment, the order, benefits, passes or tickets, refunds, and support.

Start with the end-to-end Season integration, then use the Season picker and Seasons API for the two implementation surfaces.

Do not substitute one model for another

• Do not create overlapping Performance Groups to simulate buyer-selectable date bundles.
• Do not call a Performance Group a Season when no Contract, Seat Right, or renewal lifecycle exists.
• Do not model a Season as independent Event holds; partial success would break the same-seat promise.
• Do not treat an inventory booking as proof of payment, a commercial Order, a ticket, a pass, a refund, or attendance.
• Do not send a server secret key to any buyer SDK.

Next decision

After choosing the model:

1. Return to the product model and confirm commerce, access, and SDK boundaries.
2. Choose the product and integration boundary.
3. Install the server SDK for your language.
4. Use test-mode Events and credentials for the full buyer-to-webhook rehearsal.
5. Complete the Platform going-live checklist.