---
title: "Ruby server SDK"
description: "Install the seatlayer 0.7.0 gem, inspect an authoritative hold, book with a stable reference, and use the exact Ruby resource namespaces."
---

Use the `seatlayer` gem from a trusted Ruby backend. Version `0.7.0` requires
Ruby 3.0 or newer and uses `net/http`, `json`, and `openssl` from the standard
library without runtime gem dependencies.

## Install and create the client

```bash
gem install seatlayer -v 0.7.0
```

With Bundler, pin the same version in your `Gemfile`, then run `bundle install`:

```ruby
gem "seatlayer", "0.7.0"
```

```ruby
require "seatlayer"

client = SeatLayer::Client.new(ENV.fetch("SEATLAYER_SECRET_KEY"))
raise "Use a test key while integrating." unless client.mode == "test"
```

Keep `SEATLAYER_SECRET_KEY` in the server environment. Never expose the client
or its `sk_…` credential to browser or mobile code.

## Exact resource surface

The client exposes `charts`, `channels`, `events`, `inventory`,
`performance_groups`, `sessions`, `seasons`, `templates`, `webhooks`, and
`workspaces`.

`client.performance_groups` contains all 13 released operations: `list`,
`create`, `retrieve`, `delete`, `activate`, `close`, `retrieve_lifecycle`,
`create_buyer_access_session`, `list_buyer_access_sessions`,
`revoke_buyer_access_session`, `retrieve_hold`, `book_hold`, and
`retrieve_booking`.

`client.seasons` contains all 48 frozen `0.7.0` operations. Ruby keeps the
Season prefix and uses snake case, for example `create_season`,
`publish_season_plan`, `book_season_hold`, `commit_season_renewal_offer`, and
`export_season_support_snapshot`. The resource covers catalogue, lifecycle,
Plans and sales, buyer handoff, holder import, renewals, amendments, reports,
recovery, outbox, audit, and support export. Source-only occurrence
return/reclaim operations are not part of `0.7.0`.

The same 13 Performance Group and 48 Season wire operations are released in all
seven official server SDKs; only language naming differs.

The `0.7.0` typed `performance_groups.create` keywords cover the default
`fixed` policy but do not expose the newer REST `inclusionMode` field. Use the
[REST/raw-request path](/server-api/performance-groups/#create-a-run) for
`flexible_dates`; the other typed create fields and all 13 operations remain
available.

## Inspect and book an Event hold

```ruby
event_key = ENV.fetch("SEATLAYER_EVENT_KEY")
hold_id = ENV.fetch("SEATLAYER_HOLD_ID")
booking_ref = ENV.fetch("ORDER_ID")

hold = client.inventory.retrieve_hold(event_key, hold_id)
labels = hold.fetch("items").map { |item| item.fetch("label") }
# Price from hold["items"] and authorize payment in your commerce system here.
booking = client.inventory.book(
  event_key,
  hold_id: hold_id,
  labels: labels,
  booking_ref: booking_ref
)
```

Do not calculate a charge from browser-submitted totals. `booking_ref` is your
commerce system's immutable join to SeatLayer inventory. If the response is
lost, call `client.inventory.retrieve_booking(event_key, booking_ref)` before
deciding whether to repeat the exact same hold, labels, and reference.

## Errors, retries, and pagination

Branch on `SeatLayer::AuthError`, `SeatLayer::ConflictError`, and
`SeatLayer::RateLimitError`. Use `mode_mismatch?`, `sold_out?`, and
`retry_after` for those common branches.

Reads retry `408`, `429`, and `5xx` with exponential backoff and full jitter.
These 14 methods also retry with one exact key: `charts.create`, `charts.copy`,
`templates.instantiate_template`, `events.create`, `workspaces.create`,
`performance_groups.create`, and `seasons.create_season`, `update_season`,
`delete_season`, `create_season_plan`, `duplicate_season_to_live`,
`create_season_holder_import`, `create_season_renewal_offers`, and
`create_season_amendment`. Other mutations and raw `request` mutations are
single-attempt.

Large lists can stream through a block:

```ruby
client.events.list_all do |event|
  sync_event(event)
end
```

That block iterator is Event-specific. Performance Group and top-level Season
list methods return one cursor page; pass the response's opaque `nextCursor`
back as `cursor` until it is absent.

Nullable Event fields distinguish omission from an explicit `nil`; consult the
package README before sending a reset. See [errors, retries, and
idempotency](/server-sdk/reliability/) for the shared contract.

## Verify and continue

- [RubyGems package `0.7.0`](https://rubygems.org/gems/seatlayer/versions/0.7.0)
- [tagged source and package README](https://github.com/seatlayer/seatlayer-ruby/tree/v0.7.0)
- [`performance_groups` methods at `v0.7.0`](https://github.com/seatlayer/seatlayer-ruby/blob/v0.7.0/lib/seatlayer/performance_groups.rb)
- [all `seasons` methods at `v0.7.0`](https://github.com/seatlayer/seatlayer-ruby/blob/v0.7.0/lib/seatlayer/seasons.rb)
- [server API operation support](/server-api/operation-support/)
- [OpenAPI 3.1 reference](/openapi.json)

Verify the flow with a test key, a test Event, and a real test hold. Then add
[webhook verification](/server-sdk/webhooks/), choose the correct [inventory
model](/start/inventory-models/), and complete the [going-live
checklist](/start/going-live/).