The API implements REST based on industry best practices, where possible, such [1]. The API tries to be idempotent with all resources, however with legal regulations and required business processes, we offer some higher level functions, such as deleting customers with GDPR conformity.

We not only allow doing operations on our own, but also abstract or connect third party APIs with their resources, such as ERP Systems, other apps and their backends, transaction signing APIs.

The documentation can be found on every API environment running, e.g. https://staging-api.tillhub.com, https://api.tillhub.com, via the download button at the top of this page.

Examples and how-to articles can be found under: https://developer.tillhub.com

• we provide a multi-tenant, multi-user, delegatable CRUD system, also see staff and sub-users
• we page on large datasets, whereas the load must be handled by consumers
• our storage format is generally SQL compatible, but has NoSQL components, such as embedded documents, that are usually not queryable by themselves out-of-the box (such as lists of addresses of customers, metadata, configurations)
• we offer a highly configurable system through a large number of toggles and other data to drive client behaviour and appearance, see configuration
• our system is whitelabelable
• file uploads feature based on "multipart form" data and usually comes as dedicated POST/PUT endpoint(s) along with traditional set of CRUD endpoints. The following flow applies:
  • obtain an entity unique ID via creation or reading endpoint
  • use such ID to upload associated file(s) via file(s) upload endpoint
  • get uploaded file URL from response

The authentication flow is split in into several flows, to cater for multiple headless, headfull and elevation of rights scenarios:

• Users
  • client account as admin (with expiration)
  • sub-user with specific rights (with expiration)
  • support users of Tillhub (with expiration)
• Devices
  • such as the POS systems themselves (without expiration)
  • or, based on your choosing and client scenarios (adjustable expiration)
• Service Accounts

Devices are considered Highly Trusted Clients and are required only to be passed a short password (like a short number sequence) that comes directly from the resource owner. This process will be described in greater detail in the device section. Unlike devices, users need to register through a headfull auth flow to validate themselves (e.g. email). More on that in User Authententication.

Flow Overviews

API Key Auth

Login

The login is (again) independent on the actual client and happens through the API. Users must specify their email and password and get returned a hard token, that does not expire, but can be blacklisted by the API and the user themselves. Blacklisting requires a new login procedure.

{
  "status": 200,
  "msg": "Authentication was good.",
  "request": {
    "host": "api.tillhub.com",
    "id": "034bf4f9-4107-4bc0-bdab-882cae7d3e08"
  },
  "user": {
    "id": "some-user-id",
    "name": "some-user-name",
    "legacy_id": "some-user-id-for-accounts-pre2018"
  },
  "token": "some-jwtoken",
  "token_type": "Bearer",
  "sub_user": {
    "id": "dd77cd17-b0b6-408a-87c2-09dc88ad5145",
    "created_at": "2020-03-25T10:30:58.052Z",
    "updated_at": "2020-03-25T10:30:58.176Z",
    "metadata": null,
    "groups": null,
    "scopes": null,
    "attributes": null,
    "user": {
      "id": null,
      "email": null
    },
    "description": "API User",
    "active": true,
    "role": "serviceaccount",
    "parents": null,
    "children": null,
    "blocked": false,
    "configuration_id": "6bcf2faa-b618-4b00-b12a-2a8bba9a9b31",
    "user_id": null,
    "deleted": false,
    "api_key": "81f7f582-b3e9-4912-b45a-fdf23bdf3fc5",
    "key": null,
    "username": null,
    "name": "Test",
    "locations": null
  },
  "expires_at": "2020-05-28T07:28:44.000Z"
}

Subeseuquent API calls need to set an Authorization header in every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c...

Device Authentication

device authentication is currently restricted via email/password auth flow

A client generally has access to it's resources via the token it retrieves from the authentication flow. Clients can ask for delegated rights or being assigned such in order to access other account's data.

An example would the voucher API, where a user account 8dd82ae3-d8ba-4c5f-baff-b60509ebb7bf can access the URI api/v0/vouchers/bb0aa785-e4bb-496f-bad6-f7e815a78f35?code=1234 (make a voucher lookup), but not api/v0/vouchers/bb0aa785-e4bb-496f-bad6-f7e815a78f35 (retrieve all vouchers).

