Appearance
Synchronization Processes
This guide provides an overview of the synchronization processes within POS Hub, detailing how location, catalog, and menu data are pulled and pushed between installed applications within a POS Hub location. This process is essential for ensuring that all data is accurately represented in the POS Hub platform and that all connected applications have the most up-to-date information.
Location Sync Process
This guide provides an overview of the location synchronization process within POS Hub, detailing how location data is pulled from an external POS system and updated in POS Hub. This process is essential for ensuring that all location details are accurately represented in the POS Hub platform.
Overview
Within POS Hub, the location entity represents a physical store or business location. It contains essential information such as the location name, address, business hours, service availability, and other relevant details. The location entity is important as it serves as a central point for sharing the locations current state with all connected applications, especially marketplace applications that rely on accurate location data to function correctly.
Typically the POS Application installed on the location will have the primary responsibility for managing the location data, ensuring that the POS System itself is in control of business hours, service availability, tax rates, etc in real time, allowing for the merchant to update his tax rates, business hours, special hours, and other relevant information.
Everytime the location is updated, all other installed applications will receive a webhook event notifying them of the change, allowing them to update their operational data accordingly. This ensures that all applications have the most up-to-date information about the location, and can respond accordingly.
Flow Diagram
Between the POS Application and POS Hub, The following data can be updated in real time:
- Location Name: The name of the location.
- Address: The physical address of the location.
- Business Hours: The regular business hours for the location.
- Special Hours: Any special hours for holidays or events.
- Service Availability: Indicates whether the location is currently open for service.
- Tax Rates: The tax rates applicable to the location.
- posReference: A identifier of the pos account/location in the POS System.
see the Api specification for the full list of fields that can be be updated within the PATCH /v1/accounts/{accountId}/locations/{locationId} endpoint.
Catalog Sync Process
This guide provides an overview of the catalog synchronization process within POS Hub, detailing how the catalog data is pulled from an external POS system and updated in POS Hub. This process is essential for ensuring that all products, modifiers, and categories are accurately represented in the POS Hub platform.
Overview
Currently within POS Hub, the catalog sync process is designed to allow POS Hub to pull the catalog from the external POS System. This is typically done when a POS application is installed for the first time or when a user presses the "Sync Catalog" button within the POS Hub Location. The catalog contains all the products, modifiers, and categories that are available for sale at a specific location.
Here's an outline for each of the entities that make up the catalog:
- Categories: Represents the different categories of products available at the location, such as "Beverages", "Food", etc.
- Products: Represents the individual products available for sale, including their prices, descriptions, and any associated images.
- Modifier Groups: Represents groups of modifiers that can be applied to products, such as "Size", "Extras", etc.
- Modifiers: Represents individual modifiers that can be applied to products, such as "Large", "Extra Cheese", etc.
Sync Process
The sync process can be initiated by the POS Hub client when the user clicks the "Sync Catalog" button, or via the API endpoint POST /v1/accounts/{accountId}/locations/{locationId}/connections/{connectionId}/pull, once initiated POS Hub will reach out to the POS Applications {app.catalogSyncUrl} endpoint to to request the full catalog data.
Once the catalog data is received, POS Hub will perform perform validation and transformations of the data, and compare it to the existing catalog data in the database. If there are any changes, POS Hub will update the catalog entities in the database accordingly, this process ensures that the application just needs to return all the data in the correct format, and POS Hub will handle the rest.
Flow Diagram
Menu Sync Process
This guide provides an overview of the menu synchronization process within POS Hub, detailing how menus are created based on the catalog data and how they are updated in POS Hub during the sync process. This process is essential for ensuring that all menu items are accurately represented in the POS Hub platform.
Overview
POS Hub uses the catalog data to create and manage menus for each location. The menu is typically considered as a consumer facing representation of some or all of the catalog, depending on the POS, the catalog may already be structured in a way that is suitable for the menu, or for older POS systems, the catalog may just contain the very basic information about the products, and the menu can be built based on that data.
When creating a menu, POS Hub will only allow items to appear on that menu if they are part of the location's catalog, this ensures that there is a link between the catalog and the menus, allowing for the menus to be updated automatically when the catalog is updated.
Sync Process
The sync process can be initiated by the POS Hub client when the user clicks the "Publish Menu" button, or via the API endpoint POST /v1/accounts/{accountId}/locations/{locationId}/connections/{connectionId}/publish, once initiated POS Hub will reach out to the marketplace applications {app.menuPublishUrl} endpoint to publish the entire menu (syncronously) or to trigger the menu sync process (asynchronously), this will typically be done by the marketplace application, which will then update the menu in POS Hub based on the catalog data.
Once the menu is published successfully, POS Hub will activate real time menu events between that menu and that marketplace application, allowing any changes that occur to the menu within POS Hub to also be sent as an individual event to the marketplace application, allowing them to update their menu in real time.
::: note You should note that not all marketplace applications will support real time menu updates, and some may require the menu to be published again to reflect the changes. :::