Operation

Create Event Occurrence

POST/events/{eventId}/occurrences

Add a new date and time for an event. Events don't happen on their own-they need occurrences. An occurrence is a specific date and time when the event takes place, with its own capacity and ticket availability. You can create multiple occurrences for the same event (matinee and evening shows, a week-long run, etc.).

When to use this

Adding show dates when setting up a new event
Creating recurring performances (daily, weekly, etc.)
Adding extra dates when an event sells well

Path parameters

eventIdstringRequired: Event 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

startDate*string (date-time)Start date (ISO date)

startTime*stringStart time (HH:mm:ss)

endDate*string (date-time)End date (ISO date)

endTime*stringEnd time (HH:mm:ss)

timezonestringOccurrence timezone (can override event timezone)

venueIdstringVenue ID (can override event venue)

venueLayoutIdstringVenue layout ID

ticketSchemeIdstringTicket scheme to use for this occurrence

priceSchemeIdstringPrice scheme to use (must belong to the ticket scheme)

▼categoryMappingobject[]Category mapping for template mode ticket schemes

ticketCategoryId*stringTicket category ID from the ticket scheme

venueLayoutCategoryId*stringVenue layout category ID to map to

enabledbooleanWhether this category is enabled for this occurrence

status*"draft" | "on_sale" | "sold_out" | "completed" | "cancelled"Occurrence status

Returns

Event occurrence 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

The occurrence inherits settings from its parent event, but you can override capacity and other details.

Tip

Make sure to set the correct timezone-dates are stored in UTC but displayed in the event's local timezone.

import { BackstageClient } from '@ticketlayer/backstage';const client = new BackstageClient({  organisationSlug: 'your-org',});client.setAccessToken('YOUR_ACCESS_TOKEN');// Create eventoccurrenceconst eventoccurrence = await client.eventoccurrence.create({  name: 'New EventOccurrence',  // Add other required fields});console.log(`Created eventoccurrence with ID: ${eventoccurrence.id}`);

Response 201

{
  "eventOccurrence": {
    "id": "eoc_abc123",
    "organisationId": "org_xyz789",
    "accountId": "acc_def456",
    "eventId": "evt_ghi789",
    "startDate": "2025-06-15T00:00:00Z",
    "startTime": "19:00:00",
    "endDate": "2025-06-15T00:00:00Z",
    "endTime": "23:00:00",
    "timezone": "Europe/London",
    "venueId": "vnu_abc123",
    "status": "draft",
    "isDeleted": false,
    "createdAt": "2024-12-28T10:30:00Z",
    "updatedAt": "2024-12-28T14:45:00Z"
  }
}

Create Event Occurrence

When to use this

Path parameters

Headers

Body

Returns

Errors

Notes

Related

Try it in test mode

Path parameters

Body