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.

Your implementation of /menu-publish must:

1. Receive Menu Data: Accept a POST request from POS Hub containing the menu payload, which conforms to the POS Hub MenuExportEntity schema.
2. 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.
3. 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.
4. 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.

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.