Embed the ticket shop natively

Quickstart

There are two ways to a running shop. Both use the same script and the same element; they differ in who creates the session.

Without a backend

The element creates its own browser session for your publicKey, limited to the domains you allowed. Set cart-scope="tab": without a server identity, the default "shared" ends in an explicit error. Each browser tab then has its own cart. The session is anonymous: visitors browse and fill the cart. Before registration, element.config.onUserRequired must return a user-bound session token from a server; without it the shop stops at the cart with a notice.

<!-- Site without a backend: load the script once, place the element. -->
<script src="https://developers.aditus.com/api/embed/v1/aditus-shop.js" defer></script>

<aditus-shop
  public-key="pk_your_site"
  cart-scope="tab"
></aditus-shop>

With a backend

Your server creates the session with the mint secret and decides who the buyer is. Pass the returned token to the element. With a buyer email, the default cart-scope "shared" keeps one cart across all tabs.

// 1. On your server: create a session. The mint secret never leaves the server.
const res = await fetch("https://developers.aditus.com/api/shop/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`,
    "Content-Type": "application/json",
  },
  // email comes from your own login session, never from the browser request.
  body: JSON.stringify({ publicKey: "pk_your_site", email: user.email }),
});
const { sessionToken } = await res.json();

<!-- 2. In your page: pass the token from your server to the element. -->
<script src="https://developers.aditus.com/api/embed/v1/aditus-shop.js" defer></script>

<aditus-shop
  public-key="pk_your_site"
  session-token="SESSION_TOKEN_FROM_YOUR_SERVER"
></aditus-shop>

Replace pk_your_site with your publishable key from the ADITUS admin. developers.aditus.com is the production address for the script and the API. Both ways are described in detail further down.

The technology behind the micro-frontend

The micro-frontend renders the complete purchase flow (events, articles, cart, registration, payment, completion) into your page's DOM. It uses your page's layout, and your CSS can style every part of it.

Your site is trusted: your server authenticates the user before creating an identified session. The embed deliberately renders in your page's light DOM, without iframe isolation. Scripts on your page can access the DOM and browser storage, so secure your site and its third-party scripts. Public-key origin authorization is not user authentication. Payment credentials are entered only on the external payment provider's page.

Payment security, PCI & CSP

The purchase preparation renders in your page. The payment itself happens on the payment provider's page, so no payment data passes through your page.

Compared with iframe and shadow DOM

The approaches compared

Alternative: source package (self-delivered)

Alternatively, download the source package from your ADITUS instance and bundle it into your app (Vite, webpack, Next.js or Nuxt). This is self-delivered: you must reinstall, rebuild and deploy updates yourself. It is not on public npm.

SSR apps: Next.js & Nuxt

The micro-frontend is deliberately client-only. Its content is live and session-bound: availability, prices and the user's cart exist only for an authenticated session at request time, so there is nothing meaningful your server could pre-render. mount() creates a fresh client-side React root (createRoot); server-rendered markup inside the container is not hydrated. That makes SSR integration simple and predictable: render a placeholder on the server, mount on the client, and reserve the space so nothing jumps.

// Next.js (App Router): the micro-frontend is deliberately client-only.
"use client";
import { useEffect, useRef } from "react";
import { mount, type ShopHandle } from "@aditus/shop-embed";

export function TicketshopSection({ sessionToken }: { sessionToken: string }) {
  const el = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!el.current) return;
    const handle: ShopHandle = mount(el.current, {
      publicKey: "pk_your_site",
      sessionToken, // issued server-side, passed to the client component as a prop
      cartScope: "shared", // the default in frameworks too; trusted server identity
    });
    return () => handle(); // unmount on route change
  }, [sessionToken]);

  // Server and client render the SAME placeholder and so avoid a hydration mismatch.
  // min-height reserves the space so the page does not jump on mount (CLS).
  return <div id="aditus-shop" ref={el} style={{ minHeight: 560 }} />;
}