In general the authorization is decoded into the JWT token retrieved by the authentication and can be inspected through tools like jwt.io.

The products model is at the heart of the application. Understanding and utlising the model is key.

Prior-Art

• the variants model of Amazon Amazon has similarities and good illustrations, which can serve as primer

Model

The product system can be described as product-child model. The model can handle higher level product-product relations, relations to child products, such as deposits, variants of products (trousers with different sizes and colours) and vouchers.

All products also drive financial data processes, in order to comply with regulations. Revenues for products will be booked to accounts, have multiple taxes (e.g. lowered tax rates when selling a product for to-go, or different local taxes).

Prices of products can be based on scaling (such as 20x cans of soda will be bundled with a lower price but with a crate), depending on branch, region time of day or season.

Types of Products

The types will drive speicific behaviours in Tillhub Clients, e.g. demonstrate a view with the options to click through, an edit view of all product_variants under a variant product or automatically add items to carts.

API implementors and external clients should retrieve those product from their low to high specialisation. E.g. to start a sale of a variant product it is likely more important to present the cashier with the options combination and load the leafs of the options later or even just the target product. This selective retrieval can be driven through query parameters of the /products endpoints.

Below we will illustrate the type specific object extensions and later all the common properties.

Layout of Type Specific Properties

// on the parent at query time
{
  "id": "d3c685bd-ef6e-4891-b474-7b06857a547b", // unique resource ID in the database (not your custom ID / SKU) of the parent product
  "stockable": false,
  // ...other properties
  "options": { // transient property at query time, for easier discovery
  "size": ["22", "23", "24"],
  "color": ["red", "orange"]
  }
}

// on the parent at query time
{
  "id": "6a9de45b-5a75-4b6b-90b3-9e33fd96be09", // unique resource ID in the database (not your custom ID / SKU) of the child product
  "product": "d3c685bd-ef6e-4891-b474-7b06857a547b", // the parent product
  "stockable": true,
  // ...other properties
  "attributes": { // property set upon product creation
    "Size": "S",
    "Colour": "blue"
  }
}

{
  "id": "8a7f7ba8-2240-4bda-ab10-3836c4d609d5",
  // other properties
}

{
  "id": "8a7f7ba8-2240-4bda-ab10-3836c4d609d5",
  // other properties
  "stockable": false // ... will likely denote a voucher that will be generated, e.g. printed. If true, there are e.g. physical gift cards that will be depleted
}

{
  "id": "c33ace04-4c2c-496b-97e0-d720c62d95e5",
  // other properties
  "stockable": true,
  "linked_to": [
    {
      // the full product that links to this product
      "id": "8e15e674-148e-4bd2-a216-0536e5c6fd7e"
    },
    {
      // the embedded versions
      "name": "generic embedded deposit",
      "account": "d20191ce-9f62-4e71-a4ff-e6ef3ab2fc73",
      // other properties
      "prices"; {
        "default": [
          {
            "amount": {
              "gross":  0.3,
              "net": null
            },
            "currency": "EUR"
          }
        ]
      }
    }
  ]
}

{
  "id": "8e15e674-148e-4bd2-a216-0536e5c6fd7e",
  // other properties
  "stockable": false,
  "prices"; {
    "default": [
      {
        "amount": {
          "gross":  0.3,
          "net": null
        },
        "currency": "EUR"
      }
    ]
  }
}

Prices

Prices are naturally a very important class of properties. We support many kinds of prices and will add support for many more in the future. The type of prices usually drive temporally, spacially or numerically specific behaviour that often is at the heart of the our your business logic and proesses. Those are

All prices come as amount / currency pair, whereas the currency is an ISO 4217 formatted 3 letter string and the amount an object of a net and gross value. net and gross have an either-or-relationship. This is because some clients prefer deriving the selling_price from net others form gross. This becomes relevant on customer facing prices that need to be gross stable, but have can have differnt taxes applied to them e.g. a coffee for 1.50 for "to-go" can in some countries be taxed with lower tax rates and clerks are required to ask this during the sales process.

