Skip to content

Events ​

Public events: listings, tickets, registration, payment and self-service.

Quick start ​

Register for the first free ticket

ts
const events = await window.Portal.events.events();
const detail = await window.Portal.events.event(events[0].reference_num);
const occurrence = (detail.occurrences || [])[0];

const result = await window.Portal.events.register({
  occurrence_reference_num: occurrence.reference_num,
  ticket_type_reference_num: occurrence.ticket_types[0].reference_num,
  attendee_name: 'Ada Lovelace',
  attendee_email: 'ada@example.com',
});

if (result.requires_payment && result.payment && result.direct_payment_ref && result.order_reference_num && result.registration_reference_num) {
  const pay = await window.Portal.events.beginPayment({
    directPaymentRef: result.direct_payment_ref,
    itemRef: result.payment.item_ref,
    quantity: result.payment.quantity,
    orderRef: result.order_reference_num,
    registrationRef: result.registration_reference_num,
    accessToken: result.access_token,
    email: 'ada@example.com',
    mountSelector: '#pay',
  });
  await pay.confirm();
}

API reference ​

payment ​

The handle beginPayment() returns for an event registration.

confirm() ​

Call when the attendee presses pay.

ts
await payment.confirm();

Returns

Resolves when the call has completed.

window.Portal.events ​

Portal.events — public events: listing, tickets, registration, payment and self-service.

beginPayment() ​

Mounts the payment form for a registration that requires payment.

ts
const eventPaymentHandle = await window.Portal.events.beginPayment(opts);

Parameters

NameTypeRequiredDescription
optsPortalEventPaymentOptionsYesOptions of Portal.events.beginPayment(); most come from the payment block of register().

Returns

Resolves with a PortalEventPaymentHandle: The handle beginPayment() returns for an event registration.

calendarUrl() ​

The address of an .ics calendar file for a registration. Synchronous: it only builds the URL.

ts
const value = window.Portal.events.calendarUrl(referenceNum, token);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
tokenstringNoA token issued by the server (see the description above).

Returns

Returns a string.

cancelRegistration() ​

Cancels a registration.

ts
await window.Portal.events.cancelRegistration(referenceNum, token);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
tokenstringNoA token issued by the server (see the description above).

Returns

Resolves when the call has completed.

confirmPayment() ​

Tells the server the payment went through so the registration is confirmed.

ts
await window.Portal.events.confirmPayment(registrationRef, token);

Parameters

NameTypeRequiredDescription
registrationRefstringYesThe registration's reference.
tokenstringNoA token issued by the server (see the description above).

Returns

Resolves when the call has completed.

event() ​

One event with occurrences and ticket types.

ts
const eventDetail = await window.Portal.events.event(referenceNum, site);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
sitestringNoThe website's reference.

Returns

Resolves with a PortalEventDetail: An event with its occurrences and their ticket types (Portal.events.event()).

events() ​

Lists published events.

ts
const eventSummarys = await window.Portal.events.events(filter);

Parameters

NameTypeRequiredDescription
filterPortalEventsFilterNoFilter of Portal.events.events().

Returns

Resolves with an array of PortalEventSummary.

hold() ​

Reserves tickets for a few minutes while the attendee fills in the form. Pass the hold_reference_num to register().

