Appearance

Application Onboarding ​

There are two ways to bring an application live on POS Hub. Pick the one that matches how much you want to automate, then follow the matching section below.

Application FlowReseller Flow
Difficulty
Easy
Medium
Account / location creationManual, in the POS Hub UIAutomated, via API
Connecting apps to a locationManual (click the app in POS Hub)API-driven (credentials still entered by the client)
Catalog sync & menu publishManual, from the POS Hub UIManual or via API
Best forGetting started quicklyAutomating the whole onboarding lifecycle

In short

  • Application Flow - use this when you will create the account, location, and do the work (syncing catalog, publishing menu) manually in POS Hub. It is the easiest way to integrate.
  • Reseller Flow - use this when you want to automate everything (account creation, location creation, connecting applications) through the API.

Which flow should I use? ​

Environments

Wherever you see a base URL below, it depends on your environment (Environments):

  • SIT: https://api-sit-dr.stage.tryposhub.com
  • Production: https://api.tryposhub.com

Interactive API docs (Swagger) live at {baseUrl}/docs/index.html.

Application Flow ​

The Application Flow is the easiest way to integrate with POS Hub.

You start by creating an application in POS Hub - it can be either a POS or a Marketplace application. From there, account, location, and connection setup are all done manually in the POS Hub UI.

Step 1 - Create your application ​

Create an application in POS Hub (POS or Marketplace). See Application Anatomy for the components (client ID/secret, redirect URLs, webhook endpoints) and Create Application.

By default, your application gives us a redirect endpoint. When your application is clicked inside POS Hub, we redirect the user to that endpoint.

Step 2 - Generate an access token ​

Generate a token using your application credentials.

Staging (SIT)

bash
curl --location 'https://api-sit-dr.stage.tryposhub.com/oauth2/token' \
--data '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_APPLICATION_ID",
    "client_secret": "YOUR_APPLICATION_SECRET",
    "scope": "YOUR_APPLICATION_SCOPE"
}'

Production

bash
curl --location 'https://api.tryposhub.com/oauth2/token' \
--data '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_APPLICATION_ID",
    "client_secret": "YOUR_APPLICATION_SECRET",
    "scope": "YOUR_APPLICATION_SCOPE"
}'

Step 3 - Set up the account, location & connection (manual) ​

In the Application Flow you create the account, location, and connect your application (POS or Marketplace) to a location manually in POS Hub. Step-by-step instructions:

If you are a POS application ​

You need to share two endpoints with us:

  1. Catalog pull endpoint - we call this to trigger a catalog sync from POS Hub. You return data in the CatalogImportEntity shape:
  2. Webhook endpoint - when an order is placed from any marketplace, we hit this endpoint to notify you (OrderWebhookEvent):

To update an order (status changes such as accepted, ready, completed), call the order PATCH endpoint:

Bringing your menu online (manual): As a POS application, trigger a catalog sync (click the Sync Catalog button for your application) from POS Hub. Your menu data then appears in the Catalog section. Next, create a new menu in POS Hub, connect any marketplace application available in POS Hub, and publish the menu. All of these steps are done manually.

Marking items out of stock: When an item goes out of stock at your POS, call the product PATCH endpoint:

If you don't have our POS Hub productId, look it up using your own POS reference:

bash
# Returns the product (including its POS Hub id) for your posReference
curl --location 'https://api-sit-dr.stage.tryposhub.com/v1/accounts/{accountId}/locations/{locationId}/catalog/products?posReference=YOUR_ID'

Then PATCH the product using the returned id.

Out-of-stock = show_online: false

To mark an item as out of stock, set show_online to false on the product. Do not delete the product.

If you are a Marketplace application ​

You need to share two endpoints with us:

  1. Menu publication URL - once a POS application is connected, the catalog is synced, and a menu is created, the merchant publishes the menu to your marketplace. We trigger this endpoint when the menu is published from POS Hub. You receive data in the MenuExportEntity shape:
  2. Webhook endpoint - we hit this whenever menu or order updates happen. Order events use OrderWebhookEvent:

Application Flow at a glance ​

That's it for the Application Flow.

Reseller Flow ​

With the Reseller Flow you can do all of the account creation, location creation, and connecting applications through reseller endpoints. You don't need to do anything manually in POS Hub - everything is automated.

Follow this guide to create the reseller token, account, location, and connect an application:

You can also read the internal reference: Authorization Using API.

Same endpoints, more automation

You still need to share the same endpoints described in the Application Flow (catalog pull, webhook, menu publication). The difference: in the Application Flow you sync the catalog and publish the menu manually from POS Hub, whereas here you can do it via API.

If you are a POS application, you typically also want to connect to a marketplace application. In the Application Flow you click the app manually in POS Hub; in this flow you use the connection endpoints. Note that the actual integration still requires the client to enter their credentials - this applies to both POS and marketplace connections.

Automating the flow via API ​

  1. List applications available for a location
  2. List connected applications for a location
  3. Sync the catalog from POS - identify the POS connection from the application/connection lists, then trigger a pull:
  4. Create the menu
  5. Publish the menu to a marketplace - identify the marketplace connection, then publish:

Reseller Flow at a glance ​

Next steps ​

Keep going

We provide the technology - you drive the innovation.

POS Hub