Integrate a ticketing backend

Use this pattern when you already own the event catalogue, buyer, checkout, payment, commercial Orders, receipts, tickets, delivery, scanning, and refunds. SeatLayer owns live inventory. The buyer/server handoff is holdId; your stable bookingRef links the resulting inventory booking to your commercial order.

The transaction boundary

The browser must not post trusted prices, seat labels, or a booking request. Those values either come from hold inspection or are owned by your server.

Implement the flow

1. Create and hand off the hold

With the headless chart, call hold() after selection:

const chart = new seatlayer.SeatingChart({
  container: "#chart",
  event: "ev_9f3a",
  publicKey: "pk_test_…", // ordinary Public Platform sale
  onHold: async ({ holdId, expiresAt }) => {
    await fetch("/api/checkout/start", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ holdId, expiresAt }),
    });
  },
});

await chart.render();
await chart.hold();

For a scoped private audience, replace publicKey with a server-backed buyerAccessTokenProvider. The hold and booking boundary does not change.

SeatPicker performs the hold as part of its CTA and exposes the same boundary through onCheckout(_, _, handoff). Prefer its third handoff argument for new integrations.

2. Inspect authoritative items

const holdResponse = await fetch(
  `https://api.seatlayer.io/v1/events/${eventKey}/holds/${holdId}`,
  {
    headers: {
      authorization: `Bearer ${process.env.SEATLAYER_SECRET_KEY}`,
    },
  },
);

if (!holdResponse.ok) {
  return reply.status(409).send({ code: "hold_unavailable" });
}

const hold = await holdResponse.json();
if (hold.status !== "active" || hold.expiresAt <= Date.now()) {
  return reply.status(409).send({ code: "hold_unavailable" });
}

const total = hold.items.reduce(
  (sum, item) => sum + item.unitPrice * (item.quantity ?? 1),
  0,
);

Use the returned currency, tier, quantity, and price fields supported by your order model. Treat the browser handoff as display context, never the charging authority.

3. Book after the payment decision

const bookingResponse = await fetch(
  `https://api.seatlayer.io/v1/events/${eventKey}/book`,
  {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.SEATLAYER_SECRET_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      holdId,
      bookingRef: order.id,
    }),
  },
);

if (bookingResponse.status === 409) {
  await voidOrRefundPayment(order);
  return reply.status(409).send({ code: "inventory_conflict" });
}

if (!bookingResponse.ok) {
  // State may be uncertain after a timeout or transport failure.
  // Retry with the same order.id—never mint a new bookingRef.
  throw new Error(`SeatLayer booking failed: ${bookingResponse.status}`);
}

await markOrderConfirmed(order.id);
await issueAndDeliverYourTickets(order.id);

bookingRef is your idempotency boundary. If a request times out, retry the same purchase with the same value. A confirmed replay is safe, but the current replay response contains booked: []; keep the durable receipt details in your order record and webhook handler.

Choose a payment sequence

Do not hide this tradeoff inside a generic “checkout failed” branch. Record each transition so support staff can distinguish payment state from inventory state.

Reconcile signed webhooks

app.post("/webhooks/seatlayer", rawBodyMiddleware, async (req, res) => {
  verifySeatLayerSignature(req.rawBody, req.headers);

  const { event, payload } = JSON.parse(req.rawBody);
  if (event === "seat.booked") {
    await confirmOrderIdempotently(payload);
  }

  res.sendStatus(200);
});

Webhooks are the reconciliation path, not a reason to keep the buyer waiting. Verify the signature against the raw request body, return a successful status quickly, and process every delivery idempotently.

Expected failure behavior

To reverse a completed sale, run your ticket cancellation, monetary refund, and SeatLayer inventory cancellation as observable operations in your system. SeatLayer releases inventory; it does not move money or cancel/deliver your tickets.

Production checklist

• The browser sends only holdId and non-authoritative UI context.
• Hold inspection happens with a server-only secret key.
• Price and currency are derived from the inspected hold.
• One durable order id is reused as bookingRef.
• Our platform creates, delivers, recovers, and scans its own tickets.
• Payment compensation for 409 is tested.
• Timeout retries use the same request identity.
• The webhook handler verifies the raw body and is idempotent.
• Support can see payment state and inventory state separately.
• Test mode has completed a full purchase and duplicate retry.

Continue with the booking endpoint, idempotency and conflict behavior, or webhook signatures.