DocumentationOrders

Orders

Introduction

This page documents the API for delivering orders directly to the POS. Restaurant staff work primarily inside the POS, so accepting orders and managing their lifecycle should be as simple as confirming them. The menu should stay synchronized automatically; staff should not have to maintain it manually.

To enable ordering, complete the following steps in order:

  1. Contact techsupport@qerko.com to enable the ordering feature in Restaurant Admin.
  2. Synchronize the menu.
  3. Implement order handling and lifecycle management.

Qerko must always have the latest menu so customers can order with confidence. Qerko displays the menu in the mobile app and caches it to reduce load on the POS.

Both sides can initiate synchronization:

The POS should synchronize whenever the menu changes significantly-for example when an item becomes unavailable, a new item is added, or an existing item is removed.

Qerko refreshes the menu when certain errors occur in orderStart() or orderPrepare(), when the cache expires, or when a customer requests the menu after the current time-to-live elapses. The TTL may change over time as we optimize the frequency of POS requests.

Synchronization flows only from the POS to Qerko; no additional actions are required.

Orders and their lifecycle

Orders are submitted by customers who select items from the menu and confirm them. The customer may be at the table and order another drink (delivery toBill/toTable), schedule a pickup (delivery byCustomer), or request delivery (delivery byOperator).

Delivery byOperator is not yet publicly available. Contact Qerko if you plan to use it.

Orders follow these steps:

  1. Qerko calls orderPrepare(). The POS can adjust the order or offer discounts or upsells. If the customer accepts a change or modifies the order, Qerko calls orderPrepare() again.
  2. Qerko calls orderStart() to submit the order to the POS. From this point, the order content is fixed. The POS either accepts or rejects the order and returns the next status.
  3. If applicable, Qerko calls orderMarkAsPaid() to confirm that payment was captured in advance. Standard Qerko payment processing is passed into this method.
  4. Qerko calls orderClose() when the order lifecycle ends.

The methods orderPrepare(), orderMarkAsPaid(), and orderClose() mirror the payment methods paymentStart, paymentProcessed, and paymentClose.

Each order status reflects the current phase:

  • OrderWaiting - The order awaits acceptance by restaurant personnel. The POS should prompt staff to accept or reject it.
  • OrderPreparing - The order is accepted and preparation is in progress.
  • ReadyForPickUp - Preparation is complete and the order is ready for pickup or delivery (relevant to byCustomer and byOperator).
  • Completed - The order was handed over to the customer or delivery partner.
  • Cancelled - The order was cancelled. This status is final; once cancelled, the order remains cancelled and Qerko refunds the customer.

When the status changes, the POS must call updateQerkoOrderStatus(). The POS controls every status transition. Qerko does not change statuses automatically. You can transition between statuses as needed, except that Cancelled cannot transition back. Switching the order to Cancelled also returns money to the customer.

Methods

Method signatures use TypeScript syntax for documentation purposes.

POS Methods

Below is a list of methods which can be called by Qerko. POS must implement these methods.

All of these methods support the error code ERROR_MESSAGE, which shows the returned message to the customer. Use more specific error codes whenever possible.

getMealMenus()

getMealMenus(): MealMenus

Qerko calls this method when it needs to get fresh menu from the POS. POS should respond with up-to-date menu. This method accepts no arguments.

