Storefront API

The Storefront API is the browser-side half of selling on a custom site. The frontend calls orriven directly with a publishable key that is safe to ship in page code, reads the published catalog, and — when the buyer has picked what they want — creates a checkout session and sends them to its url. From there orriven’s hosted pages do the rest: collect whatever the site did not, hold the seat, take payment on Stripe, show the order result, and return the buyer to the site. Capacity, settlement, fulfilment, and the ticket email are the platform’s job. The integrator builds only the sales page.

There is no sign-in to build and none to borrow. The platform hosts no attendee accounts: after a purchase the buyer receives an email with their entry-pass link, and every hosted page they open asks for that email before it shows anything. A “my tickets” area on a custom site is built server-side with the Developer API — the integrator authenticates the person, orriven returns their registrations and pass links.

Two keys, two shapes

	Secret key (`osk_…`)	Publishable key (`opk_…`)
Lives in	Server only	Frontend — public by design
Scope	The whole Business Unit, read/write	The Business Unit’s public storefront: published events, checkout
Surface	`/v1`	`/storefront/v1`
Sees counts, drafts, attendee lists	Yes	Never
If leaked	Rotate immediately	Equivalent to knowing the site’s URL

The two are mutually exclusive on the wire: a publishable key on /v1 returns the same 401 as an invalid key, and a secret key on /storefront/v1 does too. A leaked publishable key can read the published catalog and place rate-limited orders — nothing more. It cannot read anyone’s registration, see numeric availability, or touch the Developer API. Revoking it works like revoking any key: immediately.

Setup

Create a publishable key

On the API keys page choose Publishable key and list the origins the site runs on — https://tickets.example.com, one per line (http://localhost:… is fine for development). The key serves this Business Unit’s storefront; there is nothing else to pick. It appears in full in the list at any time. There is no one-time secret, because the key is public.

Publish the event

The storefront only ever returns published events. An event’s status is the one go-live switch. Set the event’s page address on its Public page too: that is where promotion links land and where the hosted pages send buyers back by default.

Call from the browser

const BASE = "https://openapi.orriven.com/storefront/v1";
const KEY = "opk_…";   // safe to ship

const res = await fetch(`${BASE}/events`, {
  headers: { Authorization: `Bearer ${KEY}` },
});

CORS is open to exactly the origins on the key. Requests from any other origin are refused. That check stops someone embedding the key in another site.

Catalog

GET /events lists the Business Unit’s published events (each with its siteUrl, the page address set in the console). GET /events/{publicId} returns everything a sales page needs — ticket types (soldOut is a boolean, never a count), add-ons, bundles, the open agenda, speakers, sponsors, published registration forms. Hidden ticket types are absent. GET /events/{publicId}/redemption-codes/lookup?code= is the one path to them. Every invalid code returns the same 404. Add ?lang= to receive the organizer’s translated content when the event offers other languages. The sale window is public information: on-sale types carry opensAt/closesAt, and upcomingTicketTypes lists types announced but not yet on sale — name, price, perks, and the opensAt instant a countdown ticks toward. Announcement is all it is: placing an order for an upcoming type still refuses until the window opens.

Checkout sessions — the hosted checkout

When the buyer has chosen, create a session with their selection and whatever is already known about them, then send them to url:

const { url } = await post(`${BASE}/events/${publicId}/checkout-sessions`, {
  items: [{ itemType: "registration_type", itemId: ticketTypeId, quantity: 1 }],
  email: "ada@example.com",           // optional — the hosted page asks if missing
  name: "Ada",                        // optional
  redemptionCode: "VIP2026",          // optional
  promotionCode: params.get("pl"),    // optional — attribution, never a gate
  returnUrl: location.origin + "/thanks",
});
location.assign(url);

The hosted checkout page shows the items and prices, collects what is missing — email, name, the ticket’s registration form, add-ons — then places the order (a 15-minute hold), confirms it, and for a paid order hands the buyer to Stripe. It speaks the event’s languages and carries the event’s name and the Business Unit’s name and logo.
After payment (or immediately for a free order) the buyer lands on the hosted order page. Its Return to organizer button goes to the returnUrl with ?order=<orderNumber>&status=<status> appended — paid is the one to act on. Without a returnUrl the button uses the event’s page address.
A session lives 24 hours and holds nothing. The seat is held only once the buyer places the order from it. A buyer already registered in the event is acknowledged on the hosted page, never sold a second seat.
A prefilled email is used as-is: the page shows it masked and does not let the buyer change it, so a guessed session link never reveals an address.

Direct checkout

To render checkout in the frontend instead, the three-step flow is still callable from the page: place, confirm, poll.

// Place: holds its seats for 15 minutes. `email` is required.
const { order } = await post(`${BASE}/events/${publicId}/orders`,
  { email, ticketTypeId, returnUrl: location.origin + "/thanks" });

// Confirm: a free order settles here…
const done = await post(
  `${BASE}/events/${publicId}/orders/${order.orderNumber}/confirm`, {});

// …a paid one returns { status: "awaiting_payment", paymentUrl } —
// send the buyer there, then poll GET /events/{publicId}/orders/{orderNumber} until "paid".

successUrl/cancelUrl on confirm are optional. Omit them and Stripe returns the buyer to the hosted order page (which then returns them to the returnUrl). Pass them to take the buyer straight back to the site’s own pages instead (absolute https; plain http allowed on localhost). Every order payload carries orderUrl (its hosted page) and, while it is still open, checkoutUrl. A buyer already registered is acknowledged with alreadyRegistered: true, never sold a second seat.

”My tickets” on the site

The storefront has no account area. A buyer’s own pages are the hosted ones: the entry pass link the platform emails them shows their QR, wallet passes, certificate, and surveys, and asks for their email each time it is opened on a new device. To offer the same inside a custom site, build it server-side with the Developer API: authenticate the person, call GET /v1/events/{eventId}/registrations?email=, and link each registration’s passUrl. Regenerating a leaked link is one call.

Interactive reference

The surface describes itself: $BASE/storefront/openapi.json is the OpenAPI 3.1 document and $BASE/storefront/docs the try-it reference. Every endpoint also has a page in the Storefront endpoints group in this site’s sidebar. Date versioning works as on the Developer API: the key pins its creation-time version, Orriven-Version overrides per request.

Rules

Never numbers. This surface returns soldOut: true/false and nothing else about capacity. Live counts belong to the Developer API’s availability, behind the secret key.
404, not 403. A draft event, another Business Unit’s event, and a nonexistent id are indistinguishable from this side.
Rate limits are per key and per visitor. Checkout-session creation and order-number reads carry a per-(key, IP) limit on top of the key’s own budget. Back off on 429.
Storefront traffic is request-logged, not audited. Calls appear in the console’s developer log for debugging. Checkouts are the buyer’s actions and do not enter the organization audit log. Automations and the ticket email still fire on fulfilment.

API keys

Creating publishable keys and managing their origins.

Checkout (secret key)

The server-side flow, checkout sessions included, and the “my tickets” page.

Get started

Reference

Endpoints

Storefront endpoints

Two keys, two shapes

Setup

Catalog

Checkout sessions — the hosted checkout

Direct checkout

”My tickets” on the site

Interactive reference

Rules

API keys

Checkout (secret key)

​Two keys, two shapes

​Setup

​Catalog

​Checkout sessions — the hosted checkout

​Direct checkout

​”My tickets” on the site

​Interactive reference

​Rules

​Related

API keys

Checkout (secret key)

Two keys, two shapes

Setup

Catalog

Checkout sessions — the hosted checkout

Direct checkout

”My tickets” on the site

Interactive reference

Rules

Related