Skip to content

React checkout

Web SDK quickstart

Mount AXYN checkout inside your React app.

Who this is for

Venues with a React site that want an inline embed (not a modal).

Availability

@axyn/web-sdk is a private AXYN workspace package today, not a public npm package. External partners should use the headless API path unless AXYN has explicitly provisioned a private package channel for their venue.

Do not run npm install @axyn/web-sdk against the public npm registry as a go-live step. Do not copy secrets from docs into your app.

Required props

CheckoutSpineRoot needs a real catalog payload and an API client. It does not take a lone eventId. Required props today:

PropRole
apiAxynApiClient (fixture helper or live client)
eventEventDetail
tiersTicketTier[]
addOnsEventAddOn[]
bundlesAddOnBundle[]
orgSlugOrganizer slug for URLs / analytics
stripePublishableKeyStripe publishable key
buildPaymentReturnUrlBuilds the return URL after Stripe
onPaymentCompleteHost navigation after pay

Optional: showPoweredByAxyn, seatCatalog, initialDraft. Pass seatCatalog from your host BFF when the event is reserved_seat.

axyn.events uses TicketPanel internally. That is not the partner embed path. Partners mount CheckoutSpineRoot with a server BFF.

Confirm prop names against the private @axyn/web-sdk TypeScript types supplied through your install channel.

Next.js server rendering

The SDK sanitizes organizer HTML with DOMPurify, which runs on jsdom on the server. jsdom cannot be bundled, so a Next.js host must keep it external:

// next.config.js
module.exports = {
  transpilePackages: ['@axyn/web-sdk'],
  serverExternalPackages: ['isomorphic-dompurify'],
};

Without it, next build fails while prerendering with ENOENT ... default-stylesheet.css.

Fixture mount (local)

Use the SDK fixture catalog to verify structure without a live API key.

'use client';

import {
  AxynProvider,
  CheckoutSpineRoot,
  createFixtureCheckoutApiClient,
  demoAddOnBundles,
  demoAddOns,
  demoEventDetail,
  demoTicketTiers,
} from '@axyn/web-sdk';
import '@axyn/tokens/css';
import '@axyn/web-sdk/token-aliases.css';

export function Tickets() {
  const api = createFixtureCheckoutApiClient(
    {
      baseUrl: process.env.NEXT_PUBLIC_AXYN_API_URL ?? 'http://localhost:4001',
      getAuthHeaders: async () => ({}),
    },
    {
      tiers: demoTicketTiers,
      addOns: demoAddOns,
    }
  );

  // analyticsConsent: true only once your banner grants Analytics
  // (see Analytics consent below).
  return (
    <AxynProvider theme="system" analyticsConsent={false}>
      <CheckoutSpineRoot
        api={api}
        event={demoEventDetail}
        tiers={demoTicketTiers}
        addOns={demoAddOns}
        bundles={demoAddOnBundles}
        orgSlug="demo"
        stripePublishableKey={
          process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY ?? 'pk_test_replace_me'
        }
        buildPaymentReturnUrl={({ orgSlug, eventId, orderId }) => {
          const base = `/complete?org=${encodeURIComponent(orgSlug)}&event=${encodeURIComponent(eventId)}`;
          return orderId
            ? `${base}&orderId=${encodeURIComponent(orderId)}`
            : base;
        }}
        onPaymentComplete={async ({ orderId }) => {
          window.location.assign(
            `/complete?orderId=${encodeURIComponent(orderId)}`
          );
        }}
      />
    </AxynProvider>
  );
}

Confirm export names against your private @axyn/web-sdk package if this snippet drifts. Do not invent props.

Live catalog

For a real event, load event / tiers / addOns / bundles from the AXYN catalog API (server-side preferred), then pass them into CheckoutSpineRoot with a live AxynApiClient.

Stripe card entry needs the live buyer stack (auth + payments), not fixture mode alone.

The first-party funnel beacon (POST /v1/events/:id/views: view, tier_select, checkout_start) feeds the organizer's funnel. It is off by default. It runs only for an event where the organizer turned on Analytics on partner embeds in Organizer Admin (the event's partner_embed_analytics_enabled). Until then the SDK sends nothing and stores no session key, and the API refuses funnel facts for that event.

It also needs your visitor's consent. analyticsConsent is off unless you pass true: if you pass nothing, the SDK sends no funnel facts and stores nothing in the browser for analytics (no session key, no visitor id), and no order is linked to a journey. Pass true only after your cookie banner or CMP records the visitor's Analytics consent:

<AxynProvider analyticsConsent={cmp.analyticsGranted === true}>

When it flips to true, the pending view posts. It can never turn the beacon on by itself: the organizer's switch must be on too. The browser's Global Privacy Control signal (navigator.globalPrivacyControl) always opts the buyer out, even when you pass true. The session key is per organizer, and the beacon never goes to an ad platform.

Once analytics is allowed, the SDK also keeps a random returning-visitor id in local storage (axyn_funnel_visitor:<organizer>) for up to 30 days from the day it was made, so a buyer who looks on Monday and buys on Thursday is counted as one visitor. It is separate for every organizer and is never extended. It is removed when analyticsConsent goes from true to false while the checkout is on the page, or when a Global Privacy Control signal appears. If the visitor withdraws consent somewhere else on your site, call clearFunnelVisitorKeys() (from @axyn/web-sdk/telemetry) in your consent tool's withdraw handler.

If the organizer turns it on, add AXYN to your privacy policy. Suggested copy/paste text is in the partner docs: Privacy policy copy for embed analytics.

CSS

Import tokens first, then SDK sheets. Minimum for the spine:

import '@axyn/tokens/css';
import '@axyn/web-sdk/token-aliases.css';

Add checkout / drawer / seats CSS subpaths as you use those surfaces.

Stripe

Payment uses a client secret returned by AXYN. Never create a PaymentIntent directly for AXYN inventory. Details: Stripe wrappers.

Aggregators

Multi-venue platforms use the same SDK primitives. Go-live for aggregators is white-glove (see portal /aggregators). Brand presets and Powered by AXYN policy are covered in Theming.

Next