This method returns MealMenus structure which should contain up-to-date menu.

Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "getMealMenus",
    "args": []
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "getMealMenus",
    "result": {
        "menus": [{
            "id": "the-menu",
            "currency": "CZK",
            "deliveryTypes": [ "toTable", "toBill" ],
            "categories": [
                {
                    "id": "category-1",
                    "name": "Daily offer",
                    "description": "Meals served from 11 AM to 3 PM.",
                    "orderableTimeSlots": [{
                        "startTime": "11:00:00",
                        "endTime": "15:00:00"
                    }],
                    "items": [
                        {
                            "id": "item-1",
                            "name": "Vegetable soup",
                            "description": "Boiled potatoes and a few more ingredients.",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "sale"
                        }, {
                            "id": "item-2",
                            "name": "T-bone steak",
                            "description": "Slice of cow's leg with the bone \"eye\" inside.",
                            "price": "145",
                            "inStock": true,
                            "modifiers": [
                                {
                                    "id": "ab4a054a-5a0a-48fe-947b-f5c23a566bbe",
                                    "minSelected": 1,
                                    "maxSelected": 1,
                                    "maxCount": 1,
                                    "name": "Steak Doneness",
                                    "options": [
                                        {
                                            "id": "b7055208-0827-4eca-8542-bd6d3b99252a",
                                            "menuItemId": "rare",
                                            "defaultSelected": 0,
                                            "addPrice": "0",
                                            "maxCount": 1
                                        },
                                        {
                                            "id": "92d8519f-4cba-4c45-a8fb-989200d50d54",
                                            "menuItemId": "medium",
                                            "defaultSelected": 1,
                                            "addPrice": "0",
                                            "maxCount": 1
                                        }
                                    ]
                                }
                            ],
                            "type": "sale"
                        }
                    ]
                },{
                    "id": "category-2",
                    "name": "Drinks",
                    "description": "Drinks served all the time.",
                    "items": [
                        {
                            "id": "item-3",
                            "name": "Coca-Cola",
                            "description": "We all know it. Ice-cold black sweet drink with bubbles.",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "sale"
                        }, {
                            "id": "item-4",
                            "name": "Beer",
                            "description": "Czech classic beer from Pilsen.",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "sale"
                        }
                    ]
                },
                {
                    "id": "modifiers",
                    "name": "modifiers",
                    "description": "This catogory is for modifier items and won't be showed in application",
                    "items": [
                        {
                            "id": "medium",
                            "name": "Medium",
                            "description": "This item will be hidden in application",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "modifier"
                        },
                        {
                            "id": "rare",
                            "name": "Rare",
                            "description": "This item will be hidden in application",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "modifier"
                        }
                    ]
                }
            ],
            "minOrderTime": 0,
            "maxOrderTime": 0
        }],
        "deliveryInfos": [
            {
                "type": "byOperator",
                "paused": false
            },
            {
                "type": "byCustomer",
                "paused": false,
            },
            {
                "type": "toTable",
                "paused": false
            },
            {
                "type": "toBill",
                "paused": false,
            },
        ],
    }
}

orderPrepare()

orderPrepare(args: object): object

Qerko calls this method as a first step of the order. The order is not submitted by the customer yet, but he has reached a summary before the final submission. This is the moment where he might want to apply a discount, accept an upsell offer, etc. POS can pre-validate the order and offer upsell and/or discounts.

This method can be called multiple times for one order.

Offering discounts and upsells is not ready in this moment. Please contact Qerko if you want to use this feature.

ParameterRequiredTypeDescription
orderIdNostring length: 1 - 128ID of the order which might be assigned in the previous call.
customerIdNonull / string length: 1 - 128ID of the customer. It is not required because the customer might not be logged in yet.
orderDeliveryYesOrderDeliveryToTable, OrderDeliveryToBill, OrderDeliveryByCustomer, OrderDeliveryByOperatorStructure with details regarding the order delivery. See the specific type for details. Eg: { "deliveryType": "toBill", "billId": "xyz" }
itemsYesOrderItem[] items: 1 - 256Ordered items. Eg: [{ "mealId": "m2c1i1001" }]

Returns:

