Changelog

This is the changelog of the Understory API.

All additions or changes to API endpoints, general usage updates, and behavior changes will be reflected below. Breaking changes will be high-lighted in line with our Breaking Changes policy and the affected APIs grace period will be noted.

See API Versioning to learn more.

Location API

New read-only API for resolving the location_id that every event session already carries.

• Added Get Locations (GET /v1/locations) to list the locations a company runs its experiences from, paginated with the cursor and limit query parameters.
• Added Get Location (GET /v1/locations/{locationId}) to retrieve a single location by the location_id returned on a session.
• A Location carries id, timezone, address, coordinates, created_at, and updated_at. Locations are read-only through this API; they are created and maintained by the company inside Understory.
• No company-authored label is exposed. A location's name in Understory is internal to the company's own staff, so compose your own display string from the parts in address.
• Documented that timezone is the authority for interpreting a session's start_time and end_time, which are returned without a UTC offset, and that it falls back to Europe/Copenhagen when the company has not set one.
• coordinates is omitted unless both a latitude and a longitude are known for the location.
• A location that has been removed in Understory returns 404, so a location_id read from an older event or booking may stop resolving.
• Added the location.read scope, required by both endpoints. Existing credentials do not gain it automatically — update or re-issue your credentials to request it.

Gift Card API

The Gift Card API is no longer read-only.

• Added POST /v1/gift-cards/{giftCardId}/extend-expiry to push an active gift card's expiry date further out. The endpoint returns the updated gift card. It changes only the expiry date; a gift card's balance cannot be changed through this API.
• The new expiry must be later than the gift card's current expiry — this action extends the expiry date and never brings it forward. An earlier or past date returns 400.
• Only gift cards with status ACTIVE can be extended. EXPIRED, SPENT, and VOIDED gift cards return 409.
• Re-sending a gift card's current expiry date has no effect and returns the gift card unchanged, so a retried request is safe.
• Added the gift-card.write scope, required by this endpoint. Existing credentials do not gain it automatically — update or re-issue your credentials to request it.

Checkout deep linking guide

Added a new Checkout deep linking guide documenting how to link visitors directly into a Storefront's checkout flow from emails, websites, and third-party listings.

• Documented the checkout entry URL, https://{storefront}.understory.io/checkout/{experienceId}, which works identically on storefronts served from a custom domain.
• Documented the stable, public deep link parameters: eventId, from, variant/{variantId}, and addon/{addOnId}, including validation behavior where invalid values are silently discarded.
• Documented common patterns for linking to a specific event, a specific date, or straight to the booking & payment step, and how to build links from ids returned by the Events, Experiences, and Get ticket variants endpoints.

These changes affect documentation only; no API behavior, schemas, or field names changed.

Accounting API

New APIs for consuming and reporting on journal entries in preview. This allows you to build custom accounting integrations and report back syncronization status and other relevant information to show inside Understory.

Journal entries expose the postings, references, and supporting documents needed to sync financial events into external accounting and bookkeeping systems.

• Added GET /v1/accounting-journal-entries/{journalEntryId} to retrieve a journal entry by ID.
• Added POST /v1/accounting-journal-entries/{journalEntryId}/activities so integrations can relay how an entry was processed in an external accounting system eg. sync started, succeeded, or failed.
• Added v1.journal_entry.created webhook event for discovery.
• Added v1.journal_entry.document_attached webhook event, sent when a supporting document (such as a customer receipt or credit note) is attached to an existing journal entry.

Events API & Event Availability API

• Increased the maximum number of sessions per event from 10 to 50. The sessions array on Event now accepts up to 50 items.
• Changed the from/to filters on Get events and List Event Availability to match against every session of an event instead of only the first. An event is now returned when any of its sessions starts within the requested window, so multi-session events remain in results while later sessions are still upcoming.
• Documented the ordering of GET /v1/events: results are ordered by session start time, and a multi-session event appears once, positioned by its earliest session in the requested window.

Experiences API

• Breaking change: removed the type field from Experience, which previously indicated the booking model (SINGLE_SESSION or MULTI_SESSION). The Experiences API is in Alpha and not subject to the Breaking Changes policy.