The micro-frontend needs a session

import { mount } from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// Without a sessionToken the micro-frontend stays inactive: it only shows a
// neutral notice and starts no API calls: no cart, no registration,
// no checkout. Only a session activates the shop.
mount(el, {
  publicKey: "pk_your_site",
  // sessionToken missing -> the shop is not activated.
});

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@aditus/shop-embed";

// getElementById can return null. Check it properly in TypeScript instead of using "!".
const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// AditusShopConfig types every option and gives you autocompletion.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_your_site",   // required as soon as a session is involved
  sessionToken,                // issued by your backend, keep it in memory only
  cartScope: "shared",          // default; requires a trusted server identity
};

const handle: ShopHandle = mount(el, config);

// The micro-frontend sends the X-Aditus-Session header with every shop call.
// On logout, revoke the session on the server and remount/update.

On reload, a valid journey pointer lets the embed request the live server cart under the same authorized scope and trusted identity. It is not authorization and does not guarantee recovery after session/cart expiry, storage clearing or user change. Explicit tab scope does not merge other tabs' journeys; default shared scope still enforces the single-writer checkout lock.

Payment return uses aditus-return (an opaque, short-lived, server-bound return token) plus aditus-pay. It can return in the same or a new tab, but the server requires an authorized client/origin and the matching trusted identity. Return query parameters are not proof of purchase. The server resolves payment state and finalizes the token-bound attempt; an unknown outcome stays blocked for reconciliation, never blindly retried as a new purchase. Expired or unauthorized returns are explicit errors, not permission to create a replacement order.

Assigning a payment provider only prepares payment: the summary remains editable. The lock starts at the actual redirect, after required consents. A cancel/error return query is not proof of failure: the backend rechecks the cart; Completed with order.id reconciles completion. Retry is allowed only after confirmed successful provider-assignment removal for that same cart; ambiguous outcomes stay blocked and can be rechecked. This does not guarantee a refund or rule out late settlement.

Redirect payment: what your page must do for the session

• Serve the configured return URL with the embed mounted. Preserve aditus-return and aditus-pay through routing or required login redirects; never treat aditus-pay=success as authorization. Supply a valid session for the same trusted identity and publicKey. Keep the selected cartScope, and do not clear the journey or start a second checkout to work around a pending, expired or uncertain return.

Want a deliberate fresh start with a real "start over" button? The package exports clearJourney(): call it before mounting (or re-mounting) and the locally persisted journey record for the current page is dropped, so the next mount starts fresh at the entry point. Only the local resume pointer is removed; any server-side cart state is untouched.

Entry point: event home, articles or voucher

Where the journey starts is decided by your server when it creates the session, never by the browser. Without eventSlug the micro-frontend opens on the event overview. With eventSlug choose the article list (default), the event home page or the voucher form using startMode; assortment restricts the article list.

Article selection and voucher continuation follow the original shop's recommendation-based route. Without a usable upsell offer or cross-selling, go directly to ticket personalisation through the normal login/session gates; with cross-selling, show the cart. A usable upsell offer opens its dialog first. Skip goes to personalisation without cross-selling, or to the cart with it. A confirmed upgrade goes to the cart; closing the dialog leaves the selection in place. Routing never writes registration in the background.

Shop-visible assortments can have direct entry actions. If the session pins one assortment, home shows only that assortment's ticket action, not the full list or the voucher action.

startMode: "home" opens the event home page. Visitors choose Buy tickets or Redeem voucher there; no cart is created and no code redeemed merely by opening the page. Buy tickets enters the article list (limited by assortment if set); Redeem voucher opens the code form. Without eventSlug, the event overview appears first and the chosen event then opens its home page. A prepared voucher cart or resumable journey still takes priority over a fresh start.

// Server side: use the same session route as above, only the body varies.
// You build user and your backend's login/session route yourself.
// eventSlug sets the event. startMode also works without a slug (event
// selection first, then the mode); only assortment needs the slug
// (otherwise 400 start_option_requires_event_slug).

