POS Application Integration Flow

This guide outlines the end-to-end integration flow for a Point-of-Sale (POS) application connecting to the POS Hub platform. Understanding this flow is essential for developers building POS integrations.

The primary responsibilities of a POS application are to:

1. Synchronize the catalog (products, modifiers, categories) from the external POS system to POS Hub.
2. Receive orders from POS Hub and inject them into the external POS system.
3. (Optionally) Relay real-time updates from the POS system back to POS Hub.

High-Level Integration Diagram

This diagram illustrates the key interactions between the user, POS Hub, your POS application, and the third-party POS system.

Step 1: Onboarding and Authentication

The first step is for a merchant to install your application in their POS Hub location. This process connects their location with your application and authorizes your app to access their data on the third-party POS system.

1. Installation: A user navigates to the "Apps" section in their POS Hub location and installs your POS 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 third-party POS system'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 third-party POS account and grants your application the necessary permissions. The POS system 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. These credentials will be used for all subsequent API calls to the third-party POS.

Step 2: Catalog Synchronization

Once the application is installed, POS Hub needs to pull the catalog from the external POS system. This is a critical step as it populates POS Hub with the products, prices, and modifiers that will be used by other connected applications, like marketplaces.

Your pull catalog endpoint (/pull-catalog) should handle the following:

1. Fetch Data from POS: Use the stored credentials to make API calls to the third-party POS system to retrieve all relevant catalog data, including:

   • Categories and Subcategories
   • Products/Items
   • Modifier Groups and Modifier Options
   • Taxes
   • Business Hours and Availability

2. Transform Data: Convert the data from the third-party POS's format into the standardized POS Hub CatalogImport schema. This involves mapping fields and ensuring data structures are correct. It is crucial to map the external POS's unique identifier for each entity to the posReference field in the corresponding POS Hub entity. This mapping is essential for future updates and order injection.

3. Return Transformed Data: Respond to the /pull-catalog request with the transformed JSON payload. POS Hub will then process this payload to create or update the catalog for the connected location.

Step 3: Order Injection

When a new order is created in POS Hub (e.g., from a marketplace like Uber Eats), a webhook with objectType: 'ORDER' is sent to your application's webhook endpoint. Your application is responsible for injecting this order into the third-party POS system.

Your webhook handler should follow these steps:

1. Receive the Order: Parse the OrderEntity from the webhook payload.
2. Transform the Order: Convert the POS Hub OrderEntity into the format required by the third-party POS system's order creation endpoint. This includes mapping items, modifiers, customer details, payment information, and fulfillment details using the posReference IDs stored during the catalog sync.
3. Create the Order in the POS: Make an API call to the third-party POS to create the new order.
4. Acknowledge the Webhook: Return a 200 OK response to POS Hub to confirm that the event has been received. Any other response will cause POS Hub to retry the webhook according to the Retry Policy.

Step 4: Real-time Updates (Optional but Recommended)

If your app that integrates with the POS system supports real-time updates (e.g., order status changes, item availability), you can call POS Hub and update those entities in real time, either updating parts of the catalog as they are updated on the POS system, or updating the order status as it changes in the POS system.