Configure access
In Hallify, choose the venue → Settings → Fulfillment → resource settings → Integrations. An administrator with preorders.external.manage creates the credential and selects allowed sales channels and scopes. In Public channel, configure an active channel and its service actor. Copy the key once to your server.
Cabinet route: /venues/:venueId/settings/fulfillment. Grant catalog:read, quotes:write, orders:write and orders:read for the four methods; webhooks:manage is separate. Replace :venueId with the selected venue ID.
First successful workflow
Follow these steps in order. Open each method for its exact body, required headers and response schema.
- GET catalog with an authorized salesChannelId; retain the returned menu identity, graph token, currency, timeZone and deliveryMethods.
- POST quotes using that catalog, selected products, fulfillment mode and available future slot. For DELIVERY, select a returned deliveryMethod and retain one original Idempotency-Key before sending. Retain quoteId, quoteToken, deliveryQuoteId when returned and expiresAt.
- POST orders with the accepted quote, its original delivery selection and deliveryQuoteId when present, matching inputs and a fresh order Idempotency-Key. Keep that order key and exact body for every original retry. Retain orderId, fulfillmentId and revision.
- GET orders/{orderId} or consume configured webhooks to observe the permitted partner projection.
Keep delivery preparation, customer fee and courier dispatch separate
Carrier setup belongs to an authorized administrator: /organizations/:organizationId/delivery-connections for connections and credential versions, then /venues/:venueId/settings/delivery for venue method/fee policy and pickup bindings. Account API paths are /organizations/{organizationId}/delivery-connections and /organizations/{organizationId}/venues/{venueId}/delivery/policy or /delivery/bindings. The partner key grants neither configuration nor staff dispatch authority. A configured LIVE route does not establish provider or regional live qualification.
The authorized catalog returns currency, timeZone and provisional deliveryMethods. DELIVERY can select SELF, UBER_DIRECT or WOLT_DRIVE only when currently available. Omitting deliveryMethod preserves SELF and must remain omitted on an original retry; other service modes must omit it. Wolt Drive requires genuine dropoff latitude/longitude. Do not invent coordinates or treat an address as already geocoded.
POST quotes requires Idempotency-Key for DELIVERY. It durably prepares an EXTERNAL demand under the credential’s current authority, performs bounded carrier work outside the native transaction and issues the native quote only after the original delivery preparation is resolved. Non-DELIVERY does not acquire this conditional requirement. Preserve the exact original key, body, sales channel and quote IDs. PREORDER_DELIVERY_QUOTE_UNKNOWN, PREORDER_DELIVERY_QUOTE_NOT_READY, timeout or a lost response require explicit original replay; do not allocate a replacement key or submit a different quote request to recover.
Read the API error code from SdkError.apiCode and evaluate SdkError.outcome separately. UNKNOWN marks an uncertain request outcome and does not establish the current delivery business state. The SDK performs no automatic retry. Explicit recovery must reuse the saved original Idempotency-Key and exact body, including an originally omitted deliveryMethod.
Retain the native quoteToken and deliveryQuoteId together when creating the order; the customer demand quote is not the later staff dispatchQuoteId. The accepted customer delivery fee stays frozen in the native order currency. Later carrier dispatch cost and expiry belong to a separate staff offer and do not reprice the customer agreement. An uncertain original outcome must be resolved before considering a new quote after expiry or changed inputs.
GET orders/{orderId} exposes fulfillment.deliveryMethod, deliveryFeeAmount and safe deliveryTracking with normalized state, ETA and requiresAttention. Partner deliveryTracking.trackingUrl is always null. Missing tracking is not evidence of a failed or canceled delivery. Staff dispatch, carrier cancel/readback and local abort are outside these four partner operations and the public SDK allowlist. Courier state never proves payment or performs native meal cancellation/refund.
State, retries and recovery
A quote is time-limited and single-use. Once its original outcome is resolved, requote after expiry or material changes. An idempotent retry retains the original request and result; it does not renew expiry or find a replacement delivery. The initial fulfillment is HELD or CONFIRMED according to policy; a successful create does not mean the order was paid or completed. There is no partner list-all, cancel or amend endpoint in this four-operation surface.