// 1) Article start (default): the event's article selection
const bodyArticles = { publicKey, email: user.email, eventSlug: "ExperienceDaysv52024" };

// 2) Assortment start: only one assortment (id or exact name, case-insensitive)
const bodyAssortment = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  assortment: "Pressetickets",
};

// 3) Voucher start: "Redeem voucher / register ticket" first
const bodyVoucher = {
  publicKey, email: user.email,
  eventSlug: "ExperienceDaysv52024",
  startMode: "voucher" as const,
};

const res = await fetch("https://developers.aditus.com/api/shop/session", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`, "Content-Type": "application/json" },
  body: JSON.stringify(bodyVoucher),
});
const { sessionToken }: { sessionToken: string } = await res.json();

/* Voucher form: the same tokens and role hooks as the rest of the journey */
.aditus-shop__voucher-panel  { /* panel around hints + form (general panel hook) */ }
.aditus-shop__voucher-hints  { /* the two hint lines */ }
.aditus-shop__voucher-form   { /* form */ }
.aditus-shop__voucher-input  { /* code field (also .aditus-shop__field-input) */ }
.aditus-shop__voucher-redeem { /* "Redeem" button (data-variant="primary") */ }
.aditus-shop__field-error    { /* rejection reason, role="alert" */ }
/* Event home page and event actions: structured expert hooks */
.aditus-shop__home             { /* home page; root data-step="home" */ }
.aditus-shop__home-info        { /* event information */ }
.aditus-shop__home-info-head   { /* heading and logo */ }
.aditus-shop__home-info-name   { /* event name */ }
.aditus-shop__home-info-date   { /* date */ }
.aditus-shop__home-info-venue  { /* venue */ }
.aditus-shop__home-info-desc   { /* description */ }
.aditus-shop__home-actions[data-variant="tiles"] { /* tiles, alternatively compact */ }
.aditus-shop__home-action[data-kind="articles"] { /* buy tickets; also home / voucher / assortment */ }
.aditus-shop__home-action-icon    { /* icon */ }
.aditus-shop__home-action-body    { /* text group */ }
.aditus-shop__home-action-title   { /* label */ }
.aditus-shop__home-action-desc    { /* optional description */ }
.aditus-shop__home-action-chevron { /* arrow */ }
/* Phase hook: [data-step="voucher"] on the root */

Voucher links: redeem a code from the URL

Vouchers are often sent out as links to your page with the code as a query parameter, e.g. …/tickets?code=ED24-ADITUS. The micro-frontend can take that code over and redeem it without the visitor typing anything. Two handover paths exist; both end in the same redemption call and behave identically afterwards.

// Voucher links point to your site: https://your-site.com/tickets?code=ED24-ADITUS
// The route, request and authentication below are examples for your own website.
// The parameter name is up to you: here "code".

// Option A (browser): the micro-frontend reads the parameter itself.
import { mount } from "@aditus/shop-embed";

mount(document.getElementById("aditus-shop")!, {
  publicKey: "pk_your_site",
  sessionToken,                 // session with eventSlug (article or voucher start)
  voucherCodeParam: "code",     // read ?code=… once, remove it from the address bar, redeem it
});
// Web Component: <aditus-shop public-key="pk_your_site" voucher-code-param="code"></aditus-shop>

// Option B (server): your backend hands the code over when it creates the session.
// (Express example; the code never goes into the session response, only into the session context.)
app.get("/tickets", async (req, res) => {
  const code = typeof req.query.code === "string" ? req.query.code : undefined;
  const r = await fetch("https://developers.aditus.com/api/shop/session", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      publicKey: "pk_your_site",
      email: req.user?.email,
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher",       // or omit: article start, the code lands in the first cart
      voucherCode: code,          // undefined = normal start without a code
    }),
  });
  const { sessionToken }: { sessionToken: string } = await r.json();
  // The page additionally mounts with voucherCodeParam: "code" so that ?code= disappears
  // from the address bar (the session code wins, it is redeemed only once).
  res.render("tickets", { sessionToken });
});

Optional: reserve the voucher during server-side session creation

If your site wants to show voucher rejection before opening the embed, set redeemVoucherOnMint: true on the trusted POST /api/shop/session. Unlike ordinary voucherCode handover this creates a cart for the authenticated user and actually reserves the voucher there before session creation succeeds; it is not an extra preliminary validation request. On success, pass only the returned sessionToken to the browser. The embed resumes that same cart without creating another or redeeming twice, whether startMode is voucher or articles. Without the flag, the normal voucherCode handover applies.

This mode requires voucherCode, a pinned eventSlug, an identified user (email; not anonymous) and the Idempotency-Key header; it is only available with a mint secret on your backend, not POST /shop/embed-session in the browser. It supports voucher/ticket codes, not PromotionCode. The code is reserved in a cart, not yet registered or issued as a ticket: the shopper must still complete registration and checkout. Further checks by the shop API may still reject later steps; a successful session creation does not guarantee final issuance.

// Server side of your website: one voucher attempt, no additional check call.
// You implement the authentication and storage of this attempt yourself.
// attemptKey is a random id your backend stores durably per logical redemption
// attempt (e.g. crypto.randomUUID()). On network errors, resend the same id
// and the SAME body; never generate a new one before a retry.
async function prepareVoucherSession(
  user: { email: string },
  code: string,
  attemptKey: string,
) {
  const response = await fetch("https://developers.aditus.com/api/shop/session", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ADITUS_MINT_SECRET}`,
      "Content-Type": "application/json",
      "Idempotency-Key": attemptKey,
    },
    body: JSON.stringify({
      publicKey: "pk_your_site",
      email: user.email, // only from your authenticated server session
      eventSlug: "ExperienceDaysv52024",
      startMode: "voucher", // or "articles"
      voucherCode: code,
      redeemVoucherOnMint: true,
    }),
  });
  const result: {
    sessionToken?: string; expiresAt?: number; voucherRedeemed?: boolean;
    error?: string; reason?: string; upstreamStatus?: number;
  } = await response.json();

  if (response.ok && result.sessionToken && result.voucherRedeemed === true) {
    // Only now pass it to the browser and mount the embed.
    return { sessionToken: result.sessionToken, expiresAt: result.expiresAt };
  }
  if (response.status === 422 && result.error === "voucher_rejected") {
    // Your own UI: handle the business rejection using reason, do not open the embed.
    // Translate only documented reason values into your own texts.
    return { rejected: result.reason };
  }
  if (response.status === 409 && result.error === "voucher_preparation_uncertain") {
    // Uncertain stays uncertain; a repeated POST never turns it into a success.
    // If the Shop API cannot provide the cart id, manual clarification is needed.
    throw new Error("Redemption uncertain; clarify with ADITUS, do not book again.");
  }
  if (response.status === 410 && result.error === "voucher_preparation_expired") {
    throw new Error("Prepared session no longer valid; no blind new session.");
  }
  // 400 = invalid request/key, 409 = conflict/attempt in progress,
  // 502/503 voucher_upstream_error = infrastructure, not a business error.
  throw new Error(`Session creation not completed (${response.status})`);
}

