Actions

Send an action directly to a branch's POS device. The device must be online and turned on. The result is not returned in the HTTP response — it is delivered to the webhook URL you specify (or the default webhook configured for your integration).

This reference describes Dotypos 2.17 and newer. The few capabilities that require a newer version are explicitly tagged — for example (2.18+). See the Version history for what each version introduced.

Basic request format

All requests share the basic parameters listed below. For better readability, they are not repeated in every action.

{
  "action": <string>,
  "webhook": <string>,
  "validity": <long>, // Unix timestamp
  "idempotency-key": <string> | null,
  "user-id": <long> // _employeeId
}

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?
Optional identification of a webhook call. It provides a 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.

user-id long?
The value corresponds to _employeeId. The user is resolved for every order/* action: the resolved user is recorded as the acting user of the operation and determines its permissions and — with multiple sellers enabled — the seller context. If the given user does not exist, the action fails with code 1008. When omitted, the POS acts under the integration user created for your API client.

Shared types

Item

id long
Corresponds to _productId

qty double?
Item / product quantity. Defaults to 1 when omitted.

note string?
Note for item / product

discount-percent double?
Value of discount in percent value: 20 = 20%. When provided, this discount is applied to the item exactly as sent and always takes priority over any other discount — the product's fixed sale discount as well as the discount group of the attached customer — even when the request value is lower. If the field is omitted, the customer's discount group (if a customer is attached) or otherwise the product's fixed sale discount (if any) is applied instead.

manual-price double?
Product unit price including VAT

manual-points double?
Points

tags string[]?
Tags attached to the item

course-id long?
Id of a course.

customizations customization[]?
List of customizations for the product. If the field is omitted, the product's configured default customization selections are applied; send an empty array to add the product without any optional customizations.

take-away boolean?
Whether to sell this item as takeaway.

Item Customization

product-customization-id long
Corresponds to _productCustomizationId

product-id long
Corresponds to _productId

manual-price double?
Customization item price override including VAT (default behavior if null or empty)

qty int?
Quantity of customization item (default behavior if null or empty is 1)

Split item

id long
Order item id — should correspond to items[].id from the Response schema

qty double
Quantity to move to the new 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.

Takeaway change

order-item-id long
ID of an order item.

take-away boolean
Whether this item should be set as takeaway.

Print type

Print config

{
    "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 standard

print-logo boolean?
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

An error that occurred 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

Hello

{
  "action": "order/hello"
}

Returns basic POS metadata that can be used for POS liveness checks, timezone configuration, or time shift detection. The registerStatus field tells whether the cash register is currently open.

Response format

{
    "device": <string>,
    "appName": <string>,
    "timezone": <string>,
    "registerStatus": <string>, // "open" | "closed"
    "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%
  "guest-count": <int>,
  "table-id": <long>, // _tableId
  "user-id": <long>, // _employeeId
  "note": <string>,
  "external-id": <string>,
  "delivery": <boolean>,
  "items": [...],
  "lock": <boolean>
}

customer-id long?
The value corresponds to _customerId

discount-percent double?
Value of discount in percent value: 20 = 20%

guest-count int?
Number of guests for the order. Must be greater than 0, otherwise result code 2012 (ORDER_INVALID_GUEST_COUNT) is returned. Since 2.18, if Guest count entry is disabled or unavailable under the POS license, the field is ignored and the order is created without a guest count.

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

delivery boolean?
Marks the created order as a delivery order

items item[]?
List of items to be added to new order. When omitted or empty, an empty order is created.

lock boolean?
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%
  "guest-count": <int>,
  "note": <string>,
  "lock": <boolean>
}

customer-id long?
The value corresponds to _customerId

discount-percent double?
Value of discount in percent value: 20 = 20%

guest-count int?
Number of guests for the order. Must be greater than 0, otherwise result code 2012 (ORDER_INVALID_GUEST_COUNT) is returned. Send null to clear the guest count; if the field is omitted, the guest count stays unchanged. Since 2.18, if Guest count entry is disabled or unavailable under the POS license, the field is ignored and the guest count stays unchanged.

note string?
Personal note to order

order-id long
Order ID for action. The value corresponds to _orderId

lock boolean?
If set to true the order will be locked for 45 s for external changes

Add order items

{
    "action": "order/add-item",
    "order-id": <long>, //_orderId
    "table-id": <long>, // _tableId
    "items": [
        {
            "id": <long>, // _productId
            "qty": <double>, // 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
                "manual-price": <double>,
                "qty": <int>
            }],
            "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

table-id long?
The value corresponds to _tableId. When provided, the order is moved to the given table; when omitted, the order stays on its current table.

lock boolean?
If set to true the order will be locked for 45 s for external changes

Split order

{
  "action": "order/split",
  "order-id": <long>, // _orderId
  "customer-id": <long>, // _customerId 
  "table-id": <long>, // _tableId
  "note": <string>,
  "external-id": <string>,
  "discount-percent": <double>, // 20 = 20%
  "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. The customer is attached to the newly created order. If the customer does not exist, the field is silently ignored — code 1010 is not raised by the split actions.

table-id long?
The value corresponds to _tableId

note string?
Personal note to order

external-id string?
External id set on the newly created order

discount-percent double?
Value of discount in percent value: 20 = 20%. Applied to the newly created order.

split-items split item[]
List of items to be moved to new order (id should correspond to items[].id from Response schema)

lock boolean?
If set to true the original order and the newly created order will be locked for 45 s for external changes

Issue order

{
  "action": "order/issue",
  "order-id": <long>, // _orderId
  "guest-count": <int>,
  "print-config": {},
  "print-email": <string>,
  "print-type": <string>,
  "take-away": <boolean>
}

order-id long
Order ID for action. The value corresponds to _orderId

guest-count int?
Number of guests to set on the order before it is issued. Same rules as for Update order: must be greater than 0 (2012), null clears the value, omitted field leaves it unchanged, and since 2.18 an unavailable Guest count entry feature causes the field to be ignored.

print-config print config?
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.

Pay issued order

{
  "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

{
  "action": "order/create-issue",
  "customer-id": <long>, // _customerId 
  "discount-percent": <double>, // 20 = 20%
  "guest-count": <int>,
  "table-id": <long>, // _tableId
  "user-id": <long>, // _employeeId
  "note": <string>,
  "external-id": <string>,
  "delivery": <boolean>,
  "items": [...],
  "payment-method-id": <long>, // paymentTypeId
  "print-config": {},
  "print-email": <string>,
  "print-type": <string>,
  "take-away": <boolean>
}

customer-id long?
The value corresponds to _customerId

discount-percent double?
Value of discount in percent value: 20 = 20%

guest-count int?
Number of guests to set on the order. Same rules as for Create order.

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

delivery boolean?
Marks the created order as a delivery order

items item[]
List of items to be added to new order

payment-method-id long
Payment method ID

print-config print config?
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.

Create, issue and pay order

{
  "action": "order/create-issue-pay",
  "customer-id": <long>, // _customerId
  "discount-percent": <double>, // 20 = 20% 
  "guest-count": <int>,
  "table-id": <long>, // _tableId
  "user-id": <long>, // _employeeId
  "note": <string>,
  "external-id": <string>,
  "delivery": <boolean>,
  "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?
Value of discount in percent value: 20 = 20%

guest-count int?
Number of guests to set on the order. Same rules as for Create order.

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

delivery boolean?
Marks the created order as a delivery 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 print config?
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.

Split and issue order

{
  "action": "order/split-issue",
  "order-id": <long>, // _orderId
  "customer-id": <long>, // _customerId 
  "table-id": <long>, // _tableId
  "note": <string>,
  "external-id": <string>,
  "discount-percent": <double>, // 20 = 20%
  "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. The customer is attached to the newly created order. If the customer does not exist, the field is silently ignored — code 1010 is not raised by the split actions.

table-id long?
The value corresponds to _tableId

note string?
Personal note to order

external-id string?
External id set on the newly created order

discount-percent double?
Value of discount in percent value: 20 = 20%. Applied to the newly created order.

split-items split item[]
List of items to be moved to new order (id should correspond to items[].id from Response schema)

print-config print config?
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.

Split, issue and pay order

{
  "action": "order/split-issue-pay",
  "order-id": <long>, // _orderId
  "customer-id": <long>, // _customerId 
  "table-id": <long>, // _tableId
  "note": <string>,
  "external-id": <string>,
  "discount-percent": <double>, // 20 = 20%
  "split-items": [
    {
      "id": 123,
      "qty": 12
    }
  ],
  "print-append": <string>,
  "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. The customer is attached to the newly created order. If the customer does not exist, the field is silently ignored — code 1010 is not raised by the split actions.

table-id long?
The value corresponds to _tableId

note string?
Personal note to order

external-id string?
External id set on the newly created order

discount-percent double?
Value of discount in percent value: 20 = 20%. Applied to the newly created order.

split-items split item[]
List of items to be moved to new order (id should correspond to items[].id from Response schema)

print-append string?
Text to be appended to printout

print-config print config?
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.

Issue and pay

{
  "action": "order/issue-and-pay",
  "order-id": <long>, // _orderId
  "payment-method-id": <long>, // paymentTypeId
  "guest-count": <int>,
  "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

guest-count int?
Number of guests to set on the order before it is issued. Same rules as for Update order: must be greater than 0 (2012), null clears the value, omitted field leaves it unchanged, and since 2.18 an unavailable Guest count entry feature causes the field to be ignored.

print-append string?
Text to be appended to printout

print-config print config?
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.

Cancel order

{
  "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

{
  "action": "order/perform-status-transition",
  "order-id": <long>, // _orderId
  "status-transition": <string>
}

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

{
  "action": "order/list",
  "table-id": <long>,
  "customer-id": <long>
}

table-id long?
Table ID. Lists all orders if not present, null for orders outside table

customer-id long?
Customer ID. When present, only orders of the given customer are returned; null returns only orders without a customer. Can be combined with table-id.

Change item's course

{
  "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 Course change[]
List of course changes for items in the given order.

Prepare next course

{
  "action": "order/prepare-next-course",
  "order-id": <long>
}

order-id long
ID of an order.

Print last document (SK)

Request:

{
    "action": "order/sk/print-last-document"
}

Response

{
    "resultCode": <integer>,
}

Set/unset item(s) as takeaway

{
    "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 Takeaway change[]
List of takeaway changes.

Response schema (default)

{
    "order": {
        "id": <long>,
        "bkp": <string>,
        "completed": <timestamp>,
        "canceled-date": <timestamp>,
        "currency": <string(3)>,
        "customer-id": <long>, // _customerId
        "course-id": <long>,
        "guest-count": <int>,
        "user-id": <long>, // _employeeId
        "external-id": <string>,
        "fik": <string>,
        "flags": <integer>,
        "created": <timestamp>,
        "note": <string>,
        "order-number": <string?>,
        "order-series-id": <string>,
        "paid": <boolean>,
        "pkp": <string>,
        "points": <double>,
        "table-id": <long>, // _tableId
        "price-total": <double>,
        "locked-until": <timestamp>,
        "status": <string>
    },
    "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": [...], // see Customization (response)
            "course-id": <long>,
            "name": <string>,
            "alternative-name": <string>,
            "packaging": <double>,
            "points": <double>,
            "product-id": <long>, // _productId
            "price-in-points": <double>,
            "qty": <double>,
            "tags": <string[]>,
            "vat": <double>,
            "take-away": <boolean>
        }
    ],
    "print": [string],
    "print-png": <string?>,
    "code": <integer>,
    "pass-through-errors": [PassThroughError],
    "deviceTimestamp": <long>
}

points double
Loyalty points on the order and on each item.
2.19+ When an order is issued without an assigned customer (customer-id is null), points are cleared to 0 on both the order and all its items. Points never change after the order is issued.

locked-until timestamp?
null means the order is either not locked at all, or locked without an expiration — the default response does not distinguish the two cases. See the Multiple orders response schema for how order/list encodes locks.

print [string]
Contains the base64 representation of receipt.
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?
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]
List of pass-through errors encountered.

Customization (response)

Each element of items[].customizations has the following format. Note that the field names differ from the request-side Item Customization: the request's qty and manual-price correspond to quantity and unit-price here.

{
    "id": <long>,
    "product-customization-id": <long>,
    "product-id": <long>,
    "name": <string>,
    "alternative-name": <string>,
    "quantity": <double>,
    "unit": <string>,
    "unit-price": <double>,
    "purchase-price": <double>,
    "discount": <double>
}

Multiple orders response schema

{
    "orders": [
        {
            "order": {
                "id": <long>,
                "bkp": <string>,
                "completed": <timestamp>,
                "canceled-date": <timestamp>,
                "currency": <string(3)>,
                "customer-id": <long>, // _customerId
                "course-id": <long>,
                "guest-count": <int>,
                "user-id": <long>, // _employeeId
                "external-id": <string>,
                "fik": <string>,
                "flags": <integer>,
                "created": <timestamp>,
                "note": <string>,
                "order-number": <string?>,
                "order-series-id": "0",
                "paid": <boolean>,
                "pkp": <string>,
                "points": <double>,
                "table-id": <long>, // _tableId
                "price-total": <double>,
                "locked-until": <timestamp>,
                "status": <string>
            },
            "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": [...], // see Customization (response)
                    "course-id": <long>,
                    "name": <string>,
                    "alternative-name": <string>,
                    "packaging": <double>,
                    "points": <double>,
                    "product-id": <long>, // _productId
                    "price-in-points": <double>,
                    "qty": <double>,
                    "tags": <string[]>,
                    "vat": <double>,
                    "take-away": <boolean>
                }
            ]
        }
    ],
    "code": <int>,
    "deviceTimestamp": <long>
}

The points fields follow the same rule as in the default response schema: issuing without an assigned customer clears them to 0.

locked-until timestamp?
Unlike the default response, order/list distinguishes lock states: null always means the order is not locked, and an order locked without an expiration is returned with locked-until set to a maximal timestamp value (9223372036854775807).

Error response

When processing fails, the webhook receives an error envelope instead of the order payload:

{
    "code": <integer>,
    "message": <string>,
    "localizedMessage": <string>, // some errors only
    "deviceTimestamp": <long>
}

code integer
Result code of the failure.

message string
Human-readable cause of the failure in English. For code 2999 this is the only way to distinguish the underlying failure.

localizedMessage string?
Localized description of the failure. Sent only by errors that provide it (currently product-not-found failures).

deviceTimestamp long
Current UTC timestamp of device (in ms)

Result codes

These represent the result of processing — they are NOT HTTP response codes.