ParameterRequiredTypeDescription
orderIdNostring length: 1 - 128POS can set this to an identifier and Qerko will pass it to next call of this method or to orderStart method.
orderDeliveryYesOrderDeliveryToTable OrderDeliveryToBill OrderDeliveryByCustomer OrderDeliveryByOperatorStructure with details regarding the order delivery. See the specific type for details. Eg: { "deliveryType": "toBill", "billId": "xyz" }
allowTipNobooleanCan the customer add a tip? Default: true
denyDiscountsNobooleanWhether Qerko can apply another discount. Set it to TRUE when there already is an internally applied discount by POS and other discounts are unwanted. This is related to discounts provided by restaurant owners only. Discounts paid by Qerko or third parties (sponsors like breweries) aren’t affected by this property. FALSE - Qerko can apply a discount. TRUE - Qerko can’t apply a discount. Default: false
calculatedUpchargesNoOrderCalculatedUpcharge[]This param allows POS to use upcharges with Qerko to apply service fees, etc.

TIP: You can just return unchanged input.

Error codes
  • ITEM_NOT_AVAILABLE

    • POS returns this error if the ordered item is unavailable.
    • Qerko announces that an item is not available any more and suggests to the custommer to make a new order.
    • Qerko tries to update the menu.
  • INVALID_ITEM_PRICE

    • POS returns this error if the ordered item has different price.
    • Qerko announces that prices have been changed and suggests to the custommer to make a new order.
    • Qerko tries to update the menu.
  • BILL_LOCKED

    • POS returns this error if bill is locked (toBill).
    • Qerko announces that there is a waiter operating with the bill right now and suggest to the customer to try the order afterwards.
  • BILL_NOT_FOUND

    • POS returns this error if the bill with this id does not exist (toBill).
    • Qerko announces that there is a waiter operating with the bill right now and suggest to the customer to try the order afterwards.
  • TABLE_NOT_FOUND

    • POS returns this error if the table does not exist (toTable).
    • Qerko announces that the table doesn’t exist any more and suggests to the custommer to make a new order.
  • BILL_CLOSED

    • POS returns this error if the bill is closed. (toBill).
    • Qerko announces that the bill was closed and it is not possible to make an order to this bill.
Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "orderPrepare",
    "args": [{
        "orderId": "id-order-124",
        "items": [
            { "mealId": "m2c1i1001" }
        ],
        "orderDelivery": {
            "deliveryType": "toBill",
            "billId": "xyz"
        }
    }]
}
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "orderPrepare",
    "result": {
        "orderId": "id-order-124",
        "items": [
            { "mealId": "m2c1i1001" }
        ],
        "orderDelivery": {
            "deliveryType": "toBill",
            "billId": "xyz"
        }
    }
}

orderStart()

orderStart(args: object): object

Qerko calls this method as a second step of an order. The customer has just submitted the order. The order won’t change any more except its status. POS should validate it in this step. POS returns orders and their lifecycle status. Suggested statuses are OrderWaiting, or OrderPreparing.

ParameterRequiredTypeDescription
orderIdNostring length: 1 - 128ID of the order which might be assigned in the previous orderPrepare().
customerIdYesstring length: 1 - 128ID of the customer.
calculatedPriceYesstring regexp: ^\d{1,6}(?:\.\d{1,3})?$ length: 1 - 10Calculated price for items. Eg: “129.66”
orderDeliveryYesOrderDeliveryToTable OrderDeliveryToBill OrderDeliveryByCustomer OrderDeliveryByOperatorStructure with details regarding the order delivery. See the specific type for details. Eg: { "deliveryType": "toBill", "billId": "xyz" }
itemsYesOrderItem[] items: 1 - 256Ordered items. Eg: [{ "mealId": "m2c1i1001" }]
orderDateTimeYesstring length: 1 - 25Marks the time the order has been placed in the Qerko app in the following format: 'yyyy-mm-ddTHH:MM:SS+HH:MM' Eg: "2022-03-21T14:41:50+01:00"

Returns:

ParameterRequiredTypeDescription
orderId Yesstring length: 1- 128Identifier of the created order.
billId Nostring length: 1- 128Required for delivery type toTable. It is the identifier of the created bill to which ordered items were added. This ID must match the ID returned in getTableContents
orderReferenceNostring length: 1- 128Could be used as code for pickup for delivery type byCustomer or byOperator
status YesstringOne of - OrderWaiting - OrderPreparing - ReadyForPickUp - Completed - Cancelled See Orders and their lifecycle section for details.
Error codes

