Checkout deep linking

Every Understory Storefront has a public checkout flow where customers pick a date, choose tickets, and pay. Checkout deep links let you jump a visitor straight into that flow from anywhere — a link in an email, a "Book now" button on a website, or a card in a listing you built yourself.

This closes a common gap. You can use the Events and Experiences APIs to list experiences and their upcoming dates on your own site, styled however you like, and then hand the visitor back to Understory for the parts you don't want to rebuild: availability, ticket selection, and payment. No checkout UI to maintain, no payment integration to certify — just a link.

Deep links are plain URLs. There is nothing to install and no token to attach: you construct a URL, the visitor opens it, and the checkout flow reads the query parameters and drops them at the right step.

How it works

Every deep link points at the checkout entry path for one experience, on the domain of the storefront that sells it:

Checkout entry URL

https://{storefront}.understory.io/checkout/{experienceId}

{storefront} is the storefront's subdomain on understory.io. An account can run several storefronts — build each link on the storefront the experience is sold through.
Storefronts served on a custom domain use the same path on that domain instead: https://{custom-domain}/checkout/{experienceId}. Everything on this page works identically on both.
{experienceId} is the experience's id from the Experiences API. It is the same id used as experience_id on events.

When the visitor opens the link, the checkout reads the query parameters, validates them against live availability, and forwards the visitor to the step the link describes — keeping the parameters that still apply. If a visitor already has a checkout in progress, an incoming deep link takes precedence: it overwrites the in-progress selection so the visitor lands exactly where the link points.

You can prefix the path with any locale configured for the storefront, e.g. …/en-us/checkout/{experienceId}. See Localization for how locales resolve.

Deep link parameters

All parameters are optional and supplied as query parameters. They are a stable, public contract — safe to embed in emails and on third-party sites.

Parameter	Format	Description
`eventId`	string	Pre-select a specific event (a dated, bookable instance of the experience). This is the event's `id` from the Events API.
`from`	`YYYY-MM-DD`	Open the date step anchored on this date instead of the first available one.
`variant/{variantId}`	integer ≥ 1	Pre-fill the quantity for a ticket variant. `{variantId}` is the variant `id` from Get ticket variants. Repeat the parameter to pre-fill several variants.
`addon/{addOnId}`	integer ≥ 1	Pre-fill the quantity for an add-on, by its id. Repeat for several add-ons.

Values are validated and invalid values are silently discarded — a malformed from, an unknown eventId, or a non-positive quantity is ignored rather than erroring, so a stale link always degrades to a usable starting point rather than a broken page. Unknown query parameters (e.g. your own utm_* tags) are ignored.

Common patterns

The three patterns below cover most integrations. Each one builds the same entry URL with different parameters.

Link to a specific event

Pass eventId to send the visitor to a specific date and time. The checkout opens the date step on that event's own date with the event pre-selected, ready for the visitor to choose tickets.

Link to one event

https://{storefront}.understory.io/checkout/581aa2f831d1b7fd29df7982571865a1?eventId=b1d9f3a07c4e4e1fae9c2d6b8a3f5e10

Use this for an "upcoming dates" list on your own site: render one link per event from the Events API, and each card takes the visitor straight to that slot.

If the event is sold out or can't fit the current selection, the visitor still lands on that day so they can see it alongside the alternatives — but no unbookable slot is pre-selected.

Link to a specific date

Pass from to open the date step anchored on a date, without committing the visitor to a particular event. Normal selection rules apply from there: nothing is pre-selected, and the visitor picks from whatever is available on and after that day.

Link to a date

https://{storefront}.understory.io/checkout/581aa2f831d1b7fd29df7982571865a1?from=2026-07-25

Use this when you want to point at a period — a campaign week, a season opening — rather than a single slot.

Link straight to tickets and payment

Combine eventId with one or more variant/{variantId} parameters to fully describe the booking. Because the event and the tickets are both known, the checkout skips the date and ticket steps and takes the visitor straight to the booking & payment step with the event and tickets already selected.

Link to an event with two adult tickets

https://{storefront}.understory.io/checkout/581aa2f831d1b7fd29df7982571865a1?eventId=b1d9f3a07c4e4e1fae9c2d6b8a3f5e10&variant/c0ffee254a1b4f0e9d3a7b6c5d4e3f21=2

This is the shortest path from your site to a paid booking — ideal for a "Book now" button on a page that already knows exactly what the customer wants.

One link, one outcome

An incoming deep link overwrites any checkout already in progress for that experience. This keeps links predictable: the visitor always ends up where the link points, regardless of what they were doing before.

Building links from the API

The ids in a deep link all come from the API, so you can generate links entirely from data you already fetch:

List experiences with Get experiences — each id is an {experienceId}.
List upcoming events with Get events filtered by experience_id — each event id is an eventId, and its sessions carry the dates you need for from.
(Optional) Fetch ticket variants with Get ticket variants — each id is a {variantId} for the variant/{variantId} parameter.

Render the resulting links on your own pages, and Understory handles availability, ticket selection, and payment from there.