The 30,000 Foot View

Almost every resource of interest is scoped by realm or the company alias, defined by alias in the Company entity—which is not directly accessible, but is returned as part of the getClientInfo response.

Types of Resources

Inside each realm or account, the system is structured as follows.

Organizational and Infrastructure Resources

These resources define the overall configuration of the system, such as sales locations, cash registers, printers, users, permissions, and software integrations.

• Locations: Defines physical sales locations (and/or stock locations). Entities like cash registers, orders, bookable resources, tabs and stock balances are scoped to locations.
• Tills: Cash registers, ordering devices or other kinds of trusted devices that is registered to this account, almost always associated with a specific location. They are the only kind of clients that may perform sales or register other kinds of financial records in the electronic journal; see Operational Resources below for more information.
• Users: Administrators, cashiers, other staff; basically any person that should have access to the account in some way. This also includes service accounts, which are used by internal APIs or external integrations. Each user, in turn, holds:
  • Access Tokens: Holds API keys and other kinds of secrets.
  • Triggers: Used to activate web hooks or generate reports based on events generated by the system; see also Event Streams below for an alternate approach.
  • Trigger Events: A resource that keeps logs of triggers that have fired or failed.
• Roles: Defines an extra set of permissions, which may be granted to users.
• Peripherals: External devices (physical or logical) present at a location that a trusted devices may communicate with, such as receipt/kitchen printers and statically configured credit card terminals.
• Integrations: A registry of 3rd party OAuth integrations that may be enabled by users to extend the system's capabilities. Once enabled, each instance will be issued an API access token (and possibly a dedicated service user).
• Event Streams: Software modules and devices may register to receive events from the system in real-time, which is what this resource is used for.

Business Resources

These resources define how the business operates, like what is being sold and how.

• Customers: The customer register.
• Payment Methods: Custom payment methods such as vouchers or foreign currencies that should also be accepted as payments.
• Products: Goods or services that may be sold to customers. Products can have fixed or open price (always specified including VAT), as well as fixed or open quantities (normally fixed to 1).
• Product Groups: Every product belongs to exactly one product group, which specifies general properties of the products, such as what kind of product it is, its VAT rate and what accounts to use for bookkeeping when its sold.
• Product Modifiers: Defines "extras" that may be added to individual products, or, more commonly, all products that belong to a given product group. A modifier is either just a set of text values (like "Without cheese"), a list of references to other products ("Sriracha Dipping Sauce", which may or may not have a non-zero price), or a list of Labels that can affect the layout of kitchen tickets.
• Promotions/Campaigns: Rules for automatic discounts.
• Resources: Bookable resources, such as dinner tables, hairdressing chairs, rooms etc.
• Vouchers: A register of all issued server-managed vouchers (payment vouchers or coupons), Including identifiers, balance, expiry date, owner and more.

Operational Resources

These resources reflect business activity in the system.

• Electronic Journal: A place where financial records—such as sales receipts—are written as cashiers log in or out, make sales and create reports as part of the daily use of cash registers and ordering devices. The cash register will always queue journal records locally before flushing the queue to this resource, in order to being able to operate even when offline.
• Inventory Adjustments: Incoming and outgoing deliveries of products that are subject to inventory management are registered here, as are reconciliation of the inventory.
• Orders: This resource keeps track of bookings, reservations, open tabs and incoming orders (like for take-out).
• Shifts: Keeps track of when employees arrive/punch in and leave/punch out.
• Stock Balances: This resource holds the current inventory level for each enabled product (per location). The level is automatically adjusted based on explicit inventory adjustments, receipts being stored in the journal (that is, completed sales and refunds) and tabs being opened, updated or closed.
• Tabs: Holds lists of products that are being sold to customers, but not yet paid for. Tabs are normally used for table service, but may also be used for take-out orders (pre-paid or not) that are to be picked up later. Tabs reference orders (there can be multiple open tabs for each order—one for each person at a dinner table, for example), and tabs are also normally scoped to a location via the order.

Presentation and Categorization Resources

Finally, there are a few resources of interest that are used to organize other resources, or to define the visual appearance of certain views in the cash register.

• Accounts: A register of all bookkeeping accounts used by the company.
• Button Maps: Specifies the visual layouts of product and discount buttons in the cash registers and ordering devices, or to define menus (for take-out orders or just to be displayed on displays or web sites).
• Labels: A register of all labels/tags used by the company. Any number of labels may be attached to (almost) every entity in the system, and may be used for arbitrary grouping or categorization.
• Label Categories: All labels are organized in categories.
• Resource Maps: Groups and defines the visual layout of bookable resources, such as dinner tables in a section of a restaurant.

Flows and Relationships

Here's how some of the resources are related to each other and how they are used by the system.

Physical Sales

