Skip to main content

Bill

Pay at Table integrations are currently standalone from Pay at Counter and Online payments. This is because the current version of the Tables API uses an asynchronous WebSocket protocol for its messaging.

A bill is an itemized statement of charges for the goods and services provided to a customer. In a restaurant, a bill will include food and beverages, along with any additional charges, such as taxes or service fees. It may also include gratuity or tips, and it is the stage at which discounts, promotions, and special offers are applied.

A requestor can use the Tables API to access the detailed, itemized bill found on a POS.

Operations​

Because Tables is a WebSockets Async API, each of these bill operations has both a SUB (subscribe) as well as a PUB (publish) message. The subscribe messages are the requests, while the publish messages are the responses.

There are three bill operations included in the Tables API:

  • GetBillItems retrieves a list of the individual items within a specific bill.
  • GetFullBill provides detailed information about a specific bill, as well as other receipt configuration options.
  • ListBillItems retrieves summarized information about multiple bills for a specified session.

Bill items​

billItems represents the comprehensive breakdown of a customer's bill. It is included in the JSON response of each of the three bill operations.

Quantities​

The billItems object includes an items attribute that can accommodate multiple instances of the same item, provided that the item itself does not have quantities.

tip

While you can use the item.quantity property, it's usually more straightforward to assign a quantity of 1 to all items, regardless of how many times they appear on the bill. This approach ensures easier handling of items with modifiers.

Modifiers​

Modifiers provide a detailed means of specifying the contents of an order. They can be utilized in various ways, such as indicating promotional offers applicable to a bill or item, listing additional condiments requested with a meal, or representing different sizes or variations of the same item.

Categories​

While it is not mandatory, it is recommended to use item.category in compatible POS systems. This is useful because it gives requestors more detailed insights to offer to the merchant.

Example​

This example includes modifiers, quantities, and categories. It uses the scenario of a buy one, get one free promotion on beer:

[
  {
    "id": "987654321",
    "name": "Peroni",
    "category": [
      "drinks",
      "beer",
      "lager"
    ],
    "quantity": 1,
    "amountPerItem": 450,
    "lastOrderedAt": "2021-01-01T15:00:00.123+02:00"
  },
  {
    "id": "987654321",
    "name": "Peroni",
    "category": [
      "drinks",
      "beer",
      "lager"
    ],
    "quantity": 1,
    "amountPerItem": 0,
    "lastOrderedAt": "2021-01-01T15:00:00.123+02:00",
    "modifiers": [
      {
        "id": "mod-123123",
        "name": "Buy 1 get 1 free!",
        "amountPerModifier": -450,
        "quantity": 1
      }
    ]
  }
]
info

The two amount properties in this sample interact:

item.modifiers[].amountPerModifier: This property indicates the amount that is either added to or subtracted from the original item price, such as in the case of modifiers or special offers. item.amountPerItem: This property represents the item price without any modifiers or adjustments.

Printing​

Printing the bill on your Dojo card machine organizes the itemized bill information from your POS using preconfigured templates. The fullBill schema manages all the available templating options. You have the following options:

  • fullBill.header: formatting for the bill header
  • fullBill.billItems: the bill item data
  • fullBill.footer: formatting for the bill footer

You can use any number of receiptSection options in the header and footer:

  • receiptHorizontalLine: Adds either a single or double horizontal line to break up content.
  • receiptImage: Adds an SVG representation of an image with alignment options.
  • receiptLogo: Adds a centre-aligned SVG representation of an image.
  • receiptMerchantAddress: Adds a pre-formatted version of the full address belonging to the merchant.
  • receiptMerchantEmailAddress: Adds the pre-formatted email address of the merchant.
  • receiptMerchantName: Adds the pre-formatted name of the merchant.
  • receiptMerchantPhoneNumber: Adds a pre-formatted phone number belonging to the merchant.
  • receiptText: Includes a generic text line with customizable options. There are three available sizes: SIZE_HEADER_1 (20 characters per line), SIZE_HEADER_2 (24 characters per line), and SIZE_BODY (28 characters per line). Additionally, you can choose the alignment, and there's an option to embolden the text if desired.
  • receiptURL: Adds a URL with the option to display it as a QR code along with any descriptive text.
  • receiptVATNumber: Adds a pre-formatted VAT number belonging to the merchant.

An example of the typical Tables API bill along with each piece of preformatting is available here.

Last updated on