Eventually Ticketing
Integrations

Public widget API reference

The public widget API exposes a calendar widget's event data as read-only JSON. It has two endpoints: the initial widget response, which includes pre-sale data, and a paginated events response, which omits the top-level preSales field while its event objects can still include pre-sale fields. Neither endpoint requires authentication.

Endpoints

Endpoint

Purpose

GET /api/widgets/:uuid

Initial widget render. Returns the widget config, its events, and the top-level preSales collection.

GET /api/widgets/:uuid/events

Paginated event list for calendar navigation and list or card pagination. Omits the top-level preSales field; individual events can still include pre-sale fields.

Initial widget response

Call GET /api/widgets/:uuid to load a widget and its pre-sale data. This is the only widget response that includes the top-level preSales collection.

Request parameters

Parameter

Behavior

embed

Optional. Defaults to combined; invalid values fall back to combined.

event_id

Optional. Sanitized to a numeric string of at most 19 digits; invalid values are ignored.

Response

{
  "widget": {
    "id": 123,
    "name": "Widget name",
    "config": {},
    "embedType": "combined"
  },
  "events": [],
  "preSales": []
}

The widget object identifies the widget. The events array contains the widget's events, each with fields such as id, title, date, timezone, location, imageUrl, categoryName, tagNames, ticketPrice, spotsRemaining, soldOut, and registrationUrl. When the pre-sale feature is enabled, events also include purchasable, purchasableAt, lockedLabel, cardBadgeText, and requiresPreSaleUnlock. Events can also include an optional fromPrice object, present when the team's price label applies to an event with multiple currently purchasable prices: label is the team's chosen wording, amount is the lowest applicable price shown to buyers, and compareAtPrice is the original price when that tier is on sale. fromPrice is omitted when no label applies, for example when the event has fewer than two currently purchasable prices or when checkout is not connected.

When the team enables Hide tickets remaining in Event Defaults, spotsRemaining is null in both endpoints. Use soldOut for sold-out status. A null spotsRemaining means the remaining count is hidden when Hide tickets remaining is enabled, but it can also mean the event has unlimited capacity.

The top-level preSales collection lists the pre-sales that apply to this widget's events. Each entry includes id, tagId, name, currentState, visibleAt, earlyAccessStartsAt, onSaleAt, the announcement fields announceEyebrow, announceHeadline, announceSubtext, announceButtonLabel, and announceButtonUrl, the access fields accessEyebrow, accessHeadline, and accessSubtext, and requiresCode, unlocked, earlyAccessActive, and unlockUrl. When no pre-sale applies, preSales is an empty array.

Paginated events response

Call GET /api/widgets/:uuid/events to page through a widget's events. This response contains only events and pagination metadata. It never includes a preSales field, but its event objects can still include pre-sale fields such as purchasable, purchasableAt, and requiresPreSaleUnlock.

Request parameters

Parameter

Behavior

page

Optional. Minimum 1; default 1.

per_page

Optional. Default 25, clamped to 1..200.

start_date

Optional. Start of the date range.

end_date

Optional. End of the date range.

event_id

Optional. Sanitized numeric ID. On page 1, the endpoint may insert the deep-linked event.

Response

{
  "events": [],
  "total": 30,
  "page": 1,
  "per_page": 25
}

events is the array of events for this page, total is the total matching event count, and page and per_page echo the current page and page size. Events can include the same optional fromPrice object as the initial widget response.

Errors and transport

An unknown widget returns {"error": "Widget not found"} with HTTP 404. Cross-origin GET and OPTIONS requests are allowed for /api/*. GET requests to /api/widgets/ are throttled to 60 requests per IP per 60 seconds.

Correlation IDs

Every widget API response, including error responses, carries the correlation ID that handled the request in the X-Correlation-Id response header. Send your own X-Correlation-Id request header to match a failed request to how the server handled it.

A header value is accepted when it is 8 to 64 characters long and uses only letters, digits, and hyphens. The server uses a valid value as the correlation ID for that request. When the value is missing or invalid, the server falls back to its own request ID or generates a new ID, and returns that value instead. Check the X-Correlation-Id response header to see which ID was actually used.

Was this helpful?
Was this helpful?