Prepare a real publication
An authorized restaurant operator creates a brand or venue draft, publishes its reviewed revision, enables a HOSTED connection, and establishes the required verified host authority. A brand belongs to one organization; an outlet is an actual venue explicitly attached to that connection. A draft, disabled connection or pending host proof is not a public publication.
Keep administrative setup and any provider credentials in the protected Hallify workspace. The public read operations cannot create drafts, publish content, approve a host or enable a connection. This documentation does not create a restaurant, a disposable test venue or deployment credentials.
Cabinet routes: /venues/:venueId/settings/storefront for venue setup, and /organizations/:organizationId/storefront for brand setup. The venue entry uses Hallify's venueSettings access gate; organization brand setup requires organization.manage. Select the actual organization or venue from your authorized Hallify workspace.
Read the published presentation
Use the connection's published publicHandle. The shared hosted page uses /s/{publicHandle}; a selected outlet uses /s/{publicHandle}/venues/{venueId}. Public REST reads use https://api.hallify.co. They require no account cookie or restaurant-wide key and grant no transactional guest authority.
The example uses synthetic data and sends no request from this documentation page. In your own browser application, use credentials: 'omit'. If you generate transport types from the downloaded public OpenAPI, use StorefrontPublicPresentationDto rather than defining another presentation contract.
- Obtain the actual published handle from the authorized operator; do not infer it from an organization or venue identifier.
- Read the handle and check the HTTP status before using the typed document, publication evidence and canonical URL.
- For a brand, read a bounded outlet page with limit from 1 through 50. Follow its returned nextCursor until null; do not invent a cursor or reuse one for another brand.
- Select one returned actual venue and use the selected-venue read. Preserve that venue's currency and time zone throughout any later native guest workflow.
const publicHandle = 'demo-restaurant';
const url = new URL(
`/public/storefronts/${encodeURIComponent(publicHandle)}`,
'https://api.hallify.co'
);
const response = await fetch(url, { credentials: 'omit' });
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const presentation = await response.json();
const representationEtag = response.headers.get('ETag');Follow the selected outlet's native ordering locator
The selected presentation and each listed outlet can contain nullable ordering discovery. A brand without a selected venue has no ordering entry; null is a disabled ordering state, not permission to guess a channel. A nonnull entry supplies exact connectionId, attached PREORDER resourceId, venueId, publicChannelId and publicChannelHandle. The native channel handle is distinct from the storefront presentation handle.
Retain this locator when opening the native catalog and draft flow; do not combine outlets, currencies or tenant context. Draft issuance sends its connectionId as the documented nonsecret x-hallify-connection-id, including on the canonical Hallify Origin. The server resolves and captures the exact current native attachment; do not invent body fields for the other locator values or replace the binding on later private calls.
Catalog allowedOrigins and active native fulfillment policies remain separate authority. An attached channel or successful public Storefront read does not automatically admit your origin or prove that ASAP/scheduled ordering is ready. Read the actual catalog and fulfillmentOptions, then follow the cart, verification, frozen quote and original manage sequence. Projection failure is not a reason to substitute another channel; STOREFRONT_ORDERING_UNAVAILABLE identifies unavailable scoped discovery.
Use the selected outlet’s native reservation locator
The selected presentation and each listed outlet can also contain nullable reservations discovery. A brand without a selected venue has reservations: null. A nonnull entry contains exactly connectionId, attached RESERVATION resourceId, venueId, publicChannelId and publicChannelHandle. The native booking handle differs from the presentation handle; an attached MENU or preorder channel does not create reservation authority.
Follow that exact native channel to configuration, availability, guarantee offer, intent and contact verification. Send its connectionId as the declared nonsecret x-hallify-connection-id during native channel resolution, including on the canonical Origin. Keep the actual browser Origin and original presentation binding; do not invent request-body fields for the other discovery values or combine outlets. Native channel status, allowed origins, capacity and real contact verification remain authoritative.
Null disables booking discovery; it does not authorize a guessed handle, canonical fallback or copied manage grant. STOREFRONT_RESERVATIONS_UNAVAILABLE means scoped reservation discovery cannot be safely projected. A successful Storefront read creates no hold, booking, waitlist entry, guarantee consent or payment access. Continue private management and guarantee checkout only with their own issued native authority.
Hosted booking uses /s/{publicHandle}/venues/{venueId}/book on the shared Hallify host and /venues/{venueId}/book on a verified custom host. WIDGET uses the isolated /widgets/:connectionId frame with an exact verified parent binding and private bootstrap. Native resource/channel discovery remains authoritative.
Revalidate content and resolve verified hosts
A publication retains its immutable identity, source revision, schema version and content hash. Public venue-profile fields remain current. The representation ETag and public, max-age=0, must-revalidate policy require revalidation; do not treat a published document as permanent authorization. A matching If-None-Match on the handle read returns 304 without a body, so reuse only your previously stored representation for that same public scope.
Host discovery resolves a normalized hostname through one active verified hosted binding. It returns the current presentation and, when applicable, its verified canonical destination. A hostname is a discovery locator. It cannot authorize a booking, order, table membership or payment, or substitute an unrelated public handle. Unknown or no longer authorized hosts fail closed.
A custom hosted domain uses / for its presentation and /venues/{venueId} for an attached outlet. The hosted runtime resolves the actual trusted request host; a client-supplied hostname or forwarded-host override is not a tenant selection mechanism. Unpublishing or disabling one hosted connection does not itself authorize changes to the underlying native ordering channel or another connection.
Current implementation boundaries
The presentation document supports reviewed typed content and safe theme tokens, with restaurant content in English, Georgian and Russian. It does not accept arbitrary HTML, CSS or scripts. A published presentation is not an orderable menu, a guest checkout or a shared bill.
Native ordering, reservations and guest payments retain their separate resource and financial authority. Widgets add verified parent/frame presentation proof without merging native grants. The JS/TS SDK exposes only its selected canonical operations. Courier dispatch, npm publication and live browser/domain/provider qualification remain separate.
Customer DNS changes, deployment-provider domain enrollment, certificates and live domain acceptance require their actual operational configuration and qualification. A saved host binding or source implementation is not proof that a provider has activated a production domain.