Operation
Create Venue Layout
POST
/venues/{id}/layoutsSet up a seating layout for a venue.
Layouts define how a venue is configured for ticket sales. A theatre might have
a "Full House" layout with all seats, and a "Cabaret" layout with tables.
A stadium might have different layouts for concerts vs football matches.
After creating a layout, you'll add areas (like "Stalls" or "Circle") and
then seats within those areas.
When to use this
- Setting up seating for a new venue
- Creating different configurations for the same space
- Defining reserved seating vs general admission areas
Path parameters
idstringRequired- Venue ID
Headers
Idempotency-KeystringOptional- Makes the write safe to retry. The first request with a key does the work and its response is stored for 24 hours; a repeat with the same key and the same request (method, path, query, X-Ticketlayer-Channel, TL-Version and body) gets that stored status and body back, marked `Idempotent-Replay: true`, without running again. The key is scoped to your organisation and your credential. The same key with a different request is 422 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running waits for it, then answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS if it has not finished. Only a 2xx is stored: after an error the key is free again. Omit the header and the request behaves as it always has.
Body
name*stringLayout name
descriptionstringLayout description
status"active" | "archived"Layout status
totalCapacitynumberTotal capacity (denormalized sum of all area capacities)
idstringFloor ID (auto-generated if not provided)
name*stringFloor name
displayOrder*numberDisplay order (0 = ground, higher = upper floors)
descriptionstringFloor description
idstringCategory ID (auto-generated if not provided)
name*stringCategory name
descriptionstringCategory description
displayOrder*numberDisplay order in UI
colorstringHex color for visual distinction
idstringArea ID (auto-generated if not provided)
name*stringArea name
descriptionstringArea description
type*"unallocated" | "allocated"Area type (unallocated = GA, allocated = assigned seating)
status"active" | "inactive"
floorIdstringFloor ID (for multi-level venues)
capacity*numberTotal capacity
displayOrder*numberDisplay order in UI
colorstringHex color for visual distinction
idstringDecoration ID (auto-generated if not provided)
type*"stage" | "pillar" | "barrier" | "aisle" | "wall" | "exit" | "entrance" | "bar" | "restroom" | "label" | "custom"Decoration type
namestringDecoration name
labelstringDisplay label text
tagsstring[]Layout tags
Returns
Venue layout created successfully
Errors
- 400
- Bad Request - Invalid input
- 401
- Unauthorized - Authentication required
- 403
- Forbidden - Insufficient permissions
- 404
- Not Found - Resource not found
- 500
- Internal Server Error
Every error names its code and links to it. All error codes
Notes
Note
After creating the layout, use `addAreaToVenueLayout` to add seating areas.
Tip
Give layouts clear names like "Full Capacity" or "Reduced COVID Layout" so staff can easily pick the right one.
Related
import { BackstageClient } from '@ticketlayer/backstage';const client = new BackstageClient({ organisationSlug: 'your-org',});client.setAccessToken('YOUR_ACCESS_TOKEN');// Create venuelayoutconst venuelayout = await client.venuelayout.create({ name: 'New VenueLayout', // Add other required fields});console.log(`Created venuelayout with ID: ${venuelayout.id}`);Response 201
{
"venueLayout": {
"id": "vlt_abc123",
"venueId": "vnu_def456",
"organisationId": "org_xyz789",
"accountId": "acc_ghi012",
"name": "Theatre Mode",
"description": "Standard theatre configuration",
"status": "active",
"totalCapacity": 1500,
"categories": [],
"areas": [],
"decorations": [],
"tags": [
"theatre",
"seated"
],
"isDeleted": false,
"createdAt": "2024-12-28T10:30:00Z",
"updatedAt": "2024-12-28T14:45:00Z",
"createdBy": "usr_abc123"
}
}