Marketplace Application Integration Flow

This guide outlines the end-to-end integration flow for a Marketplace application connecting to the POS Hub platform. This flow is essential for developers building integrations for services like Uber Eats, DoorDash, or other food delivery platforms.

The primary responsibilities of a Marketplace application are to:

1. Receive and process menu data from POS Hub to be published on the external marketplace.
2. Send new orders from the marketplace to POS Hub for injection into the merchant's POS system.
3. Receive real-time order status updates (e.g., accepted, cancelled) from POS Hub and reflect them on the marketplace.

High-Level Integration Diagram

This diagram illustrates the key interactions between the user, POS Hub, your Marketplace application, and the external Marketplace service.

Step 1: Onboarding and Authentication

The first step is for a merchant to install your application in their POS Hub location. This connects their location with your application and authorizes your app to manage their store on the external marketplace.

1. Installation: A user navigates to the "Apps" section in their POS Hub location and installs your Marketplace application.
2. Authorization Redirect: POS Hub redirects the user to your application's redirect uri endpoint. Your application should then redirect the user to the external marketplace's OAuth2 authorization page or provide another means of onboarding (such as a manual API key entry).
3. User Consent & Token Exchange: The user logs into their marketplace account and grants your application the necessary permissions. The marketplace then redirects back to your application with an authorization code. Your application exchanges this code for an access token and a refresh token.
4. Store Credentials: Your application must securely store the access token, refresh token, and any other necessary identifiers (like the external store ID) associated with the POS Hub location.

Step 2: Menu Publishing

Once connected, merchants will create and manage their menus within POS Hub. When a merchant decides to publish a menu to your marketplace, POS Hub sends the standardized menu data to your application.

This process is handled by your application's /menu-publish endpoint, which is defined in your application's configuration.

Delivery modes

POS Hub supports two delivery modes for the menu payload.

Presigned URL (default, recommended)

This is the default delivery mode for all newly created applications. Instead of sending the full menu payload inline, POS Hub uploads the payload to S3 and sends your endpoint a small JSON body containing a short-lived presigned URL.

Request body shape:

{
  "sourceUrl": "https://<bucket>.s3.<region>.amazonaws.com/menu-publish/<connectionId>/<menuId>.json?X-Amz-Signature=..."
}

Your endpoint should:

1. Detect the sourceUrl field on the request body.
2. Issue an authenticated-by-signature GET on sourceUrl to download the JSON payload. The downloaded body conforms to the POS Hub MenuExportEntity schema (plus the location field).
3. Continue with the transform / publish / acknowledge steps below.

Notes:

• The presigned URL is valid for 15 minutes. Fetch it as part of handling the request — do not queue it for later.
• Use a sensible HTTP timeout (~30s) and try/catch the fetch; if the URL has expired or the download fails, return a 4xx so POS Hub can surface a clear error.

Inline payload (legacy, deprecated)

Deprecated

The inline delivery mode is retained only for backward compatibility with existing applications. New applications should not rely on it, and existing applications should migrate to the presigned URL mode.

In this mode the full menu payload is POSTed directly to your endpoint and conforms to the POS Hub MenuExportEntity schema (with an additional location field).

Verifying the request signature

Every menu publish request is signed by POS Hub with your application's secret using the same scheme as application webhooks. Each request includes an X-Webhook-Signature header containing a SHA-1 HMAC of the raw request body (hex-encoded), using your application secret.

Verify the signature before processing the body (and before fetching sourceUrl if you're on the presigned URL mode). Compute the HMAC over the same raw bytes you received — not over a re-serialized object:

const crypto = require('crypto')

const expected = crypto
  .createHmac('sha1', applicationSecret)
  .update(rawRequestBody)
  .digest('hex')

const isValid = expected === request.headers['x-webhook-signature']

In presigned URL mode, the signature is computed over the small { "sourceUrl": "…" } envelope you receive — not over the underlying menu payload in S3. The S3 presigned URL itself authenticates the menu download.

Implementation checklist

Regardless of which delivery mode your application uses, your /menu-publish handler must:

1. Verify the Signature: Compute the HMAC-SHA1 of the raw request body using your application secret and compare it to the X-Webhook-Signature header. Reject the request with 401 Unauthorized if it doesn't match.
2. Receive Menu Data: Accept a POST request from POS Hub. If the body contains a sourceUrl, fetch and parse the JSON at that URL; otherwise treat the request body itself as the menu payload.
3. Transform Data: Convert the standardized POS Hub menu data into the format required by the external marketplace's API. This includes mapping categories, items, modifier groups, and pricing.
4. Publish to Marketplace: Use the stored credentials to make API calls to the external marketplace to create or update the menu for the merchant's store.
5. Acknowledge the Request: Return a 200 OK response to POS Hub to confirm that the menu publish request has been received and is being processed.

Step 3: Order Creation

When a customer places an order on the external marketplace, the marketplace will notify your application, typically via a webhook.

Your application's webhook handler for new orders should:

1. Receive the Order from Marketplace: Listen for incoming new order events from the external marketplace.
2. Transform the Order: Convert the marketplace's order data into the POS Hub OrderCreateEntity format.
3. Create the Order in POS Hub: Make a POST request to the POS Hub /v1/accounts/{accountId}/locations/{locationId}/orders endpoint to create the order. This will trigger the order injection flow to the merchant's POS system.
4. Store Mapping (Optional): You may want to store a mapping between the external marketplace's order ID and the POS Hub order ID for future reference.

For the exact shape of items, modifiers, and nested modifiers in the request body, see Order Injection Flow.

Step 4: Real-time Order Status Updates

After an order is sent to POS Hub and injected into the merchant's POS, the POS system will update the order's status (e.g., ACCEPTED, READY, CANCELLED). POS Hub relays these status changes back to your Marketplace application via webhooks.

Your /webhook handler for ORDER events should:

1. Receive Status Update: Parse the OrderWebhookEvent from the POS Hub webhook.
2. Identify the Order: Use the partnerId (which corresponds to the external marketplace's order ID) or your stored mapping to identify the order on the external marketplace.
3. Update Marketplace: Make an API call to the external marketplace to update the order's status, keeping the end customer informed.
4. Acknowledge the Webhook: Return a 200 OK response to POS Hub.