Treat 422 voucher_rejected with its sanitized reason as a business rejection on your site: do not mount an embed without a token. A malformed configuration/key returns 400; 409 idempotency_conflict means the same key was used for different inputs, while a pending/uncertain operation must not be mistaken for an invalid voucher; 502/503 and network timeouts are infrastructure/unknown outcomes, not voucher rejections. Persist a new random Idempotency-Key per logical attempt on your server and retry only with the same key and identical inputs. Never retry with a new key after an uncertain outcome: the reservation may already exist. Avoid logging code, email, raw API errors or session tokens.

A successful session creation can leave a reserved cart even if the shopper never opens the page. Known-cart cleanup on rejection/revocation is best effort; a boot/60-second sweeper retries up to 25 records per tick. A valid completed attempt with the same key and input replays its result. If the original token is expired, revoked, completed, deleted or transferred, it returns 410 voucher_preparation_expired instead; do not blindly recreate the reservation. An authorized successor may extend or transfer the preparation when it first accesses the cart. Removing the code from your page URL does not release a reservation.

Exact session creation errors: 400 invalid_redeem_voucher_on_mint / voucher_preparation_requires_user_event_code / invalid_idempotency_key (or ordinary validation); 422 voucher_rejected carries reason and upstreamStatus, never raw upstream code or message. Supported reasons: unknown · articleLimit · exhausted · ownership · used · reserved · limit · cartLimit · locked · canceled · otherEvent · legitimation · rejected · unsupported_code_type.