{
  "id": "8e15e674-148e-4bd2-a216-0536e5c6fd7e",
  // other properties
  "prices": {
    "default_prices": [
      {
        "amount": {
          "net": 1.49,
          "gross": 1.77
        },
        "currency": "EUR"
      }
    ],
    "scaled_prices": [
      {
        "qty": 1,
        "prices": [
          {
            "amount": {
              "net": 1.49,
              "gross": 1.77
            },
            "currency": "EUR"
          }
        ]
      },
      {
        "qty": 30,
        "prices": [
          {
            "amount": {
              "net": 1.49,
              "gross": 1.77
            },
            "currency": "EUR"
          }
        ]
      }
    ],
    "branch_prices": [
      {
        "branch": "e43f2a88-bae9-494f-979a-31438ecfa342",
        "prices": [
          {
            "amount": {
              "net": 1.49,
              "gross": 1.77
            },
            "currency": "EUR"
          }
        ]
      },
      {
        "branch": "1ae7a14d-1ecb-4261-8c80-b80161efb79e",
        "prices": [
          {
            "amount": {
              "net": 1.49,
              "gross": 1.77
            },
            "currency": "GBP"
          }
        ]
      }
    ]
  }
}

Properties

Below we will list common properties, that drive special behaviour, require some knowledge or are required

metadata

The metdata is a field for arbitrary data anyone can use. for custom data as JSON object. Though we do not have any household guarentees for preserving information here, it's generally safe to store custom information here (that will not be used by Tillhub clients). We often use this during bulk importants of possibly incompatible data we need to keep reference to temporarily.

custom_id

The custom_id typically refers to a generic product number, that does not follow any format, standardization or business logic. This custom field that is queryable in client application.

attributes

The attributes field drives the options logic in variant_products, to that extent that the key value combinations will be shown in a option selection. When configured in the configurations API, also regular products can display attributes for informational purposes. Note that keys are UTF-8 and will be shown in the UI.

{
  "attributes": {
    "Size": "S",
    "Colour": "blue"
  }
}

sku

Business that have a complete stock system and ensure uniqueness of SKUs (Stock keeping unit), can store such in the sku field. This field will be relevant during translation of external systems and in our stock management if so desired. Many businesses will have overlap to custom_ids here though.

gtin

Bsiness that are running standardised Global Trade Item Numbers can reference such in the gtin field.

stock_minimum

For doing stock and order management we have a number of ways predicting or informing on low stock. The numeric, not null, stock minimum is the sure circuit breaker, to receive an email notification (if desired) or the item as suggestion once a corresponding stock falls under this threshold.

barcodes

Barcodes drive the local discovery of data. They come in many formats.

serial_number_input_required

Defines whether a product requires to enter a serial number during the sale so cashier must enter and store this information in the cart item.

Products API

For the products API documentation, jump to

The Tillhub locations model allows to physically or virtually separate business entities of an account.

The most simple and even required business entity is the branch. A branch for example can have stock, has a separated financial scheme, is a physical location that cannot exist twice and has registers.

Below is a list of all entity types and their specific behaviours

Validation of Incoming Data

We are validating incoming data rather strictly as a data quality mechanism. For example on any call, may it be POST, PUT, PATCH we throwing validation errors, when one sends fields like id, created_at or updated_at, because when it is send we assume the client wants to write those fields, which is not allowed.

NOTE: we currently allow sending some properties for convenience of some downstream clients, but may remove support any time without notice

Most validations are based on JSON Schema, which we will publish also in the future.

Sending Incremental Change

The most secure way to send updates is using the PATCH routes which may explicitly allow the content type application/json-patch+json for JSON Patch.

An example from http://jsonpatch.com/ would be

The Original Document

{
  "baz": "qux",
  "foo": "bar"
}

The Patch

[
  { "op": "replace", "path": "/baz", "value": "boo" },
  { "op": "add", "path": "/hello", "value": ["world"] },
  { "op": "remove", "path": "/foo"}
]

The Result

{
  "baz": "boo",
  "hello": ["world"]
}

For some of the APIs we offer configurable integrations into third party systems, such as webhooks, message queues or direct implementations.

