Registration Capture

Public journey registration is the seam a custom registration portal uses to submit a guest into an event-backed journey.

Backend Data Prerequisites

Before a custom portal submits registrations, provision:

Data Where Purpose
Active tenant and D1 bindings Control-plane tenant registry Allows edge gateway tenant resolution
journey_builder feature row Tenant config D1 feature_catalog Allows admin journey routes
Event row Tenant ops D1 events_studio_events Registration target and capacity source
Journey surface Tenant ops D1 journey_surfaces via /v1/journeys Public configuration and event binding
Optional staff links Tenant ops D1 journey_staff_roster, journey_staff_booking_links Personal booking links
Registration rows Tenant ops D1 events_studio_guests Written by public registration capture
Visit rows Tenant ops D1 events_studio_page_visits Written by public journey visit tracking

The API creates and updates journey_surfaces, default staff rows, events_studio_guests, event counts, and visit rows. It does not create the backing events_studio_events event for you.

SDK Submit

const result = await voyage.journeys.submitPublicRegistration("private-preview", {
  selectedTickets: [{ tierId: "general", quantity: 1 }],
  guest: {
    firstName: "Ada",
    lastName: "Lovelace",
    email: "ada@example.com",
    phone: "+15555550123",
  },
  answers: {
    accessibility: "Front-row seating",
    interests: ["workshop", "networking"],
  },
  agreedToTerms: true,
  surfaceType: "journey",
});

For a browser portal, submit the form to your own backend first. That backend should hold VOYAGE_API_KEY, call the SDK, then read the registration back before returning confirmation to the browser. See examples/custom-registration-portal for the concrete pattern.

Server Behavior

The public journey registration route:

  1. Resolves a live journey by slug or enabled personal booking link.
  2. Normalizes the live JourneyConfig.
  3. Resolves the event from the row event_id or config _eventId.
  4. Validates ticket selection, guest email, names, phone, answers, and terms.
  5. Creates an events_studio_guests row through createEventsStudioRegistrationForTenant.
  6. Enforces event state, closures, capacity, and duplicate active registration by email.
  7. Refreshes event registration counts.
  8. Returns an order reference, registration DTO, and event DTO.

Common Error Codes

Code Meaning
JOURNEY_NOT_PUBLISHED Slug does not resolve to a live journey
VALIDATION_ERROR Payload failed shape or route validation
JOURNEY_EVENT_REQUIRED Journey has no event binding
NOT_FOUND Backing event was not found
INVALID_STATE Event is cancelled or archived
EVENT_CLOSED Event closure blocks registration
EVENT_FULL Capacity is exhausted
ALREADY_REGISTERED Email already has an active registration

Read Back

After submit, read back the created registration with guest ID and email:

const lookup = await voyage.journeys.getPublicRegistration(
  "private-preview",
  result.registration.guestId,
  result.registration.email,
);

console.log(lookup.registration.status);