Knowledge base

Getting started

This guide shows the shortest practical path from scratch to a working Seatmap Pro booking view on your selling page.

If you prefer a video flow, use the walkthrough:

Full video walkthrough (YouTube)

Seatmap Pro components

The end-to-end flow includes four components:

Editor: create venues and schemas, manage pricing, and publish changes.
Booking Renderer: interactive chart on your website/mobile selling page.
Admin Renderer: operational tools for managers and support teams.
Booking API: backend control for events, seat state, locks, and sales.

High-level runtime flow:

Manager configures venue/schema in Editor.
Your backend creates event and manages seat state through Booking API.
Customer opens selling page where Booking Renderer loads by publicKey + eventId.
Selection/checkout updates availability, and Renderer reflects latest state.

Diagram of the five steps: create the schema, create the event, assign prices, embed the renderer, run the checkout flow — End-to-end getting started flow

Step 1. Draw and publish your first schema

Start in Seatmap Editor.

Editor access can be:

provided by Seatmap Pro (SaaS), or
deployed in your infrastructure (on-prem via Docker/Kubernetes).

Open the venue list after login and select an existing venue or create a new one.

Screenshot of the venue list and venue creation in the Editor — Venue list and venue creation

Open schema editing workspace and design the layout (sections, rows, seats, geometry).

Screenshot of the schema editing page in the Editor — Schema editing page

Publish the schema so it becomes available for the Renderer/API usage.

Reference: Editor user guide

Step 2. Copy integration credentials from Admin panel

In Editor Admin panel, open organization details and copy:

Public API key (used by Booking Renderer on client side)
Secret API key (used as X-API-Key in backend API calls)

Screenshot of the organization settings showing the public key — Organization settings with public key

Reference: Managing access

Step 3. Create event in backend and keep `eventId`

Diagram: your backend creates the event through the Booking API and stores the eventId it returns — Event creation and eventId handoff

An event links your published schema to a specific show/date.

Call Booking API from your backend:

curl -X POST "https://booking.seatmap.pro/api/private/v2.0/events/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <ORGANIZATION_TOKEN>" \
  -H "X-Organization-ID: <ORGANIZATION_ID>" \
  -d '{
    "id": null,
    "createdDate": null,
    "start": "2025-12-03T20:00:00Z",
    "endDate": "2025-12-03T22:30:00Z",
    "name": "My Concert - Dec 03 2025",
    "schemaId": 3275
  }'

Then:

store returned eventId in your event record
return this eventId to your selling page

This is the critical bridge between your ticketing domain and Renderer initialization.

You can also create an event using Editor UI by clicking the Events tab and creating a new event from there. For more information on managing events via UI read this section.

Screenshot of the Events Hub overview — Events Hub overview

Step 4. Create and assign prices (backend)

Diagram: your backend creates prices for the event and assigns them to seats and general admission areas through the Booking API — Price creation and assignment flow

Create prices for the event:

curl -X POST "https://booking.seatmap.pro/api/private/v2.0/event/<EVENT_ID>/prices/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <ORGANIZATION_TOKEN>" \
  -H "X-Organization-ID: <ORGANIZATION_ID>" \
  -d '[
    {
      "id": null,
      "name": "2000",
      "eventId": "<EVENT_ID>",
      "externalId": null
    }
  ]'

Assign created price to seats:

curl -X POST "https://booking.seatmap.pro/api/private/v2.0/event/<EVENT_ID>/prices/assignments/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <ORGANIZATION_TOKEN>" \
  -H "X-Organization-ID: <ORGANIZATION_ID>" \
  -d '{
    "seats": [
      {
        "objectId": 5142395,
        "assignmentId": 3618500,
        "activeCount": null
      }
    ]
  }'

objectId is a seat object ID from schema metadata, and assignmentId is the created price assignment ID.

Seat and area IDs

Booking API v2 addresses each seat and each general admission area by its numeric ID, both in price assignments and in seat operations. A general admission area also takes a number of places: activeCount in a price assignment, and capacity in the lock, unlock and sale calls.

To read the seat IDs for an event, use its seat listing, GET /api/private/v2.0/events/<EVENT_ID>/seats/. It returns the event’s seats a page at a time, each with its row and section by both ID and label, together with the seat’s state and price.

The renderer reports a selected seat with its numeric id and a composite key such as Section B;;5;;14. Send the id to Booking API v2; if a seat comes without one, look it up by its section, row and seat labels in the seat listing. Composite keys address seats only in the legacy v1 API.

Optional: you can manage prices directly in Editor pricing mode instead of assigning them through backend API.

Step 5. Initialize Booking Renderer via SDK

Diagram: the selling page creates the renderer with the public key and loads the event from the Booking API — Renderer initialization on the selling page

Install the package (choose one):

npm install @seatmap.pro/renderer

yarn add @seatmap.pro/renderer

pnpm add @seatmap.pro/renderer

SDK reference: Initializing SDK

Add a Renderer container to your selling page template:

<div id="seatmap-root" style="width: 100%; height: 600px;"></div>

Then initialize the Renderer in your app code, for instance:

import { SeatmapBookingRenderer } from '@seatmap.pro/renderer';

type SeatmapConfig = {
  eventId: string;
  publicKey: string;
};

async function initSeatmap(container: HTMLElement, cfg: SeatmapConfig) {
  const renderer = new SeatmapBookingRenderer(container, {
    publicKey: cfg.publicKey,
    onSeatSelect: (seat) => {
      console.log('select', seat);
      // sync selection with your cart/back-end
    },
    onSeatDeselect: (seat) => {
      console.log('deselect', seat);
      // sync deselection with your cart/back-end
    },
  });

  await renderer.loadEvent(cfg.eventId);
  return renderer;
}

Required runtime values:

publicKey: from organization settings in Editor Admin panel.
eventId: created and stored by your backend for a specific show.

Step 6. Handle operations with seats

The Renderer exposes callbacks for seat and interaction events, including:

seat selection
seat deselection
hover and blur interactions

For getting started, the main integration point is onSeatSelect.

After the callback is triggered, you typically choose one of these approaches:

Keep selection only in a local cart and sync with backend later (for example, on checkout).
Lock or unlock seats on each select/deselect event (lock-per-click flow).

For production ticketing, lock-per-click is usually the safer approach.

Lock-per-click flow:

User selects a seat on the selling page.
Renderer triggers callback and notifies your sales page code.
Sales page sends a lock request to your ticketing backend.
Backend performs internal state checks and validates that lock is allowed.
Backend calls Booking API to lock the seat.

Diagram of lock-per-click: the renderer reports a selected seat, your backend checks it and locks the seat through the Booking API — Seat operations flow with lock-per-click

Step 7. Test integration

You are ready for production integration when:

schema is published and visible in Editor
public API key and Secret API key are copied from organization settings
backend can provide valid eventId for a show
backend can create prices and assign them to seat objects
selling page renders the chart and seat interactions work
checkout flow updates seat state correctly

If you want a ready HTML/CSS/JS example, see:

Working demo (CodePen)

Example of the final Renderer placement on a selling page:

Screenshot of a seat map rendered on a ticketing page — Renderer embedded into a ticketing page layout