The same as in orderPrepare method.

Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "orderStart",
    "args": [{
        "calculatedPrice": "129.34",
        "items": [
            { "mealId": "m2c1i1001" }
        ],
        "orderDelivery": {
            "deliveryType": "toBill",
            "billId": "xyz"
        }
    }]
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "orderStart",
    "result": {
        "orderId": "id-order-124",
        "status": "OrderWaiting"
    }
}

orderMarkAsPaid()

orderMarkAsPaid(args: Payment): Receipt

Qerko calls this method as an optional third step of an order. This method marks the order as paid. It receives the Payment object with a few modifications - orderId is used instead of idBill and the items property contains an array of Order items instead of BillItems. It returns a Receipt. Analogous to the paymentProcessed method. Method is by default called for orders with delivery type byCustomer, but our experience shows that there is strong demand for orders with delivery type toTable that are paid in advance.

The payment always pays for the whole order. Never only part of it.

Any error cancels the order.

If you wish to integrate and test this method, contact techsupport at techsupport@qerko.com.

orderClose()

orderClose(args: object): null

Qerko calls this method is as a final step of an order. Error in this method won’t cancel the order. Analogous to the paymentClose method in payments.

ParameterRequiredTypeDescription
orderIdYesstring length: 1 - 128ID of the order which was assigned in paymentStart() method.
statusYesstringOne of: OK - Success the order was successfuly ordered, Cancelled - Something went wrong. The order is cancelled.
Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "orderClose",
    "args": [{
        "orderId": "id-order-124",
        "status": "OK"
    }]
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "orderClose",
    "result": null
}

orderStatus()

orderStatus(args: object): object

Qerko calls this method when it need to check the order status on the POS side.

ParameterRequiredTypeDescription
orderIdYesstring length: 1 - 128ID of the order status of which should be returned.

Returns:

ParameterRequiredTypeDescription
statusYesstringOne of: - OrderWaiting - OrderPreparing - ReadyForPickUp - Completed - Cancelled See Orders and their lifecycle section for details
Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "orderStatus",
    "args": [{
        "orderId": "123"
    }]
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "orderStatus",
    "result": {
        "status": "OrderWaiting"
    }
}

getResource()

getResource(args: object): object | null

Qerko calls this method to get resource from the POS. Eg.: images. This method receives a string idResource which was sent in MenuItem .images array. This method returns a structure, which contains mime-type and the data of the resource. POS can also return null if there is no resource avaialable.

Qerko can download all resources immediately after menu sync or any time after. Qerko wil cache the resource. If you want to update the resource send another idResource.

ParameterRequiredTypeDescription
idResourceYesstring
length: 1 - 128
String idResource which was sent in MenuItem.images array.

Returns

ParameterRequiredTypeDescription
mimeYesstringOne of: image/png - PNG format. image/jpeg - JPEG format.
dataYesstring
length: 0 - 1000000
Base64 encoded data. Size of the image in B64 encoding is 1MB (1000000 bytes). It means max file size 750kB (750000 bytes) using B64 encoding, without padding and line ends.
Example with resource
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "getResource",
    "args": [{
        "idResource": "C:\\POS\\images\\the-product.jpg::lastMod=1234567890"
    }]
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "getResource",
    "result": {
        "mime": "image/jpeg",
        "data": " ... JPEG data in Base64 ..."
    }
}
Example with no resource available
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "getResource",
    "args": [{
        "idResource": "C:\\POS\\images\\the-product.jpg::lastMod=1234567890"
    }]
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "getResource",
    "result": null
}

Qerko Methods

Below is a list of methods which can be called by POS using websocket or REST endpoint. Qerko implements them.

updateMenus()

updateMenus(menus: MealMenus): null

POS calls this method and passes MealMenus structure to perform synchronization of menu whenever there is an important change in the menu. It accepts the same structure as is returned by getMealMenus() method.