409 idempotency_conflict means changed inputs; voucher_preparation_pending includes Retry-After: 2 seconds, and voucher_preparation_uncertain remains uncertain on replay (not an automatic eventual success). 410 voucher_preparation_expired means the original preparation cannot be replayed. 502/503 voucher_upstream_error means upstream failure. If upstream created a cart but never returned its ID, automatic reconciliation or release is impossible with the available API: the uncertain record is retained and the server will not create another cart on retry. Arrange manual clarification with ADITUS before beginning a new attempt. If session-context cannot load, the embed shows an error/retry rather than silently starting a fresh cart.

Try all three live in the Integration Tester: create a session with eventSlug, pick startMode or an assortment, mount, and watch the request log. The demo system accepts the test voucher ED24-ADITUS on ExperienceDaysv52024 (each redemption reserves the ticket for about 20 minutes; backing out releases it). Open the Integration Tester

Optional: browse anonymously, sign in at checkout

You do not have to know who the user is up front. Mount with a guest session and the micro-frontend lets an anonymous visitor browse events, pick articles and fill the cart. Only when they move past the cart, toward registration and checkout, does it ask you to establish the real user, via the onUserRequired callback. The rest of the flow then continues with the cart preserved.

1. 1

   Mount with a guest session

   A session token is still required to activate the shop, but it can be a guest session: simply create it without the email field, no placeholder address needed. The visitor browses and fills the cart under it.

2. 2

   Leaving the cart triggers onUserRequired

   The moment the visitor advances past the cart, the micro-frontend calls your callback once and shows a neutral pending state. Authenticate the user (login/SSO), then create a fresh, user-bound session the exact same way as the first one: server-to-server with your secret. The later user is established via that server-to-server session creation too. The secret never reaches the browser and the user is never set in client code. Your callback only relays the resulting opaque token. Crucially, your backend derives that identity from its own authenticated session (cookie/JWT); it must never accept the email or user id from the browser, or a malicious visitor could request someone else's session and read their personal data via the prefill.

3. 3

   Return the new token. The cart carries over

   Return the fresh session token and the micro-frontend swaps it in and binds the identified user to the existing cart. The cart, its articles and any timeslots survive unchanged. Then it enters registration. Return null to abort. The visitor simply stays on the cart, no error.

4. 4

   Omit onUserRequired for a fixed user

   If you leave the callback out, nothing changes from the classic flow: mount with a user-bound session and the micro-frontend acts as that user from the very first step.

import {
  mount,
  type ShopHandle,
  type AditusShopConfig,
} from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