E.g. the customers, transactions and vouchers APIs it is possible to get realtime updates via a message queue based on Google PubSub. Client libraries are available for a number of languages

Client accounts are required to purchase support of this feature (if applies), configure it and authenticating a matching service account.

While the client account is being created the API will also factor google service accounts and create the necessary topics and subscriptions.

The returned google credentials can be use as credentials object for the PubSub SDK Classes

const topic = new PubSub({
  // credentials come as JSON and have the necessary information, like the google project, already included
  credentials: CREDENTIALS
}).topic('api.v1.transactions')

const subscription = topic.subscription('api.v1.transactions', {
  flowControl: {
    maxMessages: 5
  }
})

subscription.on('error', (err) => console.error(err))
subscription.on('message', (msg) => console.log(msg))

Below we will describe common opeation with example and explantion of business logic

Scenario: an external application wants to create a cart that can be consumed by Tillhub client applications and to a valid sale while using local payment methods.

Actions:

1. authenticate through any auth mechanism from the /users/login-API
   Note: Mensure or assume you are sufficiently authorised to do all following actions

2. query a product from the /product-API
   Note: ensure that the product is on the last leaf of the product-child model, namely that it can be sold. It must have a price and financial information, such as accounts and taxes.

3. Construct a cart via the /carts-API
   Note: comply to the required fields. This contract then will then make sure to fill all other necessary parameters implicitly.

1.1. Getting a Authenication Token

The simplest form of authentication is via the accounts password and email. All other flows, such as delegated account, a service account or an API token, will yield the same the same response, but with differnt tokens. Those token might then have fewer rights and/or a shorter/longer lifetime.

curl -X POST \
  https://api.tillhub.com/api/v0/users/login \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]",
  "password": "[PASSWORD OMITTED]"
}'

Response:

{
    "status": 200,
    "msg": "Authentication was good.",
    "request": {
        "host": "api.tillhub.com",
        "id": "0694a625-1892-4782-9a1f-7faaa98da19c"
    },
    "user": {
        "id": "b8ca3bbd-df45-4228-8b97-e5d8e986f2f3",
        "name": "demo-demo",
        "legacy_id": "EDDB2494C2434EFE948655D6BA27E69A"
    },
    "valid_password": true,
    "token": "[TOKEN OMITTED]",
    "token_type": "Bearer",
    "expires_at": "2018-06-22T14:52:38.000Z"
}

Please take note here of the user object. The IDs here are critical for making subsequent calls, as we will describe below. It is imperative to check for the legacy_id field though, since some of our accounts are having assigned while others have not been. If there legacy ID is present always use it in subsequent calls. This has historic reasons and is important for our tenancy model.

1.2. Getting a Product

Any further call will be made on the client accounts resources. That is either the id or legacy ID as described in the previous paragraph. The ID must constructed into the request's URL as we can see in the following call to the products API:

A product can be searched by a number of parameters or you can list them all and and have your custom selection logic.

Below is an example to search a product by barcode. Note, that this likely implicilty returns a product that is sellable, because higher level products, like a variant usually do not have barcodes since they are not stockable.

curl -X GET \
  'https://api.tillhub.com/api/v1/products/EDDB2494C2434EFE948655D6BA27E69A?barcode=55000182' \
  -H 'Cache-Control: no-cache' \
  -H 'Authorization: Bearer [TOKEN OMITTED]'

Note the use of the client account ID. Also take note, that depending on your use case or application maturity, you can use differnt API versions. When starting development greenfield, please always use the highest version number.

Response:

{
    "status": 200,
    "msg": "Queried products successfully.",
    "request": {
        "host": "api.tillhub.com",
        "id": "732a5ebb-8864-4ba2-8818-1189aa737db1",
        "cursor": {
            "first": {
                "id": "f5f2b11e-d7e7-47f0-ba26-c4322b2f4552",
                "updated_at": "2018-03-02T19:08:22.000Z",
                "page": 0,
                "cursor_field": "updated_at"
            },
            "page": 0
        }
    },
    "cursor": {
        "first": "https://api.tillhub.com/api/v0/products/EDDB2494C2434EFE948655D6BA27E69A?first=2018-03-02T19%3A08%3A22.000Z&page=0&size=1000&cursor_field=updated_at",
        "self": "https://api.tillhub.com/api/v0/products/EDDB2494C2434EFE948655D6BA27E69A?first=2018-03-02T19%3A08%3A22.000Z&page=0&size=1000&cursor_field=updated_at"
    },
    "count": 1,
    "results": [
        {
            "id": "f5f2b11e-d7e7-47f0-ba26-c4322b2f4552",
            "metadata": 44,
            "created_at": {
                "iso": "2018-03-02T19:08:22.000Z",
                "unix": 1520017702000
            },
            "updated_at": {
                "iso": "2018-03-02T19:08:22.000Z",
                "unix": 1520017702000
            },
            "product": null,
            "product_group": "0abcdc67-f619-4db9-a2c6-7828580d399d",
            "name": "Ice Cream",
            "description": null,
            "type": "product",
            "summary": null,
            "account": "3abcdc67-f619-4db9-a2c6-7828580d399d",
            "tax": "2abcdc67-f619-4db9-a2c6-7828580d399d",
            "category": null,
            "images": null,
            "condition": null,
            "manufacturer": null,
            "produced_at": null,
            "purchased_at": null,
            "released_at": null,
            "similar_to": null,
            "related_to": null,
            "audiences": null,
            "keywords": null,
            "categories": null,
            "custom_ids": null,
            "active": true,
            "deleted": false,
            "insert_id": 16,
            "brand": null,
            "prices": {
              "default_prices": [
                {
                  "amount": {
                    "net": 1.59,
                    "gross": 1.49
                  },
                  "currency": "EUR"
                }
              ],
              "scaled_prices": [
                {
                  "qty": 1,
                  "prices": [
                    {
                      "amount": {
                        "net": 1.59,
                        "gross": 1.49
                      },
                      "currency": "EUR"
                    }
                  ]
                },
                {
                  "qty": 30,
                  "prices": [
                    {
                      "amount": {
                        "net": 1.59,
                        "gross": 1.49
                      },
                      "currency": "EUR"
                    }
                  ]
                }
              ],
              "branch_prices": [
                {
                  "branch": "e43f2a88-bae9-494f-979a-31438ecfa342",
                  "prices": [
                    {
                      "amount": {
                        "net": 1.59,
                        "gross": 1.49
                      },
                      "currency": "EUR"
                    }
                  ]
                },
                {
                  "branch": "1ae7a14d-1ecb-4261-8c80-b80161efb79e",
                  "prices": [
                    {
                      "amount": {
                        "net": 1.59,
                        "gross": 1.49
                      },
                      "currency": "GBP"
                    }
                  ]
                }
              ]
            },
            "stock_minimum": null,
            "stockable": true,
            "attributes": null,
            "custom_id": null,
            "linked_to": null,
            "barcode": "55000182"
        }
    ]
}

Alternatively, you can search for products by their textual information and their custom id (which is generic "product number"). This will match all strings on all of those fields combined, that start with, end with or contain the input of q.

curl -X GET \
  'https://api.tillhub.com/api/v1/products/EDDB2494C2434EFE948655D6BA27E69A/search?q=ice%20cream' \
  -H 'Cache-Control: no-cache' \
  -H 'Authorization: Bearer [TOKEN OMITTED]'

1.3. Constructing a Cart

curl -X POST \
  https://api.tillhub.com/api/v0/carts/EDDB2494C2434EFE948655D6BA27E69A \
  -H 'Authorization: Bearer [TOKEN OMITTED]' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "SOME ID of your choosing",
    "cartitems": [
      {
        "product": "f5f2b11e-d7e7-47f0-ba26-c4322b2f4552",
        "qty": 1,
        "discounts": [
          {
            "amount": 25,
            "group": "cart",
            "name": "Erstkundenrabatt",
            "type": "percentage"
          }
        ]
      }
    ]
  }'

Note: the cart item takes optional fields, that can be set manually also if prices are not available. That is the single selling_price (includes discounts) of the item, the quantity of all selling_prices and the origial_price of the product.

Business Partner API