Skip to content
Docs
Open Backstage
Operation

Update Event

PATCH/events/{id}
Update an existing event's properties. Only the fields you include in the request body will be modified - all other fields remain unchanged. Common updates include changing the event name, description, or status (e.g., publishing a draft event or cancelling an event).

When to use this

  • Publishing a draft event to make it visible
  • Updating event details like name or description
  • Cancelling an event
  • Changing the associated venue

Path parameters

idstringRequired
Event ID

Headers

If-MatchstringOptional
The version of the record this change is based on, as the `ETag` of a read returned it. When the record is no longer at that version nothing is written and the answer is 412 VERSION_MISMATCH. The same as `expectedVersion` in the body; send one or the other.
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

namestringEvent name
subtitlestringnullShort event subtitle / tagline
descriptionstringnullEvent description
shortDescriptionstringnullCard / listing summary
imageUrlstring,null (uri)Listing / card image URL
heroImageUrlstring,null (uri)Event-page hero image URL
presentationobjectnullEvent-level storefront design override
▶heroLayoutobject
▶cinemaGradientobject
twoColumnSplitarray
▶navbarobject
buttonSize"small" | "medium" | "large"
status"draft" | "published" | "on_sale" | "sold_out" | "completed" | "cancelled"Event status
venueIdstringnullVenue ID (link to formal venue)
venueNamestringnullVenue name (text-only, alternative to venueId)
timezonestringEvent timezone
▼rulesobjectThe listing states to change; an omitted state is unchanged. Each rule replaces the stored one whole.
discoverableany
visibleany
sellableany
tagsstring[]Event tags
▼ticketTypesobject[]Ticket types for this event
idstringTicket type ID (auto-generated if not provided)
name*stringTicket type name
descriptionstringTicket type description
displayOrder*integerDisplay order
tagsstring[]Ticket-type tags, by slug: each a defined tag that applies to ticket_types (400 TAG_NOT_DEFINED or TAG_NOT_APPLICABLE otherwise). What fee rules key on, the same in every event
visibility"public" | "locked" | "hidden"Price visibility for this type's cells (TKT-336): public (shown and buyable), locked (shown with how to unlock it, buyable once unlocked) or hidden (not shown to a buyer until unlocked). A cell can override it. Absent keeps the type's current visibility
unlockTagsstring[]Customer tags (slugs), any one of which unlocks a locked or hidden price of this type; each must be a defined tag that applies to customers. Absent keeps the current ones
taxCategory"admission" | "admission_exempt" | "donation" | "non_taxable"What admission of this type is taxed as: admission (the standard rate in the UK), admission_exempt (an eligible cultural or sporting body), donation or non_taxable (outside the scope). Absent keeps the current one; a new type is admission
▼layoutobjectEvent layout with categories and capacity areas
▶categoriesobject[]Pricing categories for this event
▶areasobject[]Capacity areas (GA and/or allocated)
venueLayoutTemplateIdstringSource venue layout template ID (if imported)
expectedVersionintegerThe `version` of the record this change is based on. When the record is no longer at that version nothing is written and the answer is 412 VERSION_MISMATCH. The same as the `If-Match` header.

Returns

Event updated successfully

Errors

400
Bad Request - Invalid input
401
Unauthorized - Authentication required
403
Forbidden - Insufficient permissions
404
Not Found - Resource not found
412
Precondition Failed - VERSION_MISMATCH: the record has changed since the version the request named; nothing was written
500
Internal Server Error

Every error names its code and links to it. All error codes

Notes

Note
This endpoint uses PATCH semantics - only include fields you want to change.
Important
Changing an event's status to `cancelled` will notify ticket holders if configured.
Tip
Fetch the event first with `getEvent` if you need to see current values before updating.

Related

import { BackstageClient } from '@ticketlayer/backstage';const client = new BackstageClient({  organisationSlug: 'your-org',});client.setAccessToken('YOUR_ACCESS_TOKEN');// Publish a draft eventconst event = await client.events.update('evt_abc123', {  status: 'published',  description: 'Updated description with more details!',});console.log(`Event ${event.name} is now ${event.status}`);
Response 200
{
  "event": {
    "id": "evt_abc123",
    "organisationId": "org_xyz789",
    "accountId": "acc_def456",
    "name": "Summer Music Festival",
    "subtitle": "Three days. Fifty artists. One field.",
    "description": "A three-day music festival",
    "shortDescription": "Top artists across three days.",
    "status": "draft",
    "images": {
      "card": {
        "url": "https://api.ticketlayer.com/assets/o/org_xyz789/tempest-card.jpg",
        "width": null,
        "height": null,
        "alt": "The Tempest",
        "contentType": "image/jpeg"
      },
      "hero": null
    },
    "imageUrl": "https://api.ticketlayer.com/assets/o/org_xyz789/tempest-card.jpg",
    "heroImageUrl": null,
    "presentation": {
      "heroLayout": {
        "type": "cinema",
        "size": "large"
      },
      "buttonSize": "large"
    },
    "venueId": "vnu_ghi789",
    "venueName": "The Globe",
    "timezone": "Europe/London",
    "rules": {
      "discoverable": {
        "open": true,
        "windows": [
          {
            "from": null,
            "until": null,
            "audienceTags": [],
            "audience": null
          }
        ]
      },
      "visible": {
        "open": true,
        "windows": [
          {
            "from": null,
            "until": null,
            "audienceTags": [],
            "audience": null
          }
        ]
      },
      "sellable": {
        "open": true,
        "windows": [
          {
            "from": null,
            "until": null,
            "audienceTags": [],
            "audience": null
          }
        ]
      }
    },
    "ticketTypes": [
      {
        "id": "tty_abc123",
        "name": "Adult",
        "description": "Ages 16+",
        "displayOrder": 0,
        "visibility": "hidden",
        "unlockTags": [
          "member"
        ],
        "requiredBenefit": "member",
        "tags": [
          "child"
        ],
        "taxCategory": "admission"
      }
    ],
    "defaultPriceSchemeId": "tps_abc123",
    "occurrenceCount": 3,
    "ticketCount": 0,
    "productCount": 0,
    "tags": [
      "music",
      "festival"
    ],
    "isDeleted": false,
    "createdAt": "2024-12-28T10:30:00Z",
    "updatedAt": "2024-12-28T14:45:00Z",
    "contentUpdatedAt": "2024-12-29T09:12:44.512Z",
    "createdBy": "usr_abc123",
    "version": 14
  }
}

Try it in test mode

Path parameters
Event ID
Body
Event name
Short event subtitle / tagline
Event description
Card / listing summary
Listing / card image URL
Event-page hero image URL
Event-level storefront design override
Event status
Venue ID (link to formal venue)
Venue name (text-only, alternative to venueId)
Event timezone
The listing states to change; an omitted state is unchanged. Each rule replaces the stored one whole.
Event tags
Ticket types for this event
Event layout with categories and capacity areas
The `version` of the record this change is based on. When the record is no longer at that version nothing is written and the answer is 412 VERSION_MISMATCH. The same as the `If-Match` header.