// A guest session token is enough to mount: created server-to-server as
// usual, just without the email field (no placeholder address needed). The
// visitor may browse and fill the cart before a specific user is known.
const config: AditusShopConfig = {
  apiBase: "https://developers.aditus.com/api/shop",
  publicKey: "pk_your_site",
  sessionToken: guestSessionToken,

  // Called once as soon as the visitor leaves the cart towards registration.
  // This is where you authenticate the user (login/SSO) and create a new,
  // user-bound session server-to-server.
  // Return the fresh token -> the micro-frontend adopts it and rebuilds the
  // cart under the identified user (articles are kept). Return null to
  // cancel -> the visitor stays in the cart, without an error.
  onUserRequired: async () => {
    // Calls only your backend, with no identity in the payload. Your backend reads
    // the signed-in user from its own session (cookie/JWT) and creates the session
    // server-side for exactly this identity. Never pass the email from the browser,
    // otherwise an attacker could insert someone else's address here and reach
    // that person's personal data through the prefill.
    // host.loginAndMintSession(): Promise<string | null> is your own function.
    // Implement login/SSO + authenticated backend call + server-side session creation on your website.
    // On cancel the function returns null; on failure it throws explicitly.
    return host.loginAndMintSession();
  },
};

const handle: ShopHandle = mount(el, config);

GA4 / e-commerce events (optional)

The micro-frontend can report the shopping funnel to your analytics, but only if you ask it to. It bundles no gtag, no GTM and no GA SDK, loads nothing, sets no cookies and sends nothing on its own. You add one optional callback, onEvent, and receive typed events already shaped in Google's GA4 Enhanced-Ecommerce schema. Omit onEvent and nothing changes. Which tool you feed, and whether you have consent to send, stays entirely on your side.

import {
  mount,
  type ShopHandle,
  type ShopAnalyticsEvent,
} from "@aditus/shop-embed";

const el = document.getElementById("aditus-shop");
if (!el) throw new Error("Mount target #aditus-shop not found");

const handle: ShopHandle = mount(el, {
  publicKey: "pk_your_site",
  sessionToken,
  // Optional. If you leave out onEvent, nothing changes: the micro-frontend
  // sends nothing, loads no gtag/GTM/GA SDK and sets no cookies.
  // Tool, consent and mapping stay entirely with you. This example uses GA4 via gtag.
  onEvent: (event: ShopAnalyticsEvent) => {
    // Consent is yours: only send once the user has agreed.
    if (!hasAnalyticsConsent()) return;
    // The events already follow the GA4 schema (name + items/value/currency ...),
    // so pass them to gtag 1:1.
    const { name, ...params } = event;
    window.gtag?.("event", name, params);
  },
});

publicKey vs. sessionToken

Keep the two separate. They answer different questions and are paired, not interchangeable.

Endpoint & response reference

Both calls come from your backend: it authenticates with your client's mint secret (generated in the ADITUS admin console) as a Bearer token. One session per login is the normal pattern; the browser only ever sees the resulting token. Sites without a backend do not use these endpoints: the element creates its browser session itself via the domain-restricted POST /api/shop/embed-session (public-key with cart-scope="tab").

You can try this exact flow with your own credentials in the integration tester. Create a session, mount the shop and walk through the journey.

Create a session: request

Create a session: response (200)

Revoke a session

DELETE /api/shop/session/:token with the same Bearer secret. The secret must belong to the client the session was created for. Call it on logout or a kiosk reset so the token dies with your own session. For anonymous (token-scoped) sessions the call also deletes the session's carts in the Shop API. Coupon reservations held by those carts are released immediately, not after the cart expiry. Response: { "revoked": true, "carts": { "scope": "token", "deleted": 1, "failed": 0 } } (revoked false if the session had already expired; scope "identity" for user-bound sessions, whose carts outlive a single token and stay untouched). Revoking is idempotent and safe to fire-and-forget.

Server-to-server reads

A backend that drives the micro-frontend (a kiosk shell, an onsite shop) usually needs tenant facts before it creates a session: which events exist and are on sale, which languages the shop speaks, which lookup lists and branding apply. Four read endpoints answer that with the same credentials as session creation (Bearer mint secret + X-Aditus-Public-Key header, same rate limit, Cache-Control: no-store). They are whitelisted projections of the Shop API, never a raw passthrough; ?language= (or Accept-Language, default de) picks the language of names. Errors: 400 invalid_public_key, 401 unauthorized, 503 shop_api_not_configured, 502 upstream_error.

Errors are explicit