Skip to content
Last updated

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.

2026-05-22

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.

2026-05-01

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.

2026-04-29

Bookings API

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

2026-04-28

Bookings API

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

2026-04-27

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.

2026-04-10

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.

2026-04-09

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.

2026-03-26

Marketing API

2026-03-20

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.

2026-03-03

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.

2026-02-24

Bookings API & Experiences API

  • Updated locale field description to include examples and improve clarity

2026-02-20

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.

2026-02-16

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.

2026-01-30

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.

2026-01-26

Webhooks API (Preview)

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

2026-01-09

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.

2025-12-19

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

2025-12-18

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

2025-12-17

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

2025-12-11

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.

2025-10-10

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

2025-09-30

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.

2025-04-29

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.

2025-04-08

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

2025-04-07

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

2025-04-03

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

2025-03-20

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

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

Back