SeatLayer is interactive seating chart software built for stadium scale. Platforms embed the white-label seat picker with their own checkout; organizers sell seated events on their own website with their own payment gateway.
SeatLayer's official Go server SDK is the trusted side of its reserved seating and seat
booking API: inspect the holds a buyer created, price from server data, and book with a stable
BookingRef. From Go you manage seating charts, events, sales channels, and live seat inventory
through one typed ticketing API client.
SeatLayer module on pkg.go.dev · Go server SDK guide · SeatLayer developer platform · SeatLayer JavaScript seat map SDK · Server API reference
Server-side only. This package authenticates with your secret key. Never embed it in anything a ticket buyer can reach. Browser surfaces get short-lived, origin-bound tokens that you mint here.
Two-step shape: the buyer picks and holds seats in the client with your public key, then this SDK confirms the booking from your server with your secret key while your platform keeps checkout and its own payment provider.
Start here: Quickstart · Holds and checkout · Go server SDK guide · SDK catalog · Pricing: $0 entry, 100 free confirmed-sold-seat credits per organization each month, then $0.10 down to $0.05 a credit, and credits never expire.
Benchmarked on public 100,000-, 150,000- and 200,000-seat venue fixtures on 15 September 2026: 200,000 seats chart-ready in 1.95 s, desktop, local production build. Fixtures, method and run logs: https://github.com/seatlayer/seatlayer-performance. Live 200,000-seat stadium demo: https://app.seatlayer.io/demo/play/century-stadium-200k. This is renderer evidence, not a concurrent-buyer claim.
go get github.com/seatlayer/seatlayer-go@v0.7.0The module resolves straight from this repository through the Go module proxy, so there is no
registry account to create; v0.7.0 is the current release and the API reference is published on
pkg.go.dev. Requires Go 1.23 or newer (for range-over-func iterators). No dependencies — standard library
only.
import (
"context"
"os"
"github.com/seatlayer/seatlayer-go"
)
client, err := seatlayer.New(os.Getenv("SEATLAYER_SECRET_KEY"))
if err != nil {
return err
}
ctx := context.Background()
// 1. Materialize a published catalog template as the organiser's draft chart.
// Replace this placeholder with a template id from your catalog.
chart, err := client.Templates.InstantiateTemplate(ctx, "your-published-template")
if err != nil {
return err
}
chartID := chart["meta"].(map[string]any)["id"].(string)
if _, err := client.Charts.Publish(ctx, chartID); err != nil {
return err
}
// 2. Create an event on it.
event, err := client.Events.Create(ctx, seatlayer.EventCreateParams{
ChartID: chartID,
Name: "Spring Gala",
Currency: "EUR", // leave empty to inherit the workspace currency
Region: seatlayer.RegionWesternEurope, // India: RegionAsiaPacific
})
if err != nil {
return err
}
eventKey := event["meta"].(map[string]any)["key"].(string)
// 3. Sell four seats over the phone.
held, err := client.Inventory.HoldBestAvailable(ctx, eventKey, seatlayer.BestAvailableParams{Qty: 4})
if err != nil {
return err
}
// … take payment against held["items"], which carry authoritative prices …
_, err = client.Inventory.Book(ctx, eventKey, seatlayer.BookParams{
HoldID: held["holdId"].(string),
BookingRef: "order-8842",
})Set EventCreateParams.Region based on the event venue, not your API server or office. It
controls the initial placement of the Event's live inventory; an existing Event
cannot be moved later. Leave it empty to inherit the workspace default (western-europe for new accounts).
Set the default through WorkspaceCreateParams.DefaultRegion or
UpdateWithParams(..., WorkspaceUpdateParams{DefaultRegion: ...}); updates affect only future Events.
western-europe,eastern-europe,north-america-east,north-america-west,south-americaasia-pacific,northeast-asia,southeast-asia,oceania,africa,middle-east
The hint is best effort, not a data-residency guarantee. See the full Event region guide.
For nullable event-create fields, ordinary scalar fields cover the common value-or-omit case. Use
the Nullable overlay when the wire call must contain an explicit JSON null, for example
Nullable: seatlayer.EventCreateNullableFields{Venue: seatlayer.FieldNull[string]()}.
Every method takes a context.Context. Cancelling it stops retries immediately rather than being
treated as a transient fault to back off through.
Version v0.7.0 exposes all 48 trusted organizer operations through
client.Seasons.
After the test hold/book/cancel journey and matching webhook deliveries,
client.Seasons.ValidateBuyerRehearsal(ctx, seasonKey) sends no evidence body;
SeatLayer discovers the retained chain automatically. Retrieved Season holds
contain inventory identity, not an authoritative amount—your platform owns
package price, payment, order, tax, refunds, benefits, and ticket or pass delivery.
checked, err := client.Seasons.Validate(ctx, seatlayer.SeasonSelectionParams{
SourcePerformanceGroupKeys: []string{"pg_subscription_run"},
})
created, err := client.Seasons.Create(ctx, seatlayer.SeasonCreateParams{
Name: "2027 subscription",
SourcePerformanceGroupKeys: []string{"pg_subscription_run"},
IdempotencyKey: "season-create-2027",
})Treat 202 as accepted work and poll RetrieveLifecycle with the returned
operation identity. Buyer-session minting and domain-exact booking,
cancellation, and renewal actions remain single-attempt; only declared
header-replay catalogue mutations retry automatically.
Keys carry their own mode. sk_test_… keys can only touch test-mode events and sk_live_… only
live ones; crossing them returns 403 mode_mismatch.
client, err := seatlayer.New(os.Getenv("SEATLAYER_SECRET_KEY"))
if err != nil {
return err
}
if os.Getenv("ENV") == "production" && client.Mode() != "live" {
return errors.New("refusing to boot production against test-mode seating data")
}A publishable pk_ key is rejected by New with a message naming the mistake, rather than
failing as a 401 three round-trips later.
Buyer picks seats in the browser. Your frontend holds them; your backend confirms the price and
books. Never price from what the browser sent you — RetrieveHold is authoritative.
import "errors"
hold, err := client.Inventory.RetrieveHold(ctx, eventKey, holdID)
if err != nil {
return err
}
if len(hold.Items) == 0 {
return errors.New("hold has no items")
}
currency := hold.Items[0].Currency
total := 0.0
for _, item := range hold.Items {
if item.Currency != currency {
return errors.New("a hold must use one currency")
}
quantity := 1
if item.Quantity != nil {
quantity = *item.Quantity
}
total += item.UnitPrice * float64(quantity)
}
// … charge `total` in `currency` …
_, err = client.Inventory.Book(ctx, eventKey, seatlayer.BookParams{
HoldID: holdID, BookingRef: charge.ID,
})Your backend picks the seats. Phone orders, box office, comps.
// Payment already taken — book outright, so nothing is stranded if a second call fails.
_, err := client.Inventory.BookBestAvailable(ctx, eventKey, seatlayer.BestAvailableParams{
Qty: 2, BookingRef: "phone-1183",
})
// Or name the seats yourself.
_, err = client.Inventory.BoxOfficeBook(ctx, eventKey, []string{"A-1", "A-2"}, "comp-14")Channels reserve inventory for a partner, member group, presale, or other private allocation. A buyer access session is short-lived and origin-bound, so the browser receives only the allocation it is allowed to sell; your secret key remains on your server.
_, err := client.Channels.CreateChannel(ctx, eventKey, seatlayer.ChannelCreateParams{
Name: "Venue members",
AccessIntent: "private",
})
_, err = client.Channels.UpdateAssignments(ctx, eventKey, seatlayer.ChannelAssignmentParams{
Labels: []string{"A-1", "A-2"},
AssignmentVersion: 1,
TargetChannelID: "ch_members",
})
access, err := client.Channels.CreateBuyerAccessSession(ctx, eventKey,
seatlayer.BuyerAccessSessionParams{
ChannelIDs: []string{"ch_members"},
IncludePublic: false,
AllowedOrigin: "https://members.example",
MaxQuantity: 2,
})Pass the returned token to the buyer SDK. Trusted backend sale params accept ChannelIDs, an
explicit privileged IgnoreChannelRestrictions flag, and an audit Reason.
List returns one Page plus a cursor. All is a range-over-func iterator that pages as you
consume it — deliberately not a slice, because the point of paginating is to not hold an
unbounded result set in memory.
// One page, your own paging.
page, err := client.Events.List(ctx, &seatlayer.EventListParams{Limit: 50})
page.Items
page.NextCursor // "" once exhausted
// Or let the SDK walk it.
for event, err := range client.Events.All(ctx, nil) {
if err != nil {
return err
}
sync(event)
}The error rides alongside each item so a failed page reaches you — an iterator that silently ended on error would look identical to a list that finished.
Listing events includes live availability counts by default, which costs the server one round-trip
per event. All drops them automatically — walking a whole catalogue is exactly when you don't
want that — and you can control it explicitly:
client.Events.List(ctx, &seatlayer.EventListParams{Limit: 50, NoCounts: true})When an order takes longer than the checkout window — an invoice, a phone sale — extend rather than release and re-hold. Releasing first hands the seats to whoever is racing for them in between.
_, err := client.Inventory.ExtendHold(ctx, eventKey, holdID, 10*60*1000)
var conflict *seatlayer.ConflictError
if errors.As(err, &conflict) {
// Gone, expired, or at its renewal cap — the buyer has to re-pick.
}Your secret key never reaches a browser. Mint a scoped token instead.
session, err := client.Sessions.CreateManageSession(ctx, eventKey, seatlayer.ManageSessionParams{
AllowedOrigin: "https://box-office.yourplatform.com",
Capabilities: []seatlayer.ManageCapability{
seatlayer.CapabilityView,
seatlayer.CapabilityBlock,
},
ExpiresInSeconds: 3600,
})Capabilities is required by this SDK even though the raw API safely defaults an omitted list
to view-only (event:view). Keeping the field required makes browser authority visible at every
call site. Grant the smallest set the page needs. For Platform/SDK events, event:cancel returns a
booking's inventory to sale but does not move gateway money. The Managed commerce constants cover
eligible Managed Ticketing orders, refunds, ticket delivery, door, and box-office capabilities.
Designer minting returns a DesignerSessionEnvelope; the token and the effective safe-mode and
feature policy live under result.Session. Pass SafeModeOptions only with Mode: "safe".
Webhook methods expose the wire envelopes directly: List returns WebhookList.Subs, Create
returns WebhookCreateEnvelope with the show-once Secret, and Update returns
WebhookEnvelope.Sub. Use the WebhookEvent… constants for the eight accepted event names and
WebhookDeliveryListParams for limit, status, and before filters.
Verify every delivery against the raw body. Decoding and re-encoding changes the bytes — in Go
specifically, encoding/json marshals map keys in sorted order while a real delivery arrives in
the order we serialised it, so a round trip reorders it and verification fails.
func handleWebhook(w http.ResponseWriter, r *http.Request) {
payload, err := io.ReadAll(r.Body) // raw bytes, before any decoding
if err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
event, err := seatlayer.VerifyWebhook(
payload,
r.Header.Get("X-SeatLayer-Signature"),
os.Getenv("SEATLAYER_WEBHOOK_SECRET"),
)
if errors.Is(err, seatlayer.ErrWebhookVerification) {
w.WriteHeader(http.StatusBadRequest)
return
}
// The signed body carries "at", but nothing enforces a freshness window, so a
// captured delivery stays valid indefinitely. Deduplicate on occurrenceId —
// this is your replay protection, not an optimisation.
if alreadyProcessed(event["occurrenceId"].(string)) {
w.WriteHeader(http.StatusOK)
return
}
process(event)
w.WriteHeader(http.StatusOK)
}Errors are values here, not exceptions — reach for errors.As:
_, err := client.Inventory.HoldBestAvailable(ctx, eventKey, seatlayer.BestAvailableParams{Qty: 6})
var conflict *seatlayer.ConflictError
var rateLimit *seatlayer.RateLimitError
var auth *seatlayer.AuthError
switch {
case errors.As(err, &conflict) && conflict.SoldOut():
return offerAlternativeDates() // a business outcome, not a bug
case errors.As(err, &rateLimit):
return retryAfter(rateLimit.RetryAfter)
case errors.As(err, &auth) && auth.ModeMismatch():
return errors.New("test key pointed at a live event, or the reverse")
case err != nil:
return err
}| Type | Status | Means |
|---|---|---|
AuthError |
401, 403 | Bad, revoked, or wrong-mode key |
NotFoundError |
404 | No such resource for this organisation |
ConflictError |
409 | Inventory moved, or a guard rejected the change |
ValidationError |
422 | Understood and rejected |
RateLimitError |
429 | Over budget; carries RetryAfter |
ConnectionError |
— | No answer: DNS, TLS, socket, context deadline (unwraps) |
Every API error carries Status, Code, Body, and RequestID — quote the request id in support
requests.
Retries. Reads (GET/HEAD) retry 429, 408 and 5xx with exponential backoff and full jitter;
Retry-After wins when the server sends it. Fourteen mutations use exact header replay:
Charts.Create, Charts.Copy, Templates.InstantiateTemplate, Events.Create,
Workspaces.Create, PerformanceGroups.Create, Seasons.Create, Seasons.Update,
Seasons.Delete, Seasons.CreatePlan, Seasons.DuplicateToLive, Seasons.CreateHolderImport,
Seasons.CreateRenewalOffers, and Seasons.CreateAmendment. Other 4xx responses are never retried.
Idempotency. Those 14 replay-backed operations carry an Idempotency-Key, generated when you
do not supply one and reused across attempts. All remaining SDK mutations are single-attempt. Some
have a server-side domain idempotency contract, but the SDK does not retry them automatically. This
includes inventory holds and bookings, show-once credential or secret creation, unsupported
operations, and raw Do mutations. Keep BookingRef in the booking body for reconciliation, but
handle an unknown network outcome explicitly instead of automatically repeating the sale.
client.Events.Create(ctx, seatlayer.EventCreateParams{
ChartID: chartID, IdempotencyKey: "provision-event-" + eventID,
})client, err := seatlayer.New(
os.Getenv("SEATLAYER_SECRET_KEY"),
seatlayer.WithMaxRetries(3),
seatlayer.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
)Client is safe for concurrent use.
For surface this SDK does not wrap yet, Do keeps auth and error mapping. Raw reads retain the
read retry policy; raw mutations are always single-attempt because their replay contract is unknown:
client.Do(ctx, http.MethodPost, "/v1/events/ev_1/some-new-route", nil, map[string]any{"qty": 2}, "")The client exposes these services. Performance Groups cover runs, sessions, holds, and bookings; Seasons cover catalogue, plan, sales, buyer-session, booking, renewal, occurrence, reporting, outbox, and support operations.
| Service | Methods |
|---|---|
Charts |
List All Create Retrieve Update Delete Copy Archive Unarchive Publish |
Templates |
InstantiateTemplate |
Events |
List All Create Retrieve RetrieveConfigurationBinding UpdateConfigurationBinding Update Delete UpdatePoster DeletePoster UpdateChart Close Reopen Archive ListTicketReleases UpdateTicketReleases CloseTicketRelease RetrieveHoldTTL UpdateHoldTTL RetrieveReport RetrieveLog |
Channels |
ListChannels CreateChannel UpdateChannel UpdateAssignments ListAllocation RetrieveAccessPreview RetrieveReport Pause Unpause Archive CreateBuyerAccessSession ListBuyerAccessSessions RevokeBuyerAccessSession CreateAccessLink ListAccessLinks RotateAccessLink RevokeAccessLink |
Inventory |
Hold HoldBestAvailable BookBestAvailable ExtendHold RetrieveHold Release Book BoxOfficeBook Unbook Block Unblock UnblockAll RetrieveAvailability UpdateAvailability ListBookings RetrieveBooking |
Sessions |
CreateManageSession RevokeManageSession CreateDesignerSession RevokeDesignerSession |
Webhooks |
List Create Update Delete ListDeliveries |
Workspaces |
List Create Retrieve Update |
PerformanceGroups |
List Create Retrieve Delete Activate Close RetrieveLifecycle CreateBuyerAccessSession ListBuyerAccessSessions RevokeBuyerAccessSession RetrieveHold BookHold RetrieveBooking |
Seasons |
48 operations for catalogue and Plan lifecycle, sales windows, buyer access and booking, holder imports, renewals, occurrence amendments, reports, audit, outbox, and support export |
Full reference: SeatLayer Go server SDK guide
Add the github.com/seatlayer/seatlayer-go module,
construct a client with seatlayer.New and your secret key, and call client.Inventory.Book with
the hold id and a stable BookingRef. When your own backend picks the seats — phone orders, box
office, comps — Inventory.BookBestAvailable and Inventory.BoxOfficeBook book outright with no
prior hold. A booking reference is required on every booking call, so each sale is tied to an
immutable order id you can reconcile against later.
The buyer SDK runs in the browser or mobile app and only selects and holds seats. This Go SDK
runs on your trusted server and inspects and books them. Your secret key never reaches a buyer
surface: browsers receive short-lived, origin-bound tokens minted here through
Sessions.CreateManageSession or Channels.CreateBuyerAccessSession. Always price a sale from
Inventory.RetrieveHold, never from values the browser sent you.
A hold reserves seats against concurrent buyers for a limited checkout window. From Go you
retrieve it with Inventory.RetrieveHold, whose item-level price, quantity, and currency are
authoritative, and confirm it with Inventory.Book. Use Inventory.ExtendHold for a long checkout
instead of releasing and re-holding, which would hand the seats to whoever is racing for them.
Booking is a single automatic attempt: after an unknown network outcome you may reconcile and
repeat the exact same event, hold, and BookingRef — seats already booked under that reference are
not sold again.
Yes. This server SDK does not process payment in a Platform/SDK integration. Charge through the
provider you already use, calculating the total from each server-inspected hold item's
UnitPrice, Quantity, and Currency, then call Inventory.Book with your charge or order id as
the BookingRef. Managed Ticketing is a separate product path with organizer-connected payments.
The holds and checkout guide walks
through the full handoff.
- Follow the Go server SDK guide for installation, authentication, and the full hold-to-booking flow.
- Handle errors, retries, and safe booking repeats before connecting a production order flow.
- Verify SeatLayer webhooks to react to holds, expiry, and bookings on your server.
- Browse the SeatLayer server API reference for every endpoint behind this SDK.
- Generate clients from the SeatLayer OpenAPI description or explore the raw API surface.
- Point AI coding agents at the SeatLayer docs index
(
llms.txt) for an agent-readable map of the documentation. - Explore every SeatLayer SDK on GitHub across web, mobile, and server.
| Surface | Package or source |
|---|---|
| JavaScript | @seatlayer/js |
| React | @seatlayer/react |
| React Native | @seatlayer/react-native |
| iOS | seatlayer-ios |
| Flutter | seatlayer |
| Android | seatlayer-android |
| Server SDKs | Node.js, Python, PHP, Ruby, .NET, Java, and Go |
| Node.js (server) | @seatlayer/server |
| Python (server) | seatlayer |
| PHP (server) | seatlayer/seatlayer-php |
| Ruby (server) | seatlayer |
| .NET (server) | SeatLayer |
| Java (server) | io.seatlayer:seatlayer-java |
| Go (server) | github.com/seatlayer/seatlayer-go (this module) |
gofmt -l . # must be empty
go vet ./...
go test -race ./...MIT