ts
const result = await window.Portal.events.hold(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.occurrence_reference_numstringYesThe event date's reference.
payload.ticket_type_reference_numstringYesThe ticket type's reference.
payload.quantitynumberNoHow many.
payload.tier_reference_numstringNo—

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
hold_reference_numstringYesThe reference returned by hold().
expires_atstringNoISO time it expires.

joinWaitlist() ​

Puts someone on the waiting list of a sold-out occurrence.

ts
const result = await window.Portal.events.joinWaitlist(payload);

Parameters

NameTypeRequiredDescription
payloadobjectYesThe data to send.
payload.occurrence_reference_numstringYesThe event date's reference.
payload.ticket_type_reference_numstringNoThe ticket type's reference.
payload.attendee_namestringYes—
payload.attendee_emailstringYes—
payload.quantitynumberNoHow many.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
waitlist_reference_numstringYesThe waiting-list entry's reference.
positionnumberYes—

myRegistrations() ​

The signed-in attendee's registrations.

ts
const eventRegistrationRecords = await window.Portal.events.myRegistrations();

Returns

Resolves with an array of PortalEventRegistrationRecord.

passes() ​

The multi-event passes (season tickets) of a site.

ts
const result = await window.Portal.events.passes(siteRef);

Parameters

NameTypeRequiredDescription
siteRefstringYesThe website's reference.

Returns

Resolves with Array<Record<string, unknown>>.

redeemPass() ​

Uses a pass to register.

ts
const result = await window.Portal.events.redeemPass(passRef, payload);

Parameters

NameTypeRequiredDescription
passRefstringYes—
payloadRecord<string, unknown>YesThe data to send.

Returns

Resolves with the server's record as a plain object.

register() ​

Registers an attendee. Check requires_payment in the result.

ts
const eventRegisterResult = await window.Portal.events.register(payload);

Parameters

NameTypeRequiredDescription
payloadPortalEventRegisterPayloadYesWhat Portal.events.register() sends.

Returns

Resolves with a PortalEventRegisterResult: The answer to Portal.events.register().

registration() ​

One registration; a guest passes the access token.

ts
const eventRegistrationRecord = await window.Portal.events.registration(referenceNum, token);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
tokenstringNoA token issued by the server (see the description above).

Returns

Resolves with a PortalEventRegistrationRecord: A registration as the public / the signed-in attendee sees it.

releaseHold() ​

Gives held tickets back.

ts
await window.Portal.events.releaseHold(holdRef);

Parameters

NameTypeRequiredDescription
holdRefstringYesThe reference returned by hold().

Returns

Resolves when the call has completed.

scannerManifestUrl() ​

The address of the door-scanner app's manifest. Synchronous: it only builds the URL.

ts
const value = window.Portal.events.scannerManifestUrl();

Returns

Returns a string.

validatePromo() ​

Checks a promo code against a subtotal; resolves with the discount in cents.

ts
const result = await window.Portal.events.validatePromo(occurrenceRef, code, subtotalCents);

Parameters

NameTypeRequiredDescription
occurrenceRefstringYes—
codestringYesThe code to apply.
subtotalCentsnumberYesThe order subtotal in cents.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
discount_centsnumberYes—

Types ​

PortalEventDetail ​

An event with its occurrences and their ticket types (Portal.events.event()).

Extends PortalEventSummary.

NameTypeRequiredDescription
occurrencesobject[]NoThe dates the event runs on.
occurrences[].reference_numstringYesThe occurrence's reference; use it to register.
occurrences[].starts_atstringNo—
occurrences[].ends_atstringNo—
occurrences[].timezonestringNoAn IANA timezone, for example Europe/Paris.
occurrences[].statusstringYesPublication / run status.
occurrences[].availabilitystringYes—
occurrences[].ticket_typesPortalTicketTypePublic[]YesThe tickets on sale for this date.
site_usersPortalSiteUsersBlockNoAbsent on an older server bundle; treat as unconnected.

PortalEventPaymentOptions ​

Options of Portal.events.beginPayment(); most come from the payment block of register().

NameTypeRequiredDescription
directPaymentRefstringYesThe Direct Payment to charge on.
itemRefstringYesThe Direct Payments item the ticket type is mapped to (payment.item_ref from register()).
quantitynumberYesNumber of tickets.
discountItemRefstring | nullNoThe promo discount line (payment.discount_item_ref / payment.discount_cents), when a code applies.
discountCentsnumberNoThe promo discount in cents.
orderRefstringYesThe order being paid.
registrationRefstringYesThe registration being paid.
accessTokenstringNoThe registration's access token from register(); lets a guest attach the invoice.
emailstringYesThe payer's e-mail.
mountSelectorstringNoCSS selector of the element the card form is mounted in.
onSuccess() => voidNoCalled when payment succeeded.
onError(err: Error) => voidNoCalled when payment failed.

PortalEventRegisterPayload ​

What Portal.events.register() sends.

NameTypeRequiredDescription
occurrence_reference_numstringYesThe date being registered for.
ticket_type_reference_numstringYesThe ticket type chosen.
attendee_namestringYesThe attendee's name.
attendee_emailstringYesThe attendee's e-mail (tickets are sent here).
attendee_phonestringNoThe attendee's phone.
quantitynumberNoNumber of tickets; default 1.
idempotency_keystringNoAny unique string; repeating the call with it will not register twice.
hold_reference_numstringNoThe hold made with hold().
promo_codestringNoA promo code (check with validatePromo() first).
form_submission_refstringNoA form submission the event asked the attendee to fill.
tier_reference_numstringNoThe pricing tier chosen, when the ticket type has tiers.

PortalEventRegisterResult ​

The answer to Portal.events.register().

NameTypeRequiredDescription
successbooleanYesTrue when the registration was created.
order_reference_numstringNoThe order created.
registration_reference_numstringNoThe registration created.
statusstringNoThe registration status.
access_tokenstringNoLets a guest read, pay for or cancel the registration later. Keep it.
direct_payment_refstringNoThe Direct Payment to pay on.
requires_paymentbooleanNoTrue when the attendee must pay before the registration is confirmed.
paymentobjectNoWhat the browser needs to build the invoice; present only when a charge is due.
payment.item_refstringYesThe Direct Payments item reference.
payment.quantitynumberYesHow many.
payment.ticket_namestringYes—
payment.discount_item_refstring | nullNo—
payment.discount_centsnumberNo—
errorobjectNoSet when success is false.
error.messagestringYesA message to show the visitor.
error.codestringYesA code.

PortalEventRegistrationRecord ​

A registration as the public / the signed-in attendee sees it.

NameTypeRequiredDescription
reference_numstringYesThe registration's reference.
event_reference_numstringNoThe event registered for.
event_namestring | nullNoThe Dashboard's events provider.
venue_namestring | nullNoThe event's default venue.
occurrence_reference_numstringNoThe date registered for.
starts_atstring | nullNoThe occurrence's own starts_at, eager-loaded server-side — splits upcoming/past.
ticket_type_reference_numstringNoThe ticket type bought.
ticket_type_namestring | nullNoFrom ticket_snapshot.
attendee_namestringNoThe attendee's name.
statusstringNoconfirmed, pending_payment, cancelled...
checked_in_atstring | nullNoSet only by door scanning — present means Attended, absent means unknown, never "no".
amount_centsnumberNoAmount paid in cents.
currencystringNoISO currency code.
registered_atstringNoISO time of registration.
ticket_codestringNoThe code on the ticket (QR / barcode).
access_tokenstringNoPresent only on the single-registration response (registration()), never on myRegistrations().
read_onlybooleanNoSame scoping as access_token above.
read_only_noticestring | nullNoText to show when read_only is true.

PortalEventsFilter ​

Filter of Portal.events.events().

NameTypeRequiredDescription
sitestringNoOnly the events of this website (reference).

PortalEventSummary ​

One event in a public event listing.

NameTypeRequiredDescription
reference_numstringYesThe event's reference.
slugstringNoURL slug.
namestringYesThe event's name.
subtitlestringNoA secondary line under the name.
summarystringNoA one-line summary.
descriptionstringNoThe full description.
categorystringNoThe event category.
timezonestringNoIANA timezone of the times.
starts_atstringNoISO start of the next (or only) occurrence.
ends_atstringNoISO end.
occurrence_reference_numstringNoThe occurrence the summary times refer to.
availabilitystringNoavailable, sold_out...

PortalTicketTypePublic ​

A ticket type as the public sees it.

NameTypeRequiredDescription
reference_numstringYesThe ticket type's reference.
namestringYesThe ticket type's name.
descriptionstringNoWhat the ticket includes.
kindstringYespaid, free, donation...
price_centsnumberYesPrice in cents (0 = free).
currencystringYesISO currency code.
availabilitystringYesavailable, sold_out, not_on_sale...
remainingnumberNoTickets left, when the server reports it.
min_per_ordernumberNoFewest tickets per order.
max_per_ordernumberNoMost tickets per order.