Pagination guide rewritten

The Pagination guide has been rewritten to document the consistency model of listing endpoints and how to integrate against it.

• Clarified that listing endpoints such as GET /v1/events and GET /v1/bookings are designed for ad-hoc reads, not as a continuous synchronization mechanism.
• Documented that paginated responses are best-effort traversals rather than snapshots: identical requests can return different totals, and next does not guarantee consistency across pages.
• Documented that cursors are opaque and short-lived, and must not be persisted across jobs, sessions, queues, or workflow state.
• Pointed at webhooks as the right mechanism for keeping a local data store in sync.

These changes affect documentation only; no API behavior, schemas, or field names changed.

Documentation improvements across all APIs

API reference documentation has been enriched across the Bookings, Events, Event Availability, Experiences, Gift Card, Marketing, Orders, and Webhooks APIs. Endpoint behavior, request and response semantics, and the full list of enum values are now described in line with each property.

• Added or expanded info and tag descriptions to clarify what each API is for and how it relates to the others.
• Documented the meaning of every value in lifecycle and status enums, including Booking.status, Event.state, Event.visibility, Experience.state, Experience.type, GiftCard.status, Order.status, TransactionStatus, TransactionProvider, RefundStatus, Ticket.status, ticket check-in method, line item product_type, information request scope, and webhook subscription state.
• Clarified the semantics of from/to filters on GET /v1/events (matched against the first session's local start time) and the local-time-without-offset representation used by Session.start_time/end_time.
• Documented the snapshot semantics and per-constraint behavior of the Event Availability response, including the EventStateConstraint, EventSeatsLimitConstraint, BookingLimitConstraint, BookingCutoffTimeConstraint, and TicketLimitConstraint shapes.
• Standardized pagination, error, and 4xx response documentation across all specs.

These changes affect documentation only; no API behavior, schemas, or field names changed.

Bookings API

• Added event_id query parameter to GET /v1/bookings to filter bookings for a specific event.

Bookings API

• Added GET /v1/bookings/{bookingId}/information-request-answers endpoint to retrieve answers to information requests for a booking.

Bookings API

• Added EXTERNAL check-in method to ticket check-in enum. This indicates a ticket was checked in via an external system integrated with the backoffice.

Marketing API

• Added GET /v1/marketing-consents/{id} endpoint to fetch a single marketing consent by ID. Useful for fetching consent details after receiving a webhook event. See Get marketing consent by ID for details.

Marketing API

• Added references array to marketing consents response model. References are typed links to related entities (storefronts, bookings, orders) that can be used to fetch additional details. See Get marketing consents for details.

Gift Card API

• Added new Gift Card API with endpoints to list and retrieve gift cards. See Get gift cards and Get gift card for details.
• Added gift-card.read OAuth scope for accessing gift card data.

Marketing API

• Added webhook for new marketing consents. See Marketing consent created for details.
• Added id to marketing consents response model as a stable reference for delta loading on the Get marketing consents endpoint.

Events API

• Added experience_id query parameter to GET /v1/events to filter events for a specific experience.

Orders API

• Added EXTERNAL transaction provider to order transactions. EXTERNAL indicates payment for an order was received in another system and marked as paid within Understory.

Events API

• Fixed start_time and end_time in Session to correctly return local time strings without timezone offset. The timezone is provided separately in the timezone field.

Bookings API & Experiences API

• Updated locale field description to include examples and improve clarity

Third-Party Integrations (Public Beta)

Third-party integrations are now available in public beta, enabling external applications to integrate with the Understory API on behalf of Understory customers.

This feature allows developers to build applications such as:

• Marketplaces
• Marketing tools
• Accounting systems

Key capabilities:

• OAuth 2.0 Authorization Code Grant flow for secure delegated authorization
• Access and refresh token management
• Scoped permissions to request only the access your application needs

To get started, contact integrations@understory.io with your application details to receive OAuth 2.0 client credentials.

Read the full guide at Third-Party Integrations.

Event API & Event Availability API

• Changed from and to filter parameters to accept local date-time without timezone (e.g., 2025-01-15T09:00:00 instead of 2025-01-15T09:00:00Z). The filter is matched against the event's local start time.

Webhooks API promoted to Alpha

The Webhooks API has been promoted from Preview to Alpha status. This means the API is now available for integration, though changes may still occur. See API Versioning for details.

Webhooks API (Preview)

• Added BaseEvent schema that defines the common envelope structure (id, type, timestamp, payload) for all webhook events

Webhooks API (Preview)

The Webhooks API is now available in preview.

As a preview API, this is currently a draft and is subject to change without notice.

This API enables you to:

• Create and manage webhook subscriptions to receive real-time notifications
• Subscribe to events for experiences, events, and bookings

Key features:

• Webhook subscription management (create, list, get, update, delete)
• Signature verification using HMAC-SHA256 for secure webhook delivery
• Secret key returned on subscription creation for signature verification

Available webhook events:

• Experience: v1.experience.created, v1.experience.updated, v1.experience.deleted
• Event: v1.event.created, v1.event.updated, v1.event.cancelled, v1.event.completed, v1.event.deleted
• Booking: v1.booking.created, v1.booking.updated, v1.booking.cancelled

The specification can be inspected in API Reference: Webhook.

Experiences API

• Restructured InformationRequest model to support multiple input types via discriminator pattern
• Added TextInformationRequest schema for free-form text input fields
• Renamed label to question for clarity on what is presented to the guest
• Promoted Get information requests and Get ticket variants endpoints to Alpha

Event Availability API

• Renamed remaining to cutoff_time in BookingCutoffConstraint for clarity

Other improvements

• Added default error responses to information requests and ticket variants endpoints
• Fixed Accept-Language header handling in Experiences API

Events and Experiences APIs promoted to Alpha

The Events and Experiences APIs have been promoted from Preview to Alpha status. This means they are now available for integration, though changes may still occur. See API Versioning for details.

Additional improvements in this release:

• Added UNKNOWN to state and visibility enums for better forward compatibility
• Added INACTIVE state to the Experiences API
• Improved error responses with proper 403 and 404 status codes
• Updated Metadata schema to use additionalProperties with string values

Event Availability API updates

• Renamed SeatsLimitConstraint to EventSeatsLimitConstraint (type: EVENT_SEATS_LIMIT)
• Added new EventStateConstraint (type: EVENT_STATE) for event state-based availability

Pagination improvements across APIs

Pagination parameters have been standardized across the Bookings, Grow, Events, and Experiences APIs:

• Added explicit minimum: 1 and maximum: 100 constraints to limit parameters
• Improved documentation for cursor and limit parameters

The Event Availability API is now available in alpha. This API allows querying availability for events, including remaining capacity and constraint information such as seat limits, booking limits, ticket limits, and booking cutoff times.

The specification can be inspected in API Reference: Event Availability.

The Experiences API has been updated. Specifically, the media property in the image variant no longer has a preview_url field.

The Experiences and Events preview APIs have been updated. This change includes a lot of changes to the general models while preserving the available data.

• Experiences are no longer differentiated by being shared or not. All experiences should be considered the same.
• Events now include sessions which contains the specific date and time for when the event is held. This moves a lot of fields from experiences into sessions for better separation and composability.
• Computed fields have been removed from events' capacity. These can be calculated client side if needed based on total and reserved fields on the Capacity model.

The Bookings API is moved to Alpha. This means the API is available for integration but changes might still occur. Read the API Versioning article for more details.

• POST /v1/bookings: A new optional request body field metadata is added to allow for custom key/value pairs of metadata to be attached on the booking for later reference.
• POST /v1/bookings: The endpoint now only returns the ID and status of a successfull booking operation.

The Events API is now available in early preview. The specification can be inspected in API Reference: Event.

The Experience API is now available in early preview. The specification can be inspected in API Reference: Experience.

The Bookings API is now available in early preview. The specification can be inspected in API Reference: Booking.

This release adds marketing consents to the API enabling marketing automation flows.

Read more about the API in the API Reference: Get marketing consents.