Example
Websocket
/** Method call request (sent by POS) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "updateMenus",
    "args": [{
        "menus": [{
            "id": "the-menu",
            "lang": "cs",
            "currency": "CZK",
            "deliveryTypes": [ "toTable", "toBill" ],
            "categories": [
                {
                    "id": "category-1",
                    "name": "Daily offer",
                    "description": "Meals served from 11 AM to 3 PM.",
                    "orderableTimeSlots": [{
                        "startTime": "11:00:00",
                        "endTime": "15:00:00"
                    }],
                    "items": [
                        {
                            "id": "item-1",
                            "name": "Vegetable soup",
                            "description": "Boiled potatoes and a few more ingredients.",
                            "price": "45",
                            "tagIds": [ "tag-1", "tag-2" ],
                            "inStock": true
                        }, {
                            "id": "item-2",
                            "name": "T-bone steak",
                            "description": "Slice of cow's leg with the bone \"eye\" inside.",
                            "price": "145",
                            "inStock": true
                        }
                    ]
                },{
                    "id": "category-2",
                    "name": "Drinks",
                    "description": "Drinks served all the time.",
                    "items": [
                        {
                            "id": "item-3",
                            "name": "Coca-Cola",
                            "description": "We all know it. Ice-cold black sweet drink with bubbles.",
                            "price": "45",
                            "inStock": true
                        }, {
                            "id": "item-4",
                            "name": "Beer",
                            "description": "Czech classic beer from Pilsen.",
                            "price": "45",
                            "inStock": true
                        }
                    ]
                }
            ],
            "minOrderTime": 0,
            "maxOrderTime": 0
        }],
        "deliveryInfos": [
            {
                "type": "byOperator",
                "paused": false
            },
            {
                "type": "byCustomer",
                "paused": false,
            },
            {
                "type": "toTable",
                "paused": false
            },
            {
                "type": "toBill",
                "paused": false,
            },
        ],
    }]
}
 
/** Method call response (sent by Qerko) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "updateMenus",
    "result": null
}
Long-polling

Request:

Compiling...

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{}

updateQerkoOrderStatus()

updateQerkoOrderStatus(args: object): object

POS calls this method to change status of the order. Beware: setting the order to Cancelled status is irreversible and will return money to the customer.

ParameterRequiredTypeDescription
orderIdYesstring
length: 1 - 128
ID of the order which was assigned in orderStart() method.
statusYesstringOne of OrderWaiting, OrderPreparing, ReadyForPickUp, Completed, Cancelled. See Orders and their lifecycle section for details.
collectionDateTimeNostringWhen will the order be available for pickup Eg: "2020-01-30T23:42:42Z"
preparedOrderMealIdsNostring[]Relevant for status ReadyForPickUp. List of all items that are ready or were ready in the past. If not specified the order is ready for pickup as whole.
orderReferenceNostringExternal identifier from POS, shown as order identifier in the mobile app.

Returns:

ParameterRequiredTypeDescription
statusYesstringOne of OrderWaiting, OrderPreparing, ReadyForPickUp, Completed, Cancelled. See Orders and their lifecycle section for details.
Example
Websocket
/** Method call request (sent by POS) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "updateQerkoOrderStatus",
    "args": [{
        "collectionDateTime": "2020-01-30T23:42:42Z",
        "orderId": "order-1",
        "status": "ReadyForPickUp",
        "preparedOrderMealIds": [
            "m2c1i1001"
        ]
    }]
}
 
/** Method call response (sent by Qerko) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "updateQerkoOrderStatus",
    "result": {
        "status": "Completed"
    }
}
Long-polling

Request:

Compiling...

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ "status":"OrderPreparing" }

getQerkoOrderStatus()

getQerkoOrderStatus(args: object): object

POS calls this method to get a status of the order.

ParameterRequiredTypeDescription
orderIdYesstring
length: 1 - 128
ID of the order which was assigned in paymentStart() method.

Returns

ParameterRequiredTypeDescription
statusYesstringOne of OrderWaiting, OrderPreparing, ReadyForPickUp, Completed, Cancelled. See Orders and their lifecycle section for details.
paymentStatusNostringState of related payment, if the order was marked as paid. One of STARTED, PROCESSING, PAID, CANCELLED, ERROR.
Error Codes
  • NOT_FOUND
    • We couldn’t find specified order. For POS it means that the order is cancelled. Something could go so wrong, that the order is just lost.
Example
Websocket
/** Method call request (sent by POS) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "getQerkoOrderStatus",
    "args": [{ "orderId": "order-1" }]
}
 
/** Method call response (sent by Qerko) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "getQerkoOrderStatus",
    "result": {
        "status": "Completed",
        "paymentStatus": "PAID"
    }
}
Long-polling

Request:

Compiling...

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ "status": "OrderPreparing", "paymentStatus": "PAID" }

Data structures

Follows a list of data structures, which are used for data exchange between POS and Qerko.

DeliveryAddress

This represent delivery address.

PropertyRequiredTypeDescription
nameYesstringJohn Doe
phoneYesstring+420602341203
emailNostringjohndoe@gmail.com_
streetYesstringStreet address
postcodeYesstringZip-code
cityYesstringCity name
latitudenostring38.8951
longitudenostring-77.0364

OrderItem

This represent order item.

PropertyRequiredTypeDescription
mealIdYesstring
length: 1 - 128
Corresponds to MenuItem.id.
modifiersNoOrderItemModifier[]
items: 0 - 256
Modifiers of the item. Default: [] (empty array) Eg: medium-rare
priceNostring
regexp: ^\\d{1,6}(?:\\.\\d{1,3})?$
length: 0 - 10
Price of the item without used modifiers.

OrderItemModifier

This represent modifier in order item.

PropertyRequiredTypeDescription
idYesstring
length: 1 - 128
Identifier of the modifier.
selectedOptionsYesOrderItemModifierOption[]Selected options of modifiers. Eg: “raw”, “medium”

OrderItemModifierOption

This represent option of modifier in order item.

PropertyRequiredTypeDescription
idYesstring
length: 1 - 128
Identifier of the modifier option.
itemYesOrderItemOrderItem which is used as modifier

Category

This represent menu category. Menus are divided into categories which contains menu items.

PropertyRequiredTypeDescription
idYesstring
length: 1 - 128
Identifier of the category.
nameYesstring
length: 1 - 128
Human readable name. Should be short. _Eg: "Drinks", "Soups", …
descriptionNostring
length: 0 - 256
Human readable description. Default: "" (empty string) Eg: "These are our delicious homebrewn drinks."
itemsNoMenuItem[]
items: 0 - 256
List of items in this category. Default: [] (empty array)
orderableTimeSlotsNoOrderableTimeSlot[]
items: 0 - 256
Slot when it is possible to order items from this category. It can only further limit `orderableTimeSlots` from the whole menu. Default: unlimited

This represents one orderable item.

PropertyRequiredTypeDescription
idYesstring
length: 1 - 128
Identifier of the item. You will receive this in order as `mealId`.
nameYesstring
length: 1 - 128
Human readable name. Should be short
inStockYesbooleanIs item available (= true) or sold-out (= false)?
priceYesstring
regexp: ^\d{1,6}(?:\.\d{1,3})?$
Total price for this items including taxes and packaging.
typeNostringType of MenuItem. Default: "sale". Possible values: "sale" - Item can be ordered alone."modifier" - Item is hidden in application and can be ordered only like modifier.
descriptionNostring
length: 0 - 512
Human readable description. Default: "" (empty string) Eg: "The best drink on Earth. Our bartender has spent a lot of effort to prepare this. Get ready for the best time of your life while drinking it."
deliveryTypesNostring[]
items: 1 - 4 unique items
List of allowed delivery types. It can only further limit deliveryTypes of the whole menu. Possible values: "toTable", "toBill", "byCustomer", "byOperator" Notice: byOperator is unimplemented. Contact Qerko if you want to use it.
imagesNostring[]
length: 1 - 2000
items: 0 - 10
This is list of resourceIds. See getResource() method. Qerko will use these IDs to pull the resources when they are needed. Menu can be quite lengthy and we don’t want to overload the connection with hundreds of images :). Default: [] (empty array)
modifiersNoMenuItemModifier[]
items: 0 - 256
Modifiers that are available for this item Default: [] (empty array) Eg: medium-rare

This represent modifier in menu item.

PropertyRequiredTypeDescription
idYesstring
length: 1 - 128
Identifier of the modifier.
minSelectedYesnumber
range 0 - 65635
Minimum count of selected unique options
maxSelectedNonumber or null
range 1 - 65635
Maximum count of selected unique options. Default null. If null then unlimited.
maxCountYesnumber
range: 1 - 65635
Maximum count of selected non-unique options.
nameYesstring
length: 1 - 128
Name of modifier. Eg. “Pick steak doneness”
optionsYesMenuItemModifierOption[]Modifier options. Eg. “medium rare” “raw”

This represent option of a modifier in menu item.

PropertyRequiredTypeDescription
idYesstring
length: 1 - 128
Identifier of the modifier option.
menuItemIdYesstringID of MenuItem which will be used like modifier option value.
addPriceYesstringPrice of option, which will be added to final orderItem. This price overrides price of the menuItem linked by menuItemId.
defaultSelectedNonumber or nullNumber of default selected items. Default null.
maxCountNonumber or nullMaximum number of selections for this option. Default null. If null then unlimited.

MealMenus

This structure contains a collection of menus. There can be multiple menu alternatives because of different currencies, languages and delivery options.

PropertyRequiredTypeDescription
menusYesOneMealMenu[]
items: 0 - 256
Array of menu alternatives. Up to 5000 items.
deliveryInfosYesDeliveryInfo[]
items: 0 - 4 unique items
Delivery info effects availability of delivery type for the restaurant. If Delivery info for delivery type is missing it means that delivery type is disabled.

OneMealMenu

This sturcrure represents one menu alternative for concrete language, currency and set of delivery types

PropertyRequiredTypeDescription
idYesstring
length: 1 - 128
Identifier of the menu.
categoriesYesCategory[]
items: 0 - 256
List of categories which further contains menu items.
currencyYesstring
length: 3
Currency code according to ISO 4217. Eg: "CZK"
deliveryTypesYesstring[]
items: 1 - 4 unique items
List of allowed delivery types. Possible values: "toTable" - The order can be added to the table as a new open bill. "toBill" - The order can be added to the existing bill. "byCustomer" - The order can be picked up by customer. Used in takeaway windows. "byOperator" - The order can be delivered to given address. This is unimplemented. Contact Qerko if you want to use it.
minOrderTimeYesnumber
value: 0 - 2147483647
Minimum order delay in minutes. Minimum: 0 (Setting the delay to zero means the order can be picked up immediately.) Eg: 10 - it means that the customer can express his preference of pickup time to be in 10 minutes or later.
maxOrderTimeYesnumber
value: 0 - 2147483647
Maximum order delay in minutes. Eg: 30 - it means that the customer can express his preference of pickup time to be in 30 minutes or before.
langYesstring
length: 2
ISO 639-1 language code. Default: universal Eg: "cs"
orderableTimeSlotsNoOrderableTimeSlot[]
items: 0 - 256
Slot when it is possible to order items from this menu. Default: unlimited

OrderableTimeSlot

This structure represents a timespan from to which is used to allow orders.

PropertyRequiredTypeDescription
startTimeYesstring
length: 8
Start time of this slot. Timezone is handled by Qerko configuration, because this isn’t timezoned information. The restaurant usualy opens in 11 AM regardless of summer or winter time. Eg: "11:00:00"
endTimeYesstring
length: 8
Start time of this slot. Timezone is handled by Qerko configuration, because this isn’t timezoned information. The restaurant usualy closes in 11 PM regardless of summer or winter time. Eg: "23:00:00"
startDateNostring or null
length: 10
Start date of this slot. Use dates only if there is some sort of speciality in opening hours like New years eve. Or if it is special category like daily menu. Default: null, means every day Eg: "2021-03-02"
endDateNostring or null
length: 10
End date of this slot. Use dates only if there is some sort of speciality in opening hours like New years eve. Or if it is special category like daily menu. Default: null, means every day Eg: "2021-03-02"

OrderDeliveryByOperator

This structure holds info about delivery by operator. This means classic delivery as known from Uber Eats, Wolt, Foodora, etc.

PropertyRequiredTypeDescription
customerYesDeliveryAddressAddress where to deliver
deliveryTypeYesstringConstant value - "byOperator"
collectionNotesNostring
length: 0 - 256
Customers note meant for the operator. Eg: "Leave the package under the bridge."
kitchenNotesNostring
length: 0 - 256
Customers note meant for the cook. Eg: "Shaken, not stirred."

OrderDeliveryByCustomer

This structure holds info for customers pickup. The customer will pick up the order in the restaurant.

PropertyRequiredTypeDescription
nameYesstring
length: 0 - 128
Name of the customer. Eg: "Miloslav M."
collectionDateTimeYesstringDate and time when the customer wants to arrive Eg: "2021-03-02T14:35:00.000+01:00"
deliveryTypeYesstringConstant value - "byCustomer"
orderReferenceNostringReference number or ID of the order for easier pickup. We strongly recommend to use this property
collectionNotesNostring
length: 0 - 256
This feature is not yet implemented. Contact Qerko if you want to use it. Note regarding pickup Eg: "Wrap it into something special"
kitchenNotesNostring
length: 0 - 256
This feature is not yet implemented. Contact Qerko if you want to use it. Customers note meant for the cook. Eg: "Shaken, not stirred."
phoneNostringThis feature is not yet implemented. Contact Qerko if you want to use it. Phone to the customer. Eg: "+420123456789"

OrderDeliveryToTable

PropertyRequiredTypeDescription
tableCodeYesstring
length: 1 - 256
Code of the table where the customer sits. Corresponds to idTable returned from getTableList
deliveryTypeYesstringConstant value - "toTable"
kitchenNotesNostring
length: 0 - 256
This feature is not yet implemented. Contact Qerko if you want to use it. Customers note meant for the cook. Eg: "Shaken, not stirred."

OrderDeliveryToBill

PropertyRequiredTypeDescription
billIdYesstring
length: 1 - 128
Identifier of the customers bill. Corresponds to Bill.id
deliveryTypeYesstringConstant value - "toBill"
kitchenNotesNostring
length: 0 - 256
This feature is not yet implemented. Contact Qerko if you want to use it. Customers note meant for the cook. Eg: "Shaken, not stirred."
tableCodeNostring
length: 1 - 128
Table identification

OrderCalculatedUpcharge

PropertyTypeRequiredDescription
idstringYesUnique identifier of the upcharge from the POS.
namestringYes
pricestringYesTotal price for the bill upcharge. Price can be zero. Example: 110.00
additionalDataanyNoThe POS can use this for any additional data. Qerko will not modify it, and you can use it in the order process. You will receive it in Payment
typestringYesOptions: POS_PRECALCULATED

Payment

The difference from the default Payment structure is that there is orderId used instead of idBill and the items property contains an array of Order items instead of BillItems.

Used in orderMarkAsPaid() method.

Receipt

Refers to the same structure as in Receipt data structure. Used in orderMarkAsPaid() method.

DeliveryInfo

This structure contains info about a supported delivery types.

PropertyRequiredTypeDescription
typeYesstringDelivery type identifier. Valid values are:
- toTable
- toBill
- byCustomer
- byOperator.
pausedYesbooleanSet to true to pause ordering for this delivery type, for example during peak demand or maintenance.

Need help? Contact techsupport@qerko.com for assistance.