API
Ask or search…
⌃K
Links
Comment on page

POS actions

Send action to specific branch
Send action directly to a branch device and response will send to webhook. Branch device must be turned on.
Response header Response-url contains webhook URL from request body or default webhook URL.
Note that integers in responses from POS Actions are NOT sent as strings.
If you don't sent webhook in request or webhook is null. Response body contain response from default webhook URL.
The number of requests when using the default webhook URL is limited to one request running at same time for the same combination of userId, clientId, cloudId, branchId.

Result codes

Response status code is primary OK 200. For correct status use code properties in webhook response.
Represent the result of processing. There are NOT the response codes.
Code
Value
Description
0
CODE_OK
​
100
CODE_OTHER
​
1001
REQUEST_ERROR
​
1002
CONFIGURATION_ERROR
Current configuration of cash register does not allow to perform requested POS action.
1003
MISSING_ACTION
Your request is missing action parameter
1004
UNKNOWN_ACTION
Requested action is unknown or no more supported
1005
DATA_FORMAT_ERROR
​
1006
LICENSE_ERROR
License of the Cash Register is not sufficient to perform requested POS action.
1007
EXPIRED_REQUEST
validity of request is expired
1008
USER_NOT_FOUND
user-id of request was not found in App
1009
ACTION_NOT_ALLOWED_FOR_COUNTRY
1.242+ Executed action is not allowed for current POS country.
1999
SERVER_ERROR
​
2001
ORDER_LOCKED
Requested order is locked to another service/user
2002
ORDER_NOT_FOUND
Order with given id not found
2003
ORDER_PAYMENT_METHOD_NOT_FOUND
Payment method with given id not found
2004
ORDER_PAID
Order is already paid
2005
ORDER_ISSUED
Order is already issued
2006
ORDER_NOT_ISSUED
Order is not issued yet
2007
INVALID_PRINT_EMAIL
SK print-email is required to be a valid email for give print-type.
2008
INVALID_PRINT_TYPE
SK print-type none is not supported.
2009
ORDER_NOT_EMPTY
Order is not empty, there are some items in it.
2010
ORDER_ALREADY_CANCELED
Order can't be canceled as it is already canceled.
2999
ORDER_OTHER
​
3001
REGISTER_CLOSED
Cash Register is closed. You need to open the cash register to be able to do any order modifications.
4001
PRODUCT_NOT_FOUND
Requested product was not found in database of Cash Register
5001
ORDER_ITEM_NOT_FOUND
The item of the selected order is not presented on the order.
5002
ORDER_ITEM_LOW_QUANTITY
Requested change cannot be performed due to low quantity of order item.
5003
ORDER_ITEM_NEGATIVE_QUANTITY
Requested change cannot be performed due to negative quantity change in request.
6001
ORDER_TRANSITION_UNKNOWN
The requested transition is not known (maybe old version of Dotypos App).
6002
ORDER_TRANSITION_DENIED
The requeste transition could not be performed.
7001
COURSE_CHANGE_NOT_ALLOWED_FOR_PRODUCT
The specified course is not allowed for the given product.
7002
COURSE_CHANGE_ITEM_ALREADY_PREPARED
Unable to change item's course because this item has already been prepared.
8001
TAKE_AWAY_NOT_ENABLED
Takeaway is disabled on POS.
8002
TAKE_AWAY_NOT_ALLOWED_FOR_PRODUCT
Takeaway is not allowed for given product (see response for details).
8003
TAKE_AWAY_NOT_ALLOWED_FOR_ORDER
Takeaway is not allowed for whole orders.
8004
TAKE_AWAY_NOT_ENABLED_FOR_ORDERS_WITH_NO_TAKEAWAY_ITEMS
Unable to set the order as takeaway because the order does not contain any items with takeaway allowed.
10001
CUSTOMIZATION_NOT_FOUND
No customization found for the given id (see response for details).
10002
CUSTOMIZATION_CATEGORY_NOT_FOUND
No customization category found for the given id (see response for details).
10003
PRODUCT_NOT_FOUND (when working with customizations)
No product found for the given id (see response for details).
10004
PRODUCT_NOT_FOUND_IN_CUSTOMIZATION
Product with given id couldn't be found in given customization (see response for details).
10005
INVALID_SELECTED_QUANTITY
The given quantity of a product is not within customization's bounds (see response for details).