1. When a cashier logs in to a cash register, he or she does so an a physical device that is bound to a Till entity with a 1-to-1 relationship, authenticating as a User. Such events are always logged in the cash register's Electronic Journal.
2. The cash register uses the associated Location to determine how the receipt should look like, what Button Map to display, what kitchen printers are available and if it should listen for incoming Take-Out Orders (see Orders below).
3. Products are then added to a Tab, either by the cashier pressing buttons on a Button Map or by scanning barcodes. When a product is added, additional information such as its VAT rate or if a kitchen ticket should be printed is fetched from the Product Group that the product belongs to. Also, the Product Modifiers resource is consulted to see if any extras should be added to the product, and discounts may be automatically applied based on the configured Promotions/Campaigns.
4. The cashier may then optionally choose to park the Tab—that is, save it for later and start registering a new sale. When a tab is parked, both an Order and a Tab are created. The order is used to bind the parked tab to the cash register's location and specific Resources, like a dinner table. When the tab is resumed and paid for, the order is marked as fulfilled and the tab is removed. (The tab is also removed if the cashier chooses to cancel it, but in this case the order is marked as cancelled instead of fulfilled.) Records logging tab operations will also be added to the cash register's Electronic Journal.
5. When a sale is to be finished, payments are collected by the cashier based on the available Payment Methods, kitchen tickets are printed to kitchen printers, the Order and Tab are closed and a Receipt record—including information about which customer made the purchase if provided, in addition to the products sold and how they were paid for—is added to the Electronic Journal. Finally, the receipt is then printed on the receipt printer or delivered electronically.

Note that the cash registers may operate even when offline. If so, records to the journal will be buffered and uploaded once connectivity is restored.

Orders

The Order resource acts kind of like a calendar and is used to keep track of bookings, reservations, open tabs and incoming orders (like for take-out). An order belongs to a Location and references Customers, Resources and Users. It can hold one or more Payments to indicate that the order has already been paid for (fully or partially) and may be confined to a specific timespan. Any number of Tabs may be associated with an order.

How orders are used by cash registers when parking tabs is described in the previous section.

Bookings and Reservations

When used for bookings and reservations, the order should be created in a requested or booked state, probably also referencing Resources/Users and the Customer that made the reservation, by the external booking system when the customer makes a reservation. It is then transitioned to the active state by the cashier when the customer arrives and a tab is opened. Finally, it is transitioned to the fulfilled state when the customer leaves.

Triggers on the Orders, Tabs and Electronic Journal resources may be used to notify the booking system when tabs are added, modified or closed, when the state of the order changes and to inspect the final receipt(s).

Take-Out Orders

Take-out orders are orders created by an external web site or app, and then prepared and made ready for pick-up or delivery by the restaurant (or other kind of business). Since the products are added by the external system, it's a bit more involved than the other use cases.

1. First, a TakeOutConfig and at least one menu should be configured. These resources define what products are available for take-out ordering, how they should be presented in the external system and at what times they may be ordered.
2. Second, the ordering system must synchronize the Location, its menu and all Products, Product Groups and Product Modifiers it references. Use Triggers to keep your system up to date and don't forget to synchronize newly referenced entities as well.
3. Once the ordering system has all information it needs, it may begin adding orders of type take-out and state requested. You should include Products, discounts and optionally Payments, an end date (what time the order should be ready for pick-up), a Customer and a Resource (for order-at-table services).
4. The cash registers use Event Streams to listen for incoming orders, which is also reflected in the active property of the TakeOutStatus resource. Use this flag to indicate to the customer that orders will be accepted.
5. Once a new order is added, a cashier accepts it by changing its state to booked, optionally also adding a start date as a reminder of when to start preparing the order.
6. The order's state changes to active when the order is being prepared, optionally with an updated end date in case the business is too busy to prepare the order in time. This causes kitchen tickets to be printed and the requested items to be transferred to a fresh Tab.
7. When the order is ready, the cashier changes its state to shipped, indicating that the order is ready for pick-up or delivery.
8. Finally, the order is marked as fulfilled when the customer has picked up the order. If the order was pre-paid, the Payments are transferred to the final receipt, or else the order is paid for as usual by the customer.

As always, use Triggers to keep your system up to date regarding the state of the order and to inspect the final receipt, if required.

Importing Sales Data from External Systems

If you prefer to handle sales yourself, separate from the Onslip 360 system, it's still possible to import sales and accounting data into Onslip 360 by using an external journal. This is a special kind of Electronic Journal that is not bound to an actual cash register, but rather an Access Token, allowing sales data to be injected using a dedicated API.

1. First, you need an actual external journal to write to. This is created automatically when a user authorizes an OAuth Integrations that:
   1. Is confined to a location (but not authorization).
   2. Includes the add-external-records permission in the Integration.permissions list.
   3. Actually asks for the permission, either by just requesting the default permissions or including add-external-records in the scope query parameter list of the authorization endpoint.
2. Second, the external sales system must synchronize the relevant Products, Product Groups, Product Modifiers, Payment Methods and other entities required (such as Customers, Orders, Tabs and Users), to construct an External Receipt. Use Triggers to keep your system up to date and don't forget to synchronize newly referenced entities as well, if required.
3. Once the external system has all information it needs, it may begin adding External Receipt records to the provided external Electronic Journal using the addExternalRecord endpoint.

note

The ability to inject sales/accounting data and to send digital receipts via Onslip 360 does not turn your system into an authorized cash register. You must still comply with local laws and regulations regarding cash registers, electronic fiscal devices, online sales, invoicing and accounting.

This feature is only intended to provide a seamless experience for your users and to help them keep track of sales and accounting data, from both your system and their own cash registers, in one place.

The provided external journal will accept writes via the newly created Access Token and be configured to close the batch (sales period) and automatically generate a Z-report at the end of the day.