Custom applications

SeatLayer is designed to sit inside an existing application rather than replace it. Use the browser SDK for interactive inventory and the HTTP API from any trusted server runtime.

Reference architecture

Your frontend
  ├─ SeatPicker or SeatingChart
  ├─ your cart, account and checkout UI
  └─ your analytics adapter
          │
          │ holdId
          ▼
Your backend
  ├─ your authentication and authorization
  ├─ your order + payment services
  ├─ SeatLayer HTTP adapter (secret key)
  └─ signed webhook receiver
          │
          ▼
SeatLayer charts, events and live inventory

Only the browser SDK needs DOM access. The server integration is standard HTTPS, so it works in Node, Bun, Deno, PHP, Ruby, Python, Go, Java, .NET, Workers, and other environments that can send authenticated requests.

Keep the integration boundary small

Create one server module responsible for:

• loading and validating the SeatLayer secret key;
• building the API base URL for the current environment;
• inspecting a hold;
• booking with a stable bookingRef;
• cancelling or changing server-managed inventory;
• normalizing errors into your application’s domain errors; and
• attaching request ids to logs without recording secrets.

const apiBase = "https://api.seatlayer.io";

async function seatLayerRequest(path: string, init: RequestInit = {}) {
  const response = await fetch(`${apiBase}${path}`, {
    ...init,
    headers: {
      authorization: `Bearer ${process.env.SEATLAYER_SECRET_KEY}`,
      "content-type": "application/json",
      ...init.headers,
    },
  });

  const body = await response.json().catch(() => null);
  return { ok: response.ok, status: response.status, body };
}

export function inspectHold(eventKey: string, holdId: string) {
  return seatLayerRequest(
    `/v1/events/${encodeURIComponent(eventKey)}/holds/${encodeURIComponent(holdId)}`,
  );
}

export function bookHold(
  eventKey: string,
  input: { holdId: string; bookingRef: string },
) {
  return seatLayerRequest(
    `/v1/events/${encodeURIComponent(eventKey)}/book`,
    { method: "POST", body: JSON.stringify(input) },
  );
}

Wrap this module in your existing service, dependency-injection, tracing, and test conventions. Do not spread direct SeatLayer calls across route handlers.

Define the browser-to-server contract

Your checkout route needs an opaque hold id and your own application context:

type SeatCheckoutRequest = {
  eventKey: string;
  holdId: string;
  cartId: string;
};

eventKey may instead come from a trusted product record or route parameter. Never accept buyer-supplied price, currency, category, or labels as the booking authority.

Connect any frontend

Send analytics anywhere

SeatPicker.onAnalytics is a callback, not a SeatLayer analytics destination. Forward supported events to the system your application already uses:

const picker = new seatlayer.SeatPicker({
  container: "#picker",
  event: "ev_9f3a",
  onAnalytics: (event, properties) => {
    // PostHog
    posthog.capture(`seatlayer_${event}`, properties);

    // Or Google Analytics:
    // gtag("event", `seatlayer_${event}`, properties);

    // Or your own endpoint:
    // navigator.sendBeacon("/analytics", JSON.stringify({ event, properties }));
  },
});

The currently emitted event names cover the 3D buyer journey and are marked Preview in the analytics reference. A throwing sink does not break the picker, but your adapter should still be defensive and avoid sending personal data accidentally.

Adapt errors into product behavior

Keep raw provider errors in structured server logs and return stable, buyer-appropriate application errors to the client.

Test without real dependencies

Inject the HTTP transport or mock your server adapter at its boundary. Cover:

1. successful hold inspection and booking;
2. expired or missing hold;
3. payment rejection before booking;
4. atomic booking conflict;
5. booking timeout followed by same-reference retry;
6. webhook duplicate delivery;
7. missing or wrong-mode credentials; and
8. browser cleanup during navigation.

An end-to-end test in SeatLayer test mode should complement—not replace—these fast contract tests.

Production checklist

• SDK code runs client-side and is destroyed on unmount.
• A single server adapter owns API calls and secret loading.
• Browser payloads contain no trusted price or booking authority.
• HTTP errors are mapped to stable product states.
• Checkout retries reuse the existing order id.
• Analytics forwards only intended, non-sensitive properties.
• Unit, contract, and test-mode end-to-end paths pass.
• Framework upgrades cannot silently duplicate picker instances.

Continue with install the Buyer SDK, integrate a ticketing backend, or build with agents.