Tills

Type	Base Path	Trigger Name
REST resource	~{realm}/tills/	tills

This resource holds a list of all trusted devices. For historical reasons, this resource and the related entity objects use the term till (that is, cash register), but ordering devices are also trusted devices, and more types may be added in the future.

Endpoints

Name	Method	Relative Path	Payload	Response	Description
addTill	POST	~{realm}/tills/	Till	Stored_Till	Adds a new trusted device to the list.
listTills	GET	~{realm}/tills/	N/A	Stored_Till[]	Retrieves a list of trusted devices.
getTill	GET	~{realm}/tills/{id}	N/A	Stored_Till	Retrieves a trusted device.
putTill	PUT	~{realm}/tills/{id}	Till	Stored_Till	Replaces a trusted device.
updateTill	PATCH	~{realm}/tills/{id}	Partial_Till	Stored_Till	Updates specified trusted device fields.
removeTill	DELETE	~{realm}/tills/{id}	N/A	N/A	Deletes a trusted device.

Permissions

Permission	Description
bind-control-unit	Client is allowed to set the control-unit-id property, if this was previously unset.
bind-tills	Client is allowed to set the device-id and device-key properties, if these were previously unset.
edit-location	Client is allowed to modify the account-config and location properties.
edit-till-config	Client is allowed to modify the config property.
edit-tills	Client is allowed to add new trusted devices and to modify or delete existing trusted devices.
show-tills	Client is allowed to query the trusted device list and to fetch individual trusted devices.

Entities

Interface Till

namespace Till {
    type Type = 'till' | 'ordering-device' | 'external-journal';
}

interface Till {
    'name': string;
    'type'?: Till.Type;
    'description'?: string;
    'location'?: number;
    'config'?: TillConfig;
    'account-config'?: AccountConfig;
    'device-id'?: string;
    'device-key'?: Base64String;
    'control-unit-id'?: string;
    'client-version'?: string;
    'client-user-agent'?: string;
    'cloud-control-unit'?: CloudControlUnit;
    'id'?: number;
    'created'?: DateTime;
    'updated'?: DateTime;
    'deleted'?: DateTime;
    'updated-by'?: number;
    'updated-from'?: number;
    'tags'?: string[];
    'labels'?: number[];
}

Property	Data Type	Description
name	String	The legal name of the trusted device.
type	Till.Type?	Type of trusted device. till (or null) means a cash register.
description	String?	A human-readable name of the trusted device.
location	Int64?	ID of Location this device belongs to.
config	TillConfig?	Settings that applies to this trusted device only.
account-config	AccountConfig?	Account configuration overrides for this trusted device.
device-id	String?	The UID (physical hardware ID) of this trusted device.
device-key	Base64String?	The secret key used for device authentication. See Authentication & Authorization.
control-unit-id	String?	The UID/serial number of the control unit in use by this cash register.
client-version	String?	Used to notify trusted devices that there is a software update available. If this version is greater than the software currently in use, the cashier will be prompted to upgrade.
client-user-agent	String?	The last seen User-Agent string of this trusted device. Will be updated automatically by the system.
cloud-control-unit	CloudControlUnit?	A configuration object for cloud-based, online-only control units.
id	Int64?	The resource ID of this entity.
created	DateTime?	Date and time when this entity was first created.
updated	DateTime?	Date and time when this entity was last modified.
deleted	DateTime?	Date and time when this entity was deleted.
updated-by	Int64?	ID of User who last modified this entity.
updated-from	Int64?	ID of Till (trusted device) which last modified this entity.
labels	Int64[]?	A list of Label IDs associated with this entity.

Interface AccountConfig

interface AccountConfig {
    'payment-methods'?: PaymentMethodAccount[];
    'product-groups'?: ProductGroupAccount[];
    'rounding'?: number;
    'mismatches'?: number;
    'gratuities'?: number;
    'journal-series'?: string;
    'cost-center'?: CostCenter;
}

Property	Data Type	Description
payment-methods	PaymentMethodAccount[]?	A list of account overrides for payment methods.
product-groups	ProductGroupAccount[]?	A list of account overrides for product groups.
rounding	Int32?	Account override for receipt rounding.
mismatches	Int32?	Account override for Z-report/reconciliation mismatches.
gratuities	Int32?	Account override for gratuities.
journal-series	String?	Account override for journal/verification series.
cost-center	CostCenter?	Account override for cost center.

Interface CostCenter

interface CostCenter {
    'code': string;
    'name': string;
}

Property	Data Type	Description
code	String	The short cost center name or identifier.
name	String	The name of the cost center.

Interface PaymentMethodAccount

interface PaymentMethodAccount {
    'payment-method'?: number;
    'method': PaymentMethod.Type;
    'account?': number;
    'clearing-account?': number;
    'vat-account'?: number;
}

Property	Data Type	Description
payment-method	Int64?	ID of custom PaymentMethod, if any. Required if type is anything except cash, card or credit.
method	PaymentMethod.Type	Type of payment method.
account	Int32?	Account override for transaction account.
clearing-account	Int32?	Account override for clearing account. Set it to same value as account if unused.
vat-account	Int32?	Account override for VAT account (if applicable).

Interface ProductGroupAccount

interface ProductGroupAccount {
    'product-group': number;
    'account'?: number;
    'vat-account'?: number;
    'discount-account'?: number;
}

Property	Data Type	Description
product-group	Int64	ID of ProductGroup.
account	Int32?	Account override for sales account.
vat-account	Int32?	Account override for VAT account (if applicable).
discount-account	Int32?	Account override for discount account. Set it to same value as account if unused.

Interface TillConfig

interface TillConfig {
    'peripheral-bindings'?: PeripheralBinding[];
    'auto-close-batch-schedules'?: string[];
    'button-map'?: number;
}

Property	Data Type	Description
peripheral-bindings	PeripheralBinding[]?	A list of all know peripherals (printers, scanners etc.), including information about what this trusted device uses them for.
auto-close-batch-schedules	CronExpr[]?	A cash register-specific schedule for automatic Z-reports/reconciliations.
button-map	Int64?	A reference to this trusted device's button map (if unset, the global default will be used).

Interface PeripheralBinding

interface PeripheralBinding {
    'name': string;
    'address'?: string;
    'exclusive': boolean;
    'device-id': string;
    'device-name': string;
    'device-type': string;
    'device-model': string;
    'device-version': string;
    'service-bindings': PeripheralServiceBinding[];
}

Property	Data Type	Description
name	String	The name of the peripheral (may differ from device-name if configured via the peripherals resource).
address	String?	Address (IP address, device path, etc) of peripheral, if available.
exclusive	Boolean	If true, the trusted device should keep this peripheral connected and not share it with others.
device-id	String	Unique peripheral ID.
device-name	String	Peripheral name.
device-type	String	Peripheral type.
device-model	String	Peripheral model.
device-version	String	Peripheral software version.
service-bindings	PeripheralServiceBinding[]	A list of services the peripheral provides, and what this trusted device uses them for.

Interface PeripheralServiceBinding

interface PeripheralServiceBinding {
    'functions': Peripheral.Function[];
    'name': string;
    'service-id': string;
    'service-name': string;
    'service-type': string;
    'service-hint'?: string;
}

Property	Data Type	Description
functions	Peripheral.Function[]	What this trusted device uses this service for. See the documentation of the Peripheral entity
name	String	Name of the service. (may differ from service-name if configured via the peripherals resource).
service-id	String	Unique service ID.
service-name	String	Service name.
service-type	String	Service type.
service-hint	String?	If the peripheral knows that a printer or VFD is connected to serial port service, for instance, that may be communicated here.