Basic request format

All request shares some basic parameters listed below. For better readability are those parameters are not shown in all methods.
{
"action": <string>,
"webhook": <string>,
"validity": <long>, // Unix timestamp
"idempotency-key": <string> | null
}
action string Name of action
webhook string? Webhook URL for action response
validity long? Validity of request in Unix timestamp. If the time on cash register is greater than this value, the request will not be performed with response code 1007
idempotency-key string? (Since Dotypos 2.1) Optional identification of a webhook call. It provides way for you to identify retried (same) webhook calls. When webhook parameter is filled, Dotypos will call the given URL with the Idempotency-Key header containing this value. If you do not specify idempotency-key, it will be automatically generated and sent.

Hello (1.239.8+)

{
"action": "order/hello"
}
Returns basic POS metadata can be used for POS liveness checks, timezone configuration, or time shift.

Response format

{
"device": <string>,
"timezone": <string>,
"version:": {
"id": <string>, // "com.touchpo.android"
"code": <long>,
"name": <string>,
},
"code": <int>,
"deviceTimestamp": <long> // Current UTC timestamp of device (in ms)
}

Create order

{
"action": "order/create",
"customer-id": <long>, // _customerId
"discount-percent": <double>, // 20 = 20%
"table-id": <long>, // _tableId
"user-id": <long>, // _employeeId
"note": <string>,
"external-id": <string>,
"items": [...],
"lock": <boolean>
}
customer-id long? The value corresponds to _customerId
discount-percent double? (1.238.12+) Value of discount in percent value: 20 = 20%
table-id long? The value corresponds to _tableId
user-id long? The value corresponds to _employeeId
note string? Personal note to order
external-id string? External id of the order
items item[] List of items to be added to new order
lock boolean? (1.234+) If set to true the order will be locked for 45 s for external changes

Update order

{
"action": "order/update",
"order-id": <long>, // _orderId
"customer-id": <long>, // _customerId
"discount-percent": <double>, // 20 = 20%
"note": <string>,
"lock": <boolean>
}
customer-id long? The value corresponds to _customerId
discount-percent double? Value of discount in percent value: 20 = 20%
note string? Personal note to order
order-id long Order ID for action. The value corresponds to _orderId
lock boolean? (1.234+) If se to true the order will be locked for 45 s for external changes

Add order items

{
"action": "order/add-item",
"order-id": <long>, //_orderId
"items": [
{
"id": <long>, // _productId
"qty": <doble>, // quantity
"note": <string>,
"discount-percent": <double>, // 20 = 20%
"manual-price": <double>,
"manual-points": <double>,
"tags": <string[]>,
"course-id": <long> | null,
"customizations": [{
"product-customization-id": <long>, // _productCustomizationId
"product-id": <long> // _productId
}],
"take-away": <boolean>
}
],
"lock": <boolean>
}
items item[] List of items to be added
order-id long Order ID for action. The value corresponds to _orderId
lock boolean? (1.234+) If set to true the order will be locked for 45 s for external changes

Item

id long Corresponds to _productId
qty double Item / product quantity
note string? Note for item / product
discount-percent double? Value of discount in percent value: 20 = 20%
manual-price double? Product price
manual-points double? Points
tags string[]? Note for item
course-id long? Id of a course. Since Dotypos 1.237
customizations customization[]? Add product with customization Dotypos 1.234+ required

Item Customization

Dotypos 1.234+ required
product-customization-id long Corresponds to _productCustomizationId
product-id long Corresponds to _productId
take-away boolean? Whether to sell this item as takeaway. Since Dotypos 1.237.

Split order (1.234)

