Partners Documentation

How Apps Work

Apps add features to the products made by The Despatch Company (TDC). A developer registers the app in the TDC Partner Portal, merchants install it from inside the product, and the app's own backend does the work.

The Partner Portal is the App Store and the sign-in broker for apps. It does not host your code or pass product data through. Its job is to register your app, handle the install and hand your backend an access token.

When you create an app you choose which products it supports: Fulfilment, Helm, Helm 3.x (the previous-generation warehouse system) or Voila. One app can support more than one product.

Example: a merchant installs an accounting app from inside Helm and authorises it. The Partner Portal sends them to the app's redirect URL with a one-time code, the app's backend swaps that code for an access token and stores it, and the app is now linked to that merchant until they uninstall it.

Before You Start

• A Partner Portal account: register at partners.thedespatchcompany.com. You can log in with Microsoft or with your email address.

• An HTTPS backend: your app needs an App URL and an OAuth Redirect URL. The redirect URL must use HTTPS and match exactly what you register.

• Secure server-side storage: for your Client Secret and each merchant's access token.

Creating Your App

1. Log in to the Partner Portal, or click Register to create an account.

2. Open Apps and click Create App. If you have no apps yet, you can also click Create your first app on the dashboard.

3. Fill in the form:

4. Click Create App. The app is saved as a draft, and nothing goes live until you submit it for review.

5. Open the app's Settings page. Under OAuth Credentials you will find your Client ID and Client Secret.

How a Merchant Installs Your App

Merchants install your app from inside the product. You do not build the install link yourself: the product does, and sends the merchant to the Partner Portal's install screen.

1. The merchant confirms the install.

2. The Partner Portal sends them to your OAuth Redirect URL with these query parameters added:

3. Your backend verifies the hmac, then exchanges the code for an access token (see the next section).

Exchanging the Code for an Access Token

From your backend, send the code to the Partner Portal. In the examples below, {appstore_base} is the Partner Portal's address, the same host where you manage your apps. Both headers are required and the body must be JSON.

curl -X POST {appstore_base}/oauth/code \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "code": "the-code-from-the-redirect"
  }'

A successful request returns HTTP 200:

{
  "success": true,
  "message": "Access token generated successfully.",
  "access_token": "example-access-token-value"
}

If the code has expired or has already been used, you get HTTP 400 with "success": false and a message explaining why.

Store the access token against the merchant. It does not expire on a timer and stays valid until the app is uninstalled. The code is now used up and cannot be reused.

Uninstalls & Data Deletion

When a merchant uninstalls your app, revoke their token:

curl -X POST {appstore_base}/oauth/delete-token \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "access_token": "the-access-token-to-revoke"
  }'

A successful call returns {"success": true, ...}.

Publishing Your App

Every app has one of three visibility states:

To submit your app for review:

1. Open the app and switch to the Publish tab.

2. Work through the steps: logo, app details (name, support email and a short description), store listing (headline and highlights), media (screenshots and an optional demo video), the data-deletion webhook (required for public apps) and a final declaration.

3. Submit. The app moves to pending while the TDC team reviews it, usually within two working days, and you are told the outcome by email.

If Your App Is Rejected

Rejected apps stay editable. The reviewer's reason appears at the top of the Publish tab, starting with a category in square brackets: Incomplete metadata, Brand guidelines, Functional issues, Security concerns or Other. Fix the issues in the notes and submit again from the same tab. Your earlier work is kept.

FAQ

Questions about building an app? Contact Support and the team will help.