Floor Plans

A floor plan is a location-level canvas that models a table-based dining layout: named sections (Window, Bar, Patio) that each hold table placements positioned on the canvas. Floor plans power host-stand views, table-assignment workflows, section filtering, and table-slot availability matching.

Table resources are created through floor plans — not directly

Unlike rooms and rentals, you do not create table resources or their instances directly. When you create a floor plan definition, the platform automatically creates the underlying table Resource and ResourceInstance for every table and wires the links. That is why a table resource is the one exception to the "every resource needs at least one instance" rule on Resources & Instances — its instances come from the floor plan. Author the layout here; the catalog records are generated for you.

So a floor plan is both a visual layout and the source of truth for table inventory: place a table on the canvas and the bookable table resource and its instance exist; remove it and they go with it.

FloorPlan

The location-level canvas.

Field	Type	Required	Description
id	string	Yes	Unique floor plan identifier
name	string	Yes	Display name
description	string	Yes	Description for staff or integrations
locationId	string | null	No	Business location scope
imageUrls	string[] | null	No	Optional background or reference images
isActive	boolean	Yes	Whether the layout can be used (default: true)
canvasDimensions	CanvasDimensions	Yes	Layout coordinate system (see below)
capacity	number	Yes	Total seating capacity
metadata	object | null	No	Renderer or integration metadata

Section

A named area within a floor plan.

Field	Type	Required	Description
id	string	Yes	Unique section identifier
floorPlanId	string	Yes	Parent floor plan
locationId	string	Yes	Business location
name	string	Yes	Section name (Window, Bar, Patio)
capacity	integer	Yes	Section seating capacity
color	string	Yes	Hex color #RRGGBB for the host view
isActive	boolean	Yes	Whether the section is usable (default: true)
sortOrder	integer	No	Display order (default: 0)
tables	TablePlacement[]	No	Table placements in this section (default: [])
geometry	SectionGeometry | null	No	Section shape on the canvas (see below)

TablePlacement

A single table positioned on the canvas. Each placement links to the table Resource it represents (tableResourceId) and the section it sits in (floorPlanSectionId).

Field	Type	Required	Description
id	string	Yes	Unique placement identifier
floorPlanSectionId	string	Yes	Parent section
tableResourceId	string	Yes	The table resource this placement represents
number	string	Yes	Table number/label (e.g. "12", "B1")
x / y	number	Yes	Position on the canvas
width / height	number	Yes	Table footprint (> 0)
shape	enum	Yes	Table shape (see below)
rotation	number | null	No	Rotation in degrees
minParty	integer	Yes	Minimum party size
maxParty	integer	Yes	Maximum party size (used for capacity sums)
combinableWith	string[]	No	Tables this one can combine with (default: [])
serverSectionId	string | null	No	Server/waitstaff section assignment

Table shapes

Value	Typical rendering
round	Circular table
square	Square table
booth	Booth seating
rect	Rectangular table
curved	Curved booth or banquette
high_top	High-top table
bar	Bar seat or bar area

Canvas & geometry

CanvasDimensions

Defines the coordinate system every x/y/width/height is expressed in.

Field	Type	Required	Description
width	number	Yes	Canvas width (> 0)
height	number	Yes	Canvas height (> 0)
unit	enum	No	px, ft, or m (default: px)

SectionGeometry

Sections can optionally describe their own shape, discriminated by kind:

• auto — let the renderer derive the section bounds.
• rect — x, y, width, height, and optional rotation (−360…360).
• polygon — a points array of 3–64 { x, y } vertices, with optional rotation.

Creating a floor plan

Create the whole layout — floor plan, sections, and tables — in a single atomic request using the floor plan definition (graph). Nested sections and tables are supplied inline; the server assigns and wires all IDs.

Nested tables use number, not tableResourceId

In the create payload, each nested table is identified by its number (and an optional serverSectionId) rather than tableResourceId/floorPlanSectionId — the table resource and section links are created and wired by the server. Within the payload, combinableWith references other table numbers.

TypeScript

import { WiilClient } from 'wiil-js';
import { CanvasUnit, TableShape } from 'wiil-core-js';

const client = new WiilClient({ apiKey: process.env.WIIL_API_KEY! });

const floorPlan = await client.floorPlans.createDefinition({
  name: 'Main Dining Room',
  description: 'Primary indoor dining layout',
  capacity: 12,
  canvasDimensions: { width: 1200, height: 800, unit: CanvasUnit.PX },
  isActive: true,
  sections: [
    {
      name: 'Window',
      capacity: 8,
      color: '#2F80ED',
      isActive: true,
      sortOrder: 1,
      tables: [
        { number: 'W1', x: 220, y: 180, width: 80, height: 80, shape: TableShape.ROUND, minParty: 2, maxParty: 4, combinableWith: ['W2'] },
        { number: 'W2', x: 320, y: 180, width: 80, height: 60, shape: TableShape.RECT, minParty: 2, maxParty: 4, combinableWith: ['W1'] },
      ],
    },
    {
      name: 'Main Floor',
      capacity: 4,
      color: '#7B68EE',
      isActive: true,
      sortOrder: 2,
      tables: [
        { number: 'M1', x: 200, y: 420, width: 120, height: 80, shape: TableShape.RECT, minParty: 2, maxParty: 4, combinableWith: [] },
      ],
    },
  ],
});

console.log(`Floor Plan Created: ${floorPlan.id}`);

Python

# Floor-plan authoring (definition graph) is exposed through the
# TypeScript SDK and the platform API. The Python reservations SDK
# focuses on reservation_resources and reservations.

The response is a hydrated FloorPlanDefinition — the full floor plan plus its sections, each with its full list of table placements (now carrying their server-assigned tableResourceId values).

Validation rules

The nested create enforces capacity and party-size consistency. Capacity is treated as maximum seats, so section and floor-plan totals sum each table's maxParty.

Rule	Requirement
Sections present	At least one section must be defined
Tables present	Each section must have at least one table
Section capacity	Section capacity equals the sum of its tables' maxParty
Floor plan capacity	Floor plan capacity equals the sum of section capacities
Party sizes	Each table's maxParty ≥ minParty

In the example above: Window 8 = 4 + 4; Main Floor 4 = 4; floor plan 12 = 8 + 4.

Query options

Resource	Filters
FloorPlan	locationId, isActive
Section	locationId, isActive

Both are paginated with page and pageSize.

Related

• Resources & Instances — how table resources and instances fit the broader catalog.
• Table Reservations — booking tables against a floor plan.