{
"action": "order/split",
"order-id": <long>, // _orderId
"customer-id": <long>, // _customerId
"table-id": <long>, // _tableId
"note": <string>,
"split-items": [
{
"id": "123",
"qty": "12"
}
],
"lock": <boolean>
}
order-id long Order ID of order to split. The value corresponds to _orderId
customer-id long? The value corresponds to _customerId
table-id long? The value corresponds to _tableId
note string? Personal note to order
split-items boolean? List of items to be moved to new order (id should correspond items[].id from Response schema.
lock boolean? If set to true the newly created order will be locked for 45 s for external changes

Issue order

Not allowed in following countries: Slovakia.
We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/issue",
"order-id": <long>, // _orderId
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"take-away": <boolean>
}
order-id long Order ID for action. The value corresponds to _orderId
print-config pringConfig[]? Print configuration for print type
print-email string? Email for print type
print-type string? Print type (mode)
take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Pay issued order

Not allowed in following countries: Slovakia.
{
"action": "order/pay",
"order-id": <long>, // _orderId
"payment-method-id": <long> // paymentTypeId
}
order-id long Order ID for action. The value corresponds to _orderId
payment-method-id long Payment method ID​

Create and issue order (1.234)

Not allowed in following countries: Slovakia.
We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/create-issue",
"customer-id": <long>, // _customerId
"discount-percent": <double>, // 20 = 20%
"table-id": <long>, // _tableId
"user-id": <long>, // _employeeId
"note": <string>,
"items": [...],
"payment-method-id": <long>, // paymentTypeId
"take-away": <boolean>
}
customer-id long? The value corresponds to _customerId
discount-percent double? (1.238.12+) Value of discount in percent value: 20 = 20%
table-id long? The value corresponds to _tableId
user-id long? The value corresponds to _employeeId
note string? Personal note to order
items item[] List of items to be added to new order
payment-method-id long Payment method ID​
take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Create, issue and pay order (1.234)

We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/create-issue-pay",
"customer-id": <long>, // _customerId
"discount-percent": <double>, // 20 = 20%
"table-id": <long>, // _tableId
"user-id": <long>, // _employeeId
"note": <string>,
"items": [...],
"payment-method-id": <long>, // paymentTypeId
"print-append": <string>,
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"take-away": <boolean>
}
customer-id long? The value corresponds to _customerId
discount-percent double? (1.238.12+) Value of discount in percent value: 20 = 20%
table-id long? The value corresponds to _tableId
user-id long? The value corresponds to _employeeId
note string? Personal note to order
items item[] List of items to be added to new order
payment-method-id long Payment method ID​
print-append string? Text to be appended to printout
print-config pringConfig[]? Print configuration for print type
print-email string? Email for print type
print-type string? Print type (mode)
take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Split and issue order (1.234)

Not allowed in following countries: Slovakia.
We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/split-issue",
"order-id": <long>, // _orderId
"customer-id": <long>, // _customerId
"table-id": <long>, // _tableId
"note": <string>,
"split-items": [
{
"id": "123",
"qty": "12"
}
],
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"lock": <boolean>,
"take-away": <boolean>
}
order-id long Order ID of order to split. The value corresponds to _orderId
customer-id long? The value corresponds to _customerId
table-id long? The value corresponds to _tableId
note string? Personal note to order
split-items boolean? List of items to be moved to new order (id should correspond items[].id from Response schema.
print-config pringConfig[]? Print configuration for print type
print-email string? Email for print type
print-type string? Print type (mode)
lock boolean? If set to true the original order will be locked for 45 s for external changes
take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Split, issue and pay order (1.234)

We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/split-issue-pay",
"order-id": <long>, // _orderId
"customer-id": <long>, // _customerId
"table-id": <long>, // _tableId
"note": <string>,
"split-items": [
{
"id": "123",
"qty": "12"
}
],
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"payment-method-id": <long>, // paymentTypeId
"lock": <boolean>,
"take-away": <boolean>
}
order-id long Order ID of order to split. The value corresponds to _orderId
customer-id long? The value corresponds to _customerId
table-id long? The value corresponds to _tableId
note string? Personal note to order
split-items boolean? List of items to be moved to new order (id should correspond items[].id from Response schema.
print-config pringConfig[]? Print configuration for print type
print-email string? Email for print type
print-type string? Print type (mode)
payment-method-id long Payment method ID​
lock boolean? If set to true the original order will be locked for 45 s for external changes
take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Issue and pay

We allow you to invoke optional notifications displayed for staff on the POS for issued orders via POS Action. If you want to use this feature, contact us. We will enable functionality for your API application.
Since Dotypos 1.241
{
"action": "order/issue-and-pay",
"order-id": <long>, // _orderId
"payment-method-id": <long>, // paymentTypeId
"print-append": <string>,
"print-config": {},
"print-email": <string>,
"print-type": <string>,
"take-away": <boolean>
}
order-id long Order ID for action. The value corresponds to _orderId
payment-method-id long Payment method ID​
print-append string? Text to be appended to printout
print-config pringConfig[]? Print configuration for print type
print-email string? Email for print type
print-type string? Print type (mode)
take-away boolean? Whether to issue this order as takeaway. Since Dotypos 1.237.

Cancel order (1.243+)

{
"action": "order/cancel",
"order-id": <long> // _orderId
}
order-id long Order ID for action. The value corresponds to _orderId. Order must be empty - it can't have any items.

Change order status (1.234+, WIP)

{
"action": "order/perform-status-transition",
"order-id": <long>, // _orderId
"status-transition": <string>
}
This endpoint is in active development phase. List of available transitions and their limitations could be changed in any further release of Dotypos App.
order-id long Order ID for action. The value corresponds to _orderId
status-transition string Transition to be performed. Check Order Status page for list of supported transitions.

Get list of open orders (1.235+)

{
"action": "order/list",
"table-id": <long>
}
Returns list of data in Multiple orders response format​
table-id long? Table ID, list all orders if not presented, null for orders outside table

Change item's course (1.237+)

If there are multiple course changes for the same item, only the last is applied.
{
"action": "order/change-item-course",
"order-id": <long>,
"course-changes":[{
"order-item-id": <long>,
"new-course-id": <long> | null
}]
}
order-id long ID of the order.
course-changes CourseChange[] List of course changes for items in the given order.

Course Change

order-item-id long ID of an order item.
new-course-id long? ID of a new course for the given item within an order.

Prepare next course (1.237+)

Response field next-course-id describes the next available response for this order.
{
"action": "order/prepare-next-course",
"order-id": <long>
}
order-id long ID of an order.

Set/unset item(s) as takeaway (1.237+)

If there are multiple takeaway changes for the same order item, only the last one will be applied.
{
"action": "order/set-item-takeaway",
"take-away-changes": [{
"order-item-id": <long>, // id of an order item, NOT product
"take-away": <boolean>
}],
"order-id": <long>
}
order-id long ID of an order.
take-away-changes TakeawayChange[] List of takeaway changes.

Takeaway change

order-item-id long ID of and order item.
take-away boolean Whether this item should be set as takeaway.

Shared types

local
Print on device printer
remote
Print task in format ESC/POS will contain in response (print-config is required) SK - change Using remote also requires print-email field to be sent. Response will contain the base64 encoded representation of the receipt file (print-png field). If, for some reason, receipt couldn't have been base64 encoded, the original file stays on POS (see Pass-through errors). 1.243+ If fiscal printout is not available for remote printing, print won't be added and pass-through-errors will contain error 100006.
email
Receipt will be sent to the email address specified in print-email. SK - change Also email of Order's customer can be accepted. If email sending fails (see Pass-through errors), POS will try to fill at least base64 representation of receipt (as stated in the description of remote print-type above). 1.243+ If fiscal printout is not available, email won't be sent and pass-through-errors will contain error 100006.
none
Dont print SK - change Not allowed in Slovakia. Returns an error.
{
"characters": <integer>,
"codepage": <byte>,
"print-mini": <boolean>,
"print-logo": <boolean>,
"cut": <boolean>,
"append-lines": <integer>,
"font": <integer>
}
characters integer? Width of print in characters
codepage byte?
print-mini boolean? Print in mini mode or standart
print-logo boolean? 1.243+ Print logo on receipt (if the logo is configured for any receipt print task in the register)
cut boolean? Is cut supported
append-lines integer? Number of lines appended to print
font integer(0,1)? Font type

Pass-through error (1.242+)

An error that occured during Order processing but didn't cause the processing to fail. Might be interpreted as a warning to the user.
{
"code": <integer>,
"description": <string>,
"localized-description": <string>
}
code integer Error code.
description string General description of a pass-through error in English.
localized-description string Localized description of a pass-through error in language specified in the request. If no language is specified in the request, defaults to POS' language.

Possible pass-through errors

code
description
100001
SK Fiscal receipt file not found. Usually when order is successfully fiscalized, but the fiscal module didn't fill the path to the receipt file. The fiscal receipt was probably printed locally.
100002
SK Fiscal receipt email not sent. Email with fiscal receipt couldn't have been sent. print-png field of response should contain the Base64 encoded receipt file instead (see next).
100003
SK Fiscal receipt base64 creation failed. Could not encode the receipt file in Base64. print-png field in response is null. In case this happens, the receipt file won't be deleted from POS (it can be retrieved manually - contact support).
100004
SK Fiscal receipt possibly incomplete. Might happen when the fiscal module haven't finished writing/creating the receipt file even after extensive amount of time.
The electronic receipt sent to customer might have been incomplete. The receipt file won't be deleted from POS (it can be retrieved manually - contact support).
100005
SK Fiscal receipt possibly old. When the receipt file we found was created more than 60 seconds prior to the processing. The electronic receipt sent to customer might not be the correct one. The receipt file won't be deleted from POS (it can be retrieved manually - contact support).
100006
Can't obtain fiscal receipt printout. Fiscal receipts can be printed only locally (fiscal receipt is printed only on paper by fiscal the printer)

Response schema (default)

{
"order": {
"id": <long>,
"bkp": <string>,
"completed": <timestamp>,
"canceled-date": <timestamp>, // 1.243+
"currency": <string(3)>,
"customer-id": <long>, // _customerI
"course-id": <long>, // 1.234+
"user-id": <long>, // _employeeId
"external-id": <string>,
"fik": <string>,
"flags": <integer>,
"created": <timestamp>,
"note": <string>,
"order-number": <string?>, // 1.243+
"order-series-id": <string>,
"paid": <boolean>,
"pkp": <string>,
"points": <double>,
"table-id": <long>, // _tableId
"price-total": <double>,
"locked-until": <timestamp>,
"status": <string> // 1.234+
},
"next-course-id": <long> | null,
"items": [
{
"id": <long>, // _orderItemId
"price-with-vat": {
"unit-billed": <double>,
"total": <double>,
"unit": <double>
},
"price-without-vat": {
"unit-billed": <double>,
"total": <double>,
"unit": <double>
},
"customizations": [],
"course-id": <long>, // 1.234+
"name": <string>,
"packaging": <double>,
"points": <double>,
"product-id": <long>, // _productId
"price-in-points": <double>, // 1.234+
"qty": <double>,
"tags": <string[]>,
"vat": <double>,
"take-away": <boolean>
}
],
"print": [string],
"print-png": <string?>, // 1.242+
"code": <integer>,
"pass-through-errors": [PassThroughError], // 1.242+
"deviceTimestamp": <long> // 1.239.8+
}
print [string] Contains the base64 representation of receipt. 1.243+ If the register has configured multiple receipt print tasks, there will be added print content for each of them. All configured filters and print configurations for the task will be applied. Fiscalized receipt content is added only if it is available, otherwise print won't be added and pass-through-errors will contain error 100006.
print-png string? 1.242+, SK Contains the base64 representation of a receipt returned by the fiscal module when print-type: "remote" or when print-type: "email" and email sending fails.
pass-through-errors [PassThroughError] 1.242+ List of pass-through errors encountered.

Multiple orders response schema

{
"orders": [