Skip to content

About

SeatLayer Ruby SDK for reserved seating: seat booking, holds, events, season tickets and webhook verification from your Ruby backend, with retries and idempotency built in.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

69 Commits

Folders and files

Repository files navigation

SeatLayer Ruby Server SDK for Reserved Seating

CI Gem Ruby License: MIT

The official Ruby client for the SeatLayer API. The seatlayer gem lets a Ruby or Rails backend inspect seat holds, price orders from server data, book reserved seats and verify webhooks, with no runtime dependencies. SeatLayer is seating chart and reserved-seat ticketing software built for venues up to stadium scale.

SeatLayer's official Ruby server SDK is the trusted side of its reserved seating and seat booking API. Inspect what a hold really contains, price from server-owned seating-chart data, and book with a stable booking_ref, while managing charts, events, inventory, allocations, and webhooks through one typed ticketing API client.

seatlayer gem on RubyGems · Ruby server SDK guide · SeatLayer developer platform · SeatLayer JavaScript seat map SDK · Server API reference

Server-side only. This gem authenticates with your secret key. Never load it anywhere a ticket buyer can reach. Browser surfaces get short-lived, origin-bound tokens that you mint here.

How it works: the buyer picks and holds seats in your website or app with your public key. Your server then reads the hold, takes the payment through your own provider, and books the seats with this SDK and your secret key.

Start here: Quickstart · Holds and checkout · Ruby server SDK guide · SDK catalog · Pricing: 100 sold seats free every month, then 10¢ down to 5¢ per sold seat. No subscription, and purchased credits never expire. Test mode is free.

Scale evidence

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. Tested at 10,000 simulated concurrent buyers on one 12,000-seat event (18 September 2026): engine-side hold latency p99 9 ms, zero server errors. Method, fixtures and run files: https://github.com/seatlayer/seatlayer-performance. Live 200,000-seat stadium demo: https://app.seatlayer.io/demo/play/century-stadium-200k.

Install the Ruby seat booking SDK

gem "seatlayer"
gem install seatlayer

Requires Ruby 3.0 or newer. No runtime dependencies: net/http, json and openssl from the standard library.

Quick start

require "seatlayer"

client = SeatLayer::Client.new(ENV.fetch("SEATLAYER_SECRET_KEY"))

# 1. Provision a venue for a new organiser from a public template.
# Replace this placeholder with a template id from your catalog.
chart = client.templates.instantiate_template("your-published-template")["meta"]
client.charts.publish(chart["id"])

# 2. Create an event on it.
event = client.events.create(
  chart_id: chart["id"], name: "Spring Gala",
  currency: "EUR", # omit to inherit the workspace currency
  region: "western-europe" # India: "asia-pacific"
)["meta"]

# 3. Sell four seats over the phone.
held = client.inventory.hold_best_available(event["key"], qty: 4)
# … take payment against held["items"], which carry authoritative prices …
client.inventory.book(event["key"], hold_id: held["holdId"], booking_ref: "order-8842")

Event hosting region

Pass region: to events.create 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. Omit it to inherit the workspace default (western-europe for new accounts). Set that default with workspaces.create(default_region: ...) or workspaces.update(workspace_id, default_region: ...); changing it affects only future Events.

  • western-europe, eastern-europe, north-america-east, north-america-west, south-america
  • asia-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.

Nullable event-create fields distinguish omission from an explicit reset: passing, for example, venue: nil sends JSON null; leaving venue out sends no field.

Fixed Renewable Seasons

client.seasons has all 90 season operations: seasons and their packages, dates and package prices (per price type, set with "priceTypeKey": adult, child, concession, senior or student), sales windows, checkout tests, buyer sessions and booking, holder imports and the holder list, season orders, renewals (offers, quotes, intents, checkouts and hosted renewal links), date changes and cancellations, season seats, bulk refunds with their jobs, sales and seat reports, CSV exports, audit and support export. The bulk refund of a cancelled date is refund_season_performance, the release of lapsed renewal offers is release_season_lapsed_offers, and their jobs are read with list_season_bulk_jobs and retrieve_season_bulk_job.

Above 100 contracts, create_season_renewal_offers answers 202 with {"job", "batchId"} instead of the offers: follow the renewal_run job with retrieve_season_bulk_job, then page the offers with list_season_renewal_offers (cursor: and limit:, until nextCursor is nil). A bring-across of more than 100 holders (create_season_holder_import_from_season) answers 202 with a holder_import job the same way.

Before you open sales, run one test hold, booking and cancellation with their webhooks, then call validate_season_buyer_rehearsal(season_key). It finds those test records itself, so it takes no body. With your own checkout, until a test like this or a checkout test has passed, opening sales answers with a checkout_test_missing warning. A season hold lists each date's seat, category and quantity but no price: when you run your own checkout, you set the package price and take the payment, and you issue the tickets.

checked = client.seasons.validate_season(
  source_performance_group_keys: ["pg_subscription_run"]
)
draft = client.seasons.create_season(
  name: "2027 subscription",
  source_performance_group_keys: ["pg_subscription_run"],
  idempotency_key: "season-create-2027"
).fetch("season")

A 202 answer means the work was accepted and is still running: keep the returned operation id and poll retrieve_season_lifecycle until it finishes. Bookings, cancellations and renewal commits are sent once and never retried by the SDK, so give each one your own stable id; sending the same id again is safe. A buyer session is sent once too, and repeating it is not safe: if its answer is lost, revoke what was created and create one new session.

When SeatLayer takes the Season's payments, renew a holder with no hosted page: read the price, start a checkout, and send the holder to payment.url. For a renewal taken by phone or at the box office, create_season_renewal_intent records the holder's intent before you commit the offer. A decline can carry the holder's reason.

quote = client.seasons.retrieve_season_renewal_quote(season_key, offer_id)
if quote["problem"].nil?
  started = client.seasons.create_season_renewal_checkout(
    season_key, offer_id,
    return_url: "https://tickets.yourclub.example/renewed",
    idempotency_key: "renew-#{offer_id}"
  )
  redirect_to started.dig("payment", "url")
end

client.holders.decline_holder_renewal_offer("holder_123", offer_id, reason: "Moving away")

Season seats

Season seats are the seats a season sets aside on every date before its sales open. A season buyer's hold then doesn't have to ask each date, and single-ticket buyers see those seats as unavailable. They are off for every season until you pass inventory_mode: "block" to create_season or update_season. The season needs one package, and its sales must not have opened.

client.seasons.update_season(season_key, expected_revision: revision, inventory_mode: "block")

job = client.seasons.set_aside_season_block(
  season_key,
  expected_revision: revision,
  keep_for_single_tickets: { "sectionIds" => ["sec_family"] }
).fetch("job")
while %w[planning running].include?(job["state"])
  sleep 2
  job = client.seasons.retrieve_season_bulk_job(season_key, job["jobId"]).fetch("job")
end
block = client.seasons.retrieve_season_block(season_key).fetch("block")

# Release unsold season seats to single sale. Leave out at: to release now.
client.seasons.release_season_block(
  season_key,
  expected_revision: block["revision"],
  scope: { "all" => true },
  at: "2026-12-01T09:00:00Z"
)
  • On an active season, block mode turns on by itself once every date has the seats, and season.block.ready is sent once. On a draft, publish_season turns it on. season.block.released is sent once a release has run.
  • In block mode, a date cancel (create_season_amendment, kind "cancel") or mark_season_performance_past first takes the date off every season seat. Until that finishes the answer is a 202: check it with SeatLayer::Seasons.date_leave_pending?(answer), then send the same request again after Retry-After.
  • Refusals come through SeatLayer::APIError with code, and nothing changes. For example 409 season_block_packages (more than one package), 409 season_block_on_sale (sales have opened), or 409 block_not_ready from open_season_sales before block mode is on.
  • A partner's seat on a date (one a sales channel sells there) stays out of the block. It is listed in block["notFreeOnEveryDate"] with reason channel.

The Season seats docs list every refusal.

Orders, holders, event sales and event series

client.orders reads, exports, refunds and cancels the orders SeatLayer took through its own checkout; client.holders covers Season holders, customers, their tickets and ticket transfers; the event sales settings (who takes payment, gateway, booking fee, sales state, discount codes) are on client.events; and client.event_series plans many dates of one show from a schedule. The CSV exports return the raw CSV text, not a Hash.

page = client.orders.list_event_orders(event_key, status: "confirmed", limit: 50)
csv = client.orders.export_event_orders_csv(event_key, status: "confirmed") # a String
client.orders.refund_event_order(event_key, order_id, amount_minor: 1500)

client.events.transition_event_sales(event_key, to: "live", expected_revision: 4)
client.event_series.create_event_series(
  name: "Hamlet", chart_key: chart_key, dry_run: true,
  schedule: { "rule" => "weekly", "from" => "2027-01-04", "count" => 6, "times" => ["19:30"] }
)

Test vs live

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, surfaced as AuthError with mode_mismatch?.

client = SeatLayer::Client.new(ENV.fetch("SEATLAYER_SECRET_KEY"))
raise "Refusing to boot production against test-mode seating data." if
  ENV["RAILS_ENV"] == "production" && client.mode != "live"

A publishable pk_ key is rejected at construction with a message naming the mistake, rather than failing as a 401 three round-trips later.

Book reserved seats from Ruby

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: retrieve_hold is authoritative.

hold = client.inventory.retrieve_hold(event_key, hold_id)
currencies = hold["items"].map { |item| item.fetch("currency") }.uniq
raise "A hold must use one currency" unless currencies.one?

currency = currencies.first
total = hold["items"].sum do |item|
  item.fetch("unitPrice") * item.fetch("quantity", 1)
end
# … charge `total` in `currency` …
client.inventory.book(event_key, hold_id: hold_id, booking_ref: 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.
client.inventory.book_best_available(event_key, qty: 2, booking_ref: "phone-1183")

# Or name the seats yourself.
client.inventory.box_office_book(event_key, labels: ["A-1", "A-2"], booking_ref: "comp-14")

Private and partner sales

Channels split event inventory into explicit allocations. A channel id is reporting/routing metadata, not browser authority. Authenticate the buyer in your backend and mint a short-lived token restricted to the event, origin, and allowed allocations:

access = client.channels.create_buyer_access_session(
  event_key,
  channel_ids: ["chn_partner_a"],
  include_public: false,
  allowed_origin: "https://tickets.example"
)
# Return access["token"] to the in-memory buyerAccessTokenProvider only.

Never log or persist the returned bse_… bearer. Allocation setup, previews, pause/archive controls, audit-safe session listing, and channel reports are on client.channels.

Listing and pagination

list returns one page plus a nextCursor. list_all pages for you and returns a lazy Enumerator when no block is given, because the point of paginating is to not hold an unbounded result set in memory, so .lazy.first(n) stops fetching once it has enough.

# One page, your own paging.
page = client.events.list(limit: 50)
page["events"]
page["nextCursor"]   # nil once exhausted

# Or let the SDK walk it.
client.events.list_all do |event|
  sync(event)
end

# Lazily: this fetches one page, not all of them.
client.charts.list_all.lazy.first(5)

Listing events includes live availability counts by default, which costs the server one round-trip per event. list_all turns them off automatically, since walking a whole catalogue is exactly when you don't want that, and you can control it explicitly:

client.events.list(limit: 50, counts: false)

Pass series_key: "ser_1" to list only the dates of one event series.

Keeping a hold alive

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.

begin
  client.inventory.extend_hold(event_key, hold_id, ttl_ms: 10 * 60_000)
rescue SeatLayer::ConflictError
  # Gone, expired, or at its renewal cap: the buyer has to re-pick.
end

Embedding the control room

Your secret key never reaches a browser. Mint a scoped token instead.

session = client.sessions.create_manage_session(
  event_key,
  allowed_origin: "https://box-office.yourplatform.com",
  capabilities: ["event:view", "event:block"],
  expires_in_seconds: 3600
)

capabilities is required by this SDK even though the raw API safely defaults an omitted list to view-only (event:view). Keeping the argument required makes browser authority visible at every call site. Grant the smallest set the page needs.

The full set, all opt-in:

Capability Grants
event:view Read the seat map and its live states
event:block Block and unblock seats
event:cancel Cancel a booking by its reference and put the seats back on sale; refunds nobody
event:reports Read sales and availability reports
event:channels:view Read sales channels and their allocations
event:channels:manage Create, pause and archive channels; rotate access links
event:orders:read Read the orders SeatLayer's checkout took
event:refund Refund an order SeatLayer's checkout took, through its payment gateway
event:tickets:send Send the tickets of an order SeatLayer's checkout took
event:door:view Read the door list
event:door:checkin Check tickets in and out
event:boxoffice Use SeatLayer's box office screen

The two event:channels:* capabilities are not in the default (a token minted before sales channels existed must not silently acquire channel authority), so ask for them explicitly if the page manages channels.

Designer minting returns the API envelope unchanged: read the token and effective safe-mode and feature policy under result["session"]. Pass safe_mode_options only with mode: "safe".

Webhooks

Subscription responses use the wire envelopes exactly: list returns {"subs" => [...]}, create returns {"sub" => ..., "secret" => ...} (the secret is shown once), and update returns {"sub" => ...}. SeatLayer::Webhooks::EVENT_NAMES lists every event name this version accepts; delivery history accepts limit, status ("ok" or "failed"), and before.

Verify every delivery against the raw body. Re-encoding a parsed Hash changes the bytes and verification will fail.

# Rails
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def seatlayer
    event = SeatLayer::Webhook.verify(
      request.raw_post,                          # raw body, never params
      request.headers["X-SeatLayer-Signature"],
      ENV.fetch("SEATLAYER_WEBHOOK_SECRET")
    )

    # 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.
    return head :ok if already_processed?(event["occurrenceId"])

    Handler.call(event)
    head :ok
  rescue SeatLayer::WebhookVerificationError
    head :bad_request
  end
end

Errors

begin
  client.inventory.hold_best_available(event_key, qty: 6)
rescue SeatLayer::ConflictError => e
  return show_alternative_dates if e.sold_out?   # a business outcome, not a bug
  raise
rescue SeatLayer::RateLimitError => e
  return retry_after(e.retry_after)
rescue SeatLayer::AuthError => e
  raise "Test key pointed at a live event, or the reverse." if e.mode_mismatch?
  raise
end
Class 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 retry_after
ConnectionError none No answer: DNS, TLS, socket, timeout

All descend from SeatLayer::Error, so rescue SeatLayer::Error catches everything. Every API error carries status, code, body and request_id. Quote the request id in support requests.

Reliability

Retries. Reads (GET/HEAD) retry 429, 408 and 5xx with exponential backoff and full jitter; Retry-After wins when the server sends it. Forty-one mutations use exact header replay:

  • charts.create, charts.copy, templates.instantiate_template, events.create, workspaces.create, and performance_groups.create;
  • 26 on seasons: create_season, update_season, delete_season, create_season_plan, update_season_plan, delete_season_plan, publish_season, duplicate_season_to_live, create_season_holder_import, create_season_holder_import_from_season, create_season_renewal_offers, create_season_amendment, create_season_performances, attach_season_performances, delete_season_performance, create_season_checkout_test, replace_season_package_prices, attach_season_plan_performance, delete_season_plan_performance, mark_season_performance_past, refund_season_order, cancel_season_order, cancel_season_order_date, refund_season_performance, release_season_lapsed_offers, and create_season_renewal_checkout;
  • holders.update_holder, holders.create_holder_transfer, holders.create_holder_return, and holders.create_holder_renewal_checkout;
  • orders.refund_event_order and orders.cancel_event_order;
  • event_series.create_event_series, event_series.add_event_series_dates, and event_series.update_event_series.

Other 4xx responses are never retried.

Idempotency. Those 41 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 request mutations. Keep booking_ref in the booking body for reconciliation, but handle an unknown network outcome explicitly instead of automatically repeating the sale.

client.events.create(chart_id: chart_id, idempotency_key: "provision-event-#{event_id}")
SeatLayer::Client.new(
  ENV.fetch("SEATLAYER_SECRET_KEY"),
  max_retries: 3,   # total attempts
  timeout: 30.0     # seconds, per attempt
)

Escape hatch

For surface this SDK does not wrap yet, request 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.request("POST", "/v1/events/ev_1/some-new-route", body: { "qty" => 2 })

API surface

The client exposes these resources. Performance Groups cover runs, sessions, holds, and bookings; Seasons cover catalogue, plan, sales, buyer-session, booking, renewal, occurrence, reporting, outbox, and support operations.

Resource Methods
charts list list_all create retrieve update delete copy archive unarchive publish
templates instantiate_template
events list list_all create retrieve retrieve_configuration_binding update_configuration_binding update delete update_poster delete_poster update_chart close reopen archive retrieve_hold_ttl update_hold_ttl list_ticket_releases update_ticket_releases close_ticket_release retrieve_report retrieve_log retrieve_event_buyer_checkout replace_event_buyer_checkout retrieve_event_payment_gateway replace_event_payment_gateway retrieve_event_sales_readiness preflight_event_sales transition_event_sales retrieve_event_booking_fee replace_event_booking_fee list_event_discount_codes create_event_discount_code update_event_discount_code end_event_discount_code delete_event_discount_code
inventory hold hold_best_available book_best_available extend_hold retrieve_hold release book box_office_book unbook list_bookings retrieve_booking block unblock unblock_all retrieve_availability update_availability
channels list_channels create_channel update_channel update_assignments list_allocation retrieve_access_preview retrieve_report pause unpause archive create_buyer_access_session list_buyer_access_sessions revoke_buyer_access_session create_access_link list_access_links rotate_access_link revoke_access_link
sessions create_manage_session revoke_manage_session create_designer_session revoke_designer_session
webhooks list create update delete list_deliveries
workspaces list create retrieve update
performance_groups list create retrieve delete activate close retrieve_lifecycle create_buyer_access_session list_buyer_access_sessions revoke_buyer_access_session retrieve_hold book_hold retrieve_booking
seasons 90 operations for catalogue and Plan lifecycle, performances, package prices, checkout tests, sales windows, buyer access and booking, holder imports, holders, renewals, renewal quotes and checkouts, occurrence amendments, returns and reclaims, Season orders, bulk refunds, lapsed-offer releases and jobs, reports and CSV exports, audit, outbox, and support export
holders list_customers retrieve_holder update_holder revoke_holder_sessions list_holder_seasons list_holder_tickets retrieve_holder_ticket create_holder_transfer list_holder_transfers cancel_holder_transfer accept_holder_transfer create_holder_return create_holder_renewal_checkout decline_holder_renewal_offer
orders list_orders retrieve_order list_order_tickets list_event_orders retrieve_event_order export_event_orders_csv refund_event_order cancel_event_order resend_event_order_tickets
event_series create_event_series list_event_series retrieve_event_series add_event_series_dates update_event_series

Full reference: SeatLayer Ruby server SDK guide

Deliberately not in this SDK

Some API surface is intentionally unwrapped, not merely pending:

  • Payment gateways. A gateway is set up in the SeatLayer dashboard, not through this SDK. Once it is set up, events.replace_event_payment_gateway assigns it to an event.
  • Realtime seat updates. Live seat changes reach buyers through the seat map itself. There is no server-side live feed; a server reads the current state with events.retrieve_report and inventory.retrieve_availability.

Neither of these two (setting up a gateway, a server-side live feed) is part of the public API, so request does not support them either.

Frequently asked questions

How do I book seats from Ruby?

Create a client with your secret key, obtain a hold id (either from the buyer's browser session or by holding server-side) and call inventory.book(event_key, hold_id: ..., booking_ref: ...). booking_ref is your own stable order id and is the join between SeatLayer inventory and your commercial order, so the same reference identifies the booking in Booking History and when you later cancel it. For phone orders, box office, and comps, inventory.book_best_available books outright with no browser involved.

What does the server SDK do compared with the buyer SDK?

The buyer SDK runs where the ticket buyer is: it renders the interactive seating chart, handles seat selection, and creates temporary holds. This server SDK is the trusted side. It authenticates with your secret key, inspects what a hold actually contains, prices from server-owned data, and books. Never bundle the secret key into a browser or a mobile app. Browser surfaces get short-lived, origin-bound tokens that you mint here.

How do temporary holds work server-side?

A hold reserves seats against concurrent buyers for a limited window. inventory.retrieve_hold(event_key, hold_id) is the authoritative answer for what is held and at what price, so charge from its items rather than from anything the browser sent you. When an order runs longer than the checkout window, inventory.extend_hold renews the hold instead of releasing and re-holding, which would hand the seats to whoever is racing for them. Bookings carry the server's exact-selection plus booking_ref safeguard, but the SDK sends each booking once; reconcile an unknown outcome before trying again.

Can I use my own payment provider?

Yes. Nothing in this SDK takes a payment: your server charges the hold's total through the provider you already use, then books the seats with your order id as booking_ref, and SeatLayer never touches the money. If you would rather SeatLayer run the checkout for an event (events.replace_event_buyer_checkout), buyers pay through one of 14 payment gateways, including Stripe, PayPal and Square, straight into your own account.

Continue your Ruby integration

Other SeatLayer SDKs

Surface Package or source
JavaScript @seatlayer/js
React @seatlayer/react
React Native @seatlayer/react-native
iOS seatlayer-ios
Flutter seatlayer
Android seatlayer-android
Node.js (server) @seatlayer/server
Python (server) seatlayer
PHP (server) seatlayer/seatlayer-php
Ruby (server) seatlayer (this package)
.NET (server) SeatLayer
Java (server) io.seatlayer:seatlayer-java
Go (server) github.com/seatlayer/seatlayer-go

Development

bundle install
bundle exec rubocop
bundle exec rspec

License

MIT

About

SeatLayer Ruby SDK for reserved seating: seat booking, holds, events, season tickets and webhook verification from your Ruby backend, with retries and idempotency built in.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages