POS Gateway Guide

Introduction

The POS Gateway provides a standardized and streamline way to deliver POS data to Fourth systems. It acts as a single point-of-entry to all Fourth systems that use POS data. This data in turn drives:

  • Labor forecasts in Demand Forecasting
  • Inventory movement in Purchasing and Inventory
  • Business Intelligence (BI) reporting in Fourth Analytics

If you are a POS provider, we highly recommend integrating with this gateway, rather than working on a custom integration. Doing so makes sure that you will only need to integrate once with us, regardless of which systems you need to communicate with now or in the future.

To integrate, follow these steps:

  1. Contact Fourth, so that we can provide account details and support your business.
  2. Develop your CSV export, using the information on this page.
  3. Test your integration with our sandbox.
  4. Get the customer to provide written sign-off.
  5. Go live!

Updates

Date Version Description
11 Nov 2019 2.13

Updated the description for MajorGroupDesc. If your customer is using Fourth Adaco, each value must be prefixed with a two-digit number between 01-99. The numbers should be unique. For example:

  • 01-Food
  • 02-Beverages
  • 03-Retail
20 Oct 2019 2.12

Revised documentation:

  • Clarified that any times sent in should be for the transaction time, not for when a tab closed.
  • Unless otherwise advised by Fourth, please leave the UnitId field blank. Entering values in this field can cause issues with processing the data. Instead, the SiteLocationCode field should have the identifying codes for stores, cafes, restaurants or other physical locations.
  • Converted (Conv) fields must have the same values as the related, non-converted field. For example, the value of ListPrice and ListPriceConv must be the same. Note that you must still continue to include both fields.
13 Sep 2019 2.11 New transaction type variants are avialable for VOID_WASTE. See the VOID_WASTE transaction type in Table 1: transaction types below. To support this, the DeductionDesc column is now required for VOID_WASTE transaction types.
18 Feb 2019 2.10

Guide launched on the Developer Hub. Changes from 2.09 include:

  • The transaction type VOID_WASTAGE has been renamed to VOID_WASTE. Existing integrations can continue to use VOID_WASTAGE.

How is the data delivered?

Data is delivered to Fourth as a CSV file, which we call a "Transaction Dataset" file. You can send this using either FTP or our POS Transaction API.

POS Transaction API

The POS Transaction API is our preferred data delivery method. It is a RESTful API that supports HTTP connections. See the reference for details.

FTP

If desired, you can use FTP to deliver the file.

Due to the sensitive nature of the data, each Fourth customer is given an individual FTP folder and login credential per POS provider they work with. For example, if you are a POS provider, you will have a separate FTP folder for each Fourth customer, that will only ever have data from your POS systems. This ensures privacy and security for both the Fourth customers and POS providers.

Testing

We provide a sand-box environment for testing data submission. If you would like to test our API, please contact Fourth for a test account.

When you are ready to go live, we need the related Fourth customer to provide written authorization. After this, we issue a set of secure login credentials, and you can begin submitting live POS data.

The Transaction Dataset file

The Transaction Dataset file is a denormalized export of POS transactions from the POS provider's database (or data warehouse). The POS provider (or customer) should send a file daily to Fourth, with incremental data. The file should be:

  • Format: A .CSV file that is comma delimited, and with double-quote around each field; for example: “field1”,”field2”. Ensure that none of the text in your fields include double-quotes; for example "10" pizza", as this will cause data issues.
  • Encoding: Encoded according to the UTF-8 standard without BOM.
  • File limit: Below the daily limit of 350 MB (of unzipped data).
  • Cell character limit: No more than 255 characters for each field.
  • (un)zipped files: Either unzipped or zipped, as required.

Sample file

Files for multiple locations

Preferably, the database should send a single daily file that contains the transactional data for all locations for a customer. However, providers can also send a separate file for each location, if necessary.

Data duplication

Fourth expects only incremental POS data in each new file. Sending unnecessary data (that is, data Fourth has already received that does not include updates or new records) must be keep to a minimum to reduce the resources needed and time taken to process.

However, it may be permissible to send rolling dates, of 3 days maximum. This is dependent on your data volume and scenario. You must check with Fourth first before doing this.

Transaction types

To use the data sent in the file, Fourth needs to know what type of transaction each record relates to. This is set using the TransactionTypeCode field for each record. For example, SALES_ITEM identifies records for items that were recorded as a sale on a till (or ePOS). You MUST set a transaction type code for each record — otherwise the record is deemed invalid!

To understand how transaction types are related, see example scenarios below.

Some transaction types require you to send data in every field, while others only require a sub-set of fields. Table 3 (below) shows which fields must be populated with valid data for each transaction type.

Table 1: transaction types

Fourth transaction type code Description
DISC_ITEM Represents a discount applied to one specific item. It provides additional information about the discount such as discount name and id.
MAINS_AWAY This represents an instruction to the kitchen that the customer has finished their starters and the kitchen should start preparing the main course (or the next course).
MODIFIER_ITEM Modifier Item i.e. no cheese. It is useful to separate small modifications to a main menu item so that we can add that layer of analysis to our Business Intelligence (BI) dashboards. Because modifiers are usually small additions or deductions, they can be ignored in the labor forecasting computation.
PRINT_CHECK This represents when the server prints the bill (used in conjunction with tender or tab close to see how long the customer waited to pay the bill).
SALES_ITEM Represents the sale of a menu item. This transaction type carries critical information including but not limited to adjusted tax for the actual price paid, the list price of the item (price on the menu) and the price paid that will include any discount at the item or check level.
SERVICE_CHARGE Represents any service charges posted on the check, as well as any tips (if these are recorded on the POS).
TAB_CLOSE

Represents the time the check is closed.

For TAB_OPEN & TAB_CLOSED: Where multiple records are recorded against a single check code, use the field TransactionStartEnd to indicate first and last record for the check. These values to use are:

  • "1" — first record
  • "2" — last record
TAB_OPEN Represents the time the check is opened.
TENDER Represents the amount paid on the check, which should be split out by tender type (for example: "CASH" or "VISA").
VOID_ERROR

Item that was voided to correct an error that occurred before prep.

An example of this is an error when the waiter entered the information in the till. This is swiftly corrected without any impact either to the stock of the labor (nothing was prepared).

VOID_ITEM

Item that was voided after some labor occurred, where the item goes back to stock.

An example is an unopened bottled beer that is returned because the customer changed their mind. This impacts the labor because someone needs to serve the beer, but does not impact the stock because the beer can be put back in stock.

VOID_WASTE
VOID_WASTE2
VOID_WASTE3
VOID_WASTE4
VOID_WASTE5
VOID_WASTE6
VOID_WASTE7
VOID_WASTE8
VOID_WASTE9
VOID_WASTE10
VOID_WASTE11

Item that was voided after preparation, where the item reduces the stock available. An example is a cocktail that has been prepared but is returned because the customer did not like it. This void category impacts both the stock (raw ingredients used) and the labor (as someone had to prepare the cocktail).

There are eleven VOID_WASTE variants. This allows our mutual customer to differentiate between what caused a VOID_WASTE transaction. For example, they could be used to indicate:

  • VOID_WASTE2 — food or beverages voided because there was a mistake during ordering.
  • VOID_WASTE3 — food or beverages voided because the diner did not like the taste.
  • VOID_WASTE4 — food voided due to contamination from the kitchen (e.g. meat on a vegetarian pizza).
  • VOID_WASTE5 — staff meals
  • etc...

Please work with our mutual customer and the Fourth CSM team to decide the meaning of each VOID_WASTE variant.

The variants are all exported to Fourth Inventory. In the rest of the Fourth Platform, such as Fourth Analytics, the variants are aggregated to a single variant: VOID_WASTE.

Ensure that you also include the DeductionDesc column for each VOID_WASTE variant, as this shown onscreen to Fourth Inventory users.

Types of data fields

The type of data added as fields in the .csv file are either:

  • Values — FACT and FACT (INT).
  • Dimensions — ATTRIBUTE, ATTRIBUTE (DATE) and ATTRIBUTE (TIME).

The restrictions and formats of these types are shown in the next table. All fields must be enclosed with double quotes, for example “Margherita”.

Table 2: Data field types

Format Description
FACT

Number, up to 4 decimal points.

FACT fields should contain POSITIVE (+ve) values for the fields of all transaction types. This includes voided transaction types (VOID_ITEM, VOID_ERROR, and VOID_WASTE). 

However, you can include a NEGATIVE (-ve) number when sending a cancellation or reversal of a transaction that was previously reported.   

For example:

"123.45"

FACT (INT)

Number, with no decimal point.

As with FACT fields, FACT (INT) fields should contain a POSTIVE (+ve) number, unless you are sending a cancellation or reversal of a previous transaction.

For example:

"12345"

ATTRIBUTE

Text string, no longer than 255 characters. For example:

"AbC123"

ATTRIBUTE (DATE)

Date, in the format: YYYY-MM-DD. For example:

"2019-01-30"

ATTRIBUTE (TIME)

Time, in the format: HH:MM:SS. For example:

"23:07:57"

Times are in their local timezone, rather than a UTC value.

For each transaction, send the time that the transaction occurred, rather than the time that the tab was closed. This will help provide the customer with better analytics.

Field headers

When creating your .csv file, the first row must use the header names listed in Table 3 below (these are also the same header names shown in Table 4). The header names are not case sensitive.

The file must include all the headers. If there is no data for the field, then insert these default values, rather than leave the field empty. The default values are:

  • For FACT fields — enter zero value, i.e. "0"
  • For ATTRIBUTE fields — enter a blank string value, i.e.  ""

Table 3: Fields required for each transaction type

As this table has many columns, we have provided an .xlsx file with the same fields as Table 3.

Key for the table:

  • Y — Fields that must contain valid data.
  • c — Fields calculated by Fourth. Include the column in your .csv export, but do not populate the value.
  • / — Fields Fourth has reserved for future use. Please include the column in your .csv export.
  • empty — Fields that are not used for the transaction type, or that should normally remain blank. Please include the column in your .csv export.
 
Column
DISC_ITEM
MAINS_AWAY
MODIFIER_ITEM
PRINT_CHECK
SALES_ITEM
SERVICE_CHARGE
TAB_CLOSE
TAB_OPEN
TENDER
VOID_ERROR
VOID_ITEM
VOID_WASTE
1 TransactionId Y Y Y Y Y Y Y Y Y Y Y Y
2 UnitId                        
3 SiteLocationCode Y Y Y Y Y Y Y Y Y Y Y Y
4 TradingDate Y Y Y Y Y Y Y Y Y Y Y Y
5 Time Y Y Y Y Y Y Y Y Y Y Y Y
6 TimeFact c c c c c c c c c c c c
7 TerminalCode Y Y Y Y Y Y Y Y Y Y Y Y
8 TerminalDesc Y Y Y Y Y Y Y Y Y Y Y Y
9 RecordActivityCode Y Y Y Y Y Y Y Y Y Y Y Y
10 ReceiptCode Y Y Y Y Y Y Y Y Y Y Y Y
11 CheckCode Y Y Y Y Y Y Y Y Y Y Y Y
12 TableCode Y Y Y Y Y Y Y Y Y Y Y Y
13 RevenueCentreCode Y Y Y Y Y Y Y Y Y Y Y Y
14 RevenueCentreDesc Y Y Y Y Y Y Y Y Y Y Y Y
15 TransactionTypeCode Y Y Y Y Y Y Y Y Y Y Y Y
16 SalesItemId c c c c c c c c c c c c
17 SalesItemPLU Y   Y   Y         Y Y Y
18 SalesItemGUID Y   Y   Y         Y Y Y
19 SalesItemDesc Y   Y   Y         Y Y Y
20 TenderTypeCode                 Y      
21 TenderTypeDesc                 Y      
22 DeductionCode Y   Y   Y              
23 DeductionDesc Y   Y   Y             Y
24 Covers             Y          
25 Qty Y   Y   Y   Y     Y Y Y
26 Currency Y Y Y Y Y Y Y Y Y Y Y Y
27 ListPrice Y   Y   Y         Y Y Y
28 Tax Y   Y   Y   Y     Y Y Y
29 PricePaid Y   Y   Y   Y     Y Y Y
30 Deduction Y   Y   Y   Y     Y Y Y
31 TenderAmount           Y Y   Y      
32 CostPriceTheo                        
33 ListPriceConv Y   Y   Y         Y Y Y
34 TaxConv Y   Y   Y   Y     Y Y Y
35 PricePaidConv Y   Y   Y   Y     Y Y Y
36 DeductionConv Y   Y   Y   Y     Y Y Y
37 TenderAmountConv           Y Y   Y      
38 CostPriceTheoConv                        
39 OrderTypeDesc Y   Y   Y              
40 MenuBand Y   Y   Y              
41 MajorGroupDesc Y   Y   Y         Y Y Y
42 FamilyGroupDesc Y   Y   Y         Y Y Y
43 SubGroupDesc Y   Y   Y         Y Y Y
44 TabOwner Y Y Y Y Y Y Y Y Y Y Y Y
45 TabOwnerDesc Y Y Y Y Y Y Y Y Y Y Y Y
46 OriginalTabOwner Y Y Y Y Y Y Y Y Y Y Y Y
47 OriginalTabOwnerDesc Y Y Y Y Y Y Y Y Y Y Y Y
48 OldTableCode / / / / / / / / / / / /
49 PrevTransactionCode / / / / / / / / / / / /
50 AuthorisedBy / / / / / / / / / / / /
51 TextField / / / / / / / / / / / /
52 GuestDesc / / / / / / / / / / / /
53 GuestCode / / / / / / / / / / / /
54 TimeSentToPrep / / / / / / / / / / / /
55 BumpTime / / / / / / / / / / / /
56 UniversalTimeSlotId c c c c c c c c c c c c
57 TimeSlotDesc / / / / / / / / / / / /
58 TransactionStartEnd Y Y Y Y Y Y Y Y Y Y Y Y
59 IsDeleted / / / / / / / / / / / /
60 customfield1 / / / / / / / / / / / /
61 customfield2 / / / / / / / / / / / /
62 customfield3 / / / / / / / / / / / /
63 customfact1 / / / / / / / / / / / /
64 customfact2 / / / / / / / / / / / /
65 DateFact c c c c c c c c c c c c

Table 4: Field descriptions

# Column Description
1

TransactionId
 

A unique ID for this record.

For new records, this value must always be unique, and not repeat across days or locations. To update an existing record, submit the updated data using the ID of the existing record.

Field name: Primary key

Type: Attribute

2 UnitId
 

Customer or POS stock location code. Unless otherwise advised by Fourth, please leave this field blank.

    Field name: Unit ID

    Type: Attribute

    3 SiteLocationCode

    The code for the store, cafe, restaurant or other physical location. The values need to be set in advance of sending us data. There are two ways to achieve this:

    • Fourth can provide you with the existing codes for locations, which you then add or map to the POS system. These codes are discoverable as Fourth accounting codes in our Workforce Management solution.
    • Your business can provide a list of your own codes with the names of the locations. We then create a mapping to our codes. However, you will need to ensure that you provide us with the new code when a new location is added.

    Field name: Site location code

    Type: Attribute

    4

    TradingDate

    Must use the format: YYYY-MM-DD.

    Field name: Date

    Type: Attribute

    5

    Time

    Must use the format: HH:MM:SS. Send this in the local time, rather than the time in UTC.

    For each transaction, send the time that the transaction occurred, rather than the time that the tab was closed. This will help provide the customer with better analytics.

    Field name: Time

    Type: Attribute

    6

    TimeFact

    A numeric time reference. Leave empty, as Fourth populates this field.

    Field name: Time fact

    Type: Fact (INT)

    7

    TerminalCode

    The ID of the POS (or till) on which the transaction occurred.

    Leave this field blank if you cannot supply this information.

    Field name: Terminal code

    Type: Attribute

    8

    TerminalDesc

    Description of the POS (or till), if applicable.

    Leave this field blank if you cannot supply this information.

    Field name: Terminal description

    Type: Attribute

    9

    RecordActivityCode

     

    Incremental record number for each transaction or check record. The record number should usually reset for each check.

    Field name: Record activity code

    Type: Attribute

    10

    ReceiptCode

    Number or code shown on printed receipt. This can differ from the check code.

    Leave this field blank if you do not have separate receipt codes.

    Field name: Receipt code

    Type: Attribute

    11

    CheckCode

    The check or transaction reference that identifies the bill for the table. Ideally this would be unique.

    Field name: Check code

    Type: Attribute

    12

    TableCode

    Tab or table reference. For example: 

    • "17"
    • "table 4"

    Leave this field blank if customer sales are not assigned to tables.

    Field name: Tab code

    Type: Attribute

    13

    RevenueCentreCode

    Revenue center code or reference.

    Use the values in your POS system for these fields.

    Field name: Revenue centre code

    Type: Attribute

    14

    RevenueCentreDesc

    Description for the revenue center; for example:

    • "restaurant"
    • "bar"

    Use the values in your POS system for these fields.

    Field name: Revenue centre desc

    Type: Attribute

    15

    TransactionTypeCode

    Used to categorize the type of record. See Transaction types for a table of values.

    Field name: Transaction type code

    Type: Attribute

    16

    SalesItemId

    A Fourth ID. Leave empty, as Fourth populates this field.

    Field name: Sales item ID

    Type: Attribute

    17

    SalesItemPLU

     

    The item's PLU code. You must:

    • Always supply a value for this field (for the relevant transactions types)
    • Use the codes from Fourth Purchase to Pay and Inventory

    Field name: Sales item PLU

    Type: Attribute

    18

    SalesItemGUID

    Alternative product reference field. This is normally your POS system's reference.

    Leave this field blank if you do not have a separate POS GUID for the sales item.

    Field name: Sales item GUID

    Type: Attribute

    19

    SalesItemDesc

    Product description, for example:

    • "cheeseburger"

    Field name: Sales item description

    Type: Attribute

    20

    TenderTypeCode

    Code. For example:

    • "12"

    Use the values in your POS system for these fields.

    Field name: Tender type code

    Type: Attribute

    21

    Tendertypedesc

    Type of payment. For example:

    • "VISA"
    • "CASH"
    • "PAYPAL"

    Use the values in your POS system for these fields.

    Field name: Tender type description

    Type: Attribute

    22

    DeductionCode

    Deduction code. For example:

    • "1234"

    Use the values in your POS system for these fields.

    Field name: Deduction code

    Type: Attribute

    23

    DeductionDesc

    Deduction description. For example:

    • "25% off bill"
    • "staff meal"

    Ensure that you include this field for all relevant transaction types, as it is the user-friendly description shown onscreen to users. For example, VOID_WASTE transactions must include this description so that users can understand what type of wastage occurred. 

    Field name: Deduction description

    Type: Attribute

    24

    Covers

     

    Use this field for these transaction types:

    • TAB_CLOSE — to record the number of covers (guests).
    • SALES_ITEM — to record the number of mains.

    Otherwise, leave the value as zero.

    Field name: Covers

    Type: Fact (INT)

    25

    Qty

    Count of the items sold, discounted, modified, etc.

    Field name: Quantity

    Type: Fact

    26

    Currency

    Local currency symbol. For example:

    • "GBP"
    • "USD"
    • "EUR"

    Field name: Currency

    Type: Attribute

    27

    ListPrice

    The items price as advertised in the menu. This is in your local currency.

    Do not multiply this by Qty.

    UK:
    Use the item's price inclusive of VAT and before any deductions or discounts on the check or item.

    US:
    Use the item's price exclusive of tax and before any deductions or discounts on the check or item.

    Field name: List price

    Type: Fact

    28

    Tax

    Amount of tax applied to the item, in local currency. To enter the correct amount:

    • Ensure that the tax is applied to the PricePaid and not the ListPrice.
    • Calculate the amount of tax after the price is multipled by Qty.

    Field name: Tax

    Type: Fact

    29

    PricePaid

    Price the item was sold at, inclusive of tax and including any deductions (e.g. promotions, discounts or refunds). This should be in the local currency.

    If the record is for multiple items, then this price must be the combined price for all items. That is, the price must be multiplied by the quantity (Qty) of items sold in this transaction.

    Field name: Price paid

    Type: Fact

    30

    Deduction

    Amount of deduction applied to the item, in local currency. This number should always be POSITIVE (+ve).

    If the record is for multiple items, then this value must be the combined deduction for all items.

    Field name: Deduction

    Type: Fact

    31

    TenderAmount

    Amount tendered for the sale, in local currency.

    Field name: Tender amount

    Type: Fact

    32

    CostPriceTheo

    The theoretical cost of the item sold, in local currency. Do not use this field unless otherwise directed by Fourth or the mutual customer.

    Field name: Theoretical cost price

    Type: Fact

    33

    ListPriceConv

    Use the same value as ListPrice unless otherwise advised by Fourth.

    Field name: List price (converted)

    Type: Fact

    34

    TaxConv

    Use the same value as Tax unless otherwise advised by Fourth.

    Field name: Tax (converted)

    Type: Fact

    35

    PricePaidConv

    Use the same value as PricePaid unless otherwise advised by Fourth.

    Field name: Price paid (converted)

    Type: Fact

    36

    DeductionConv

    Use the same value as Deduction unless otherwise advised by Fourth.

    Field name: Deduction (converted)

    Type: Fact

    37

    TenderAmountConv

    Use the same value as TenderAmount unless otherwise advised by Fourth.

    Field name: Tender amount (converted)

    Type: Fact

    38

    CostPriceTheoConv

    Do not use this field unless otherwise directed by Fourth or the mutual customer. If using, enter the same value as CostPriceTheo , unless otherwise advised by Fourth.

    Field name: Theoretical cost price (converted)

    Type: Fact

    39

    OrderTypeDesc

    The order type, for example:

    • "Eat in"
    • "Takeaway"

    Use the values in your POS system for these fields.

    Field name: Order type

    Type: Attribute

    40

    MenuBand

    Menu price band; also known as "menu level" and "price band". For example:

    • "low"
    • "1"

    This is used when you have the same product that is sold at different prices at different times, for example happy hour.

    Leave this field blank if you are not using it. 

    Field name: Menu band

    Type: Attribute

    41

    MajorGroupDesc

    For each sales item, your POS system can send product category data. You can include up to three levels of hierarchy:

    1. MajorGroupDesc — the primary level of categorization, e.g. "Beverages" 
    2. FamilyGroupDesc — the second level of categorization, e.g. "Wine"
    3. SubGroupDesc — the last level of categorization, e.g. "White Wine"

    If your customer is using Fourth Adaco, each value must be prefixed with a two-digit number between 01-99. The numbers should be unique. For example:

    • 01-Food
    • 02-Beverages
    • 03-Retail

    If you are sending only one level of hierarchy, send these values in the field MajorGroupDesc.

    If you are sending two levels of hierarchy, send these values in the fields MajorGroupDesc and FamilyGroupDesc.

    Field name: Major group description 

    Type: Attribute

    42

    FamilyGroupDesc

    Second level of categorization from the POS system. For example:

    • "Starters"
    • "Mains"
    • "Drinks" 

    Field name: Family group description

    Type: Attribute

    43

    SubGroupDesc

    Third level of categorization from the POS system. This is the level just above the sales item.

    Field name: Sub group description

    Type: Attribute

    44

    Tabowner

    Operator ID of the person who entered the record.

    Field name: Tab owner code

    Type: Attribute

    45

    TabOwnerDesc

    The name of operator who entered the record. Separate their firstname and surname with a space. For example:

    • "Maria Rossi"

    Field name: Tab owner description

    Type: Attribute

    46

    OriginalTabOwner

    Operator ID of the person who opened the tab.

    Field name: Original tab owner code

    Type: Attribute

    47

    OriginalTabOwnerDesc

    The name of operator who opened the tab. Separate their firstname and surname with a space.

    Field name: Original tab owner description 

    Type: Attribute

    48

    OldTableCode

    RESERVED FOR FUTURE USE.

    Old tab ID. For use when items are transferred from one tab to another.

    Field name: Old tab code

    Type: Attribute

    49

    PrevTransactionCode

    RESERVED FOR FUTURE USE.

    Old check code. For use when items are transferred from one check to another.

    Field name: Previous transaction code

    Type: Attribute

    50

    AuthorisedBy

    RESERVED FOR FUTURE USE.

    Person who authorized a discount, if applicable.

    Field name: Authorised by

    Type: Attribute

    51

    TextField

    RESERVED FOR FUTURE USE.

    Free text field, with a limit of 250 characters.

    Field name: Text field

    Type: Attribute

    52

    GuestDesc

    RESERVED FOR FUTURE USE.

    The booking party name.

    Field name: Guest description

    Type: Attribute

    53

    GuestCode

    RESERVED FOR FUTURE USE.

    Reserved for possible uses such as SUV codes or hotel room numbers.

    Field name: Guest code

    Type: Attribute

    54

    TimeSentToPrep

    RESERVED FOR FUTURE USE.

    A number ("timefact") that shows when items are sent to the kitchen. This is the number or seconds since midnight; for example, 7:30PM would be:

    • "70200"

    Field name: Time sent to prep

    Type: Fact (INT)

    55

    BumpTime

    RESERVED FOR FUTURE USE.

    A number ("timefact") that shows when items were sent or taken to the customer. This is the number or seconds since midnight; for example, 7:47PM would be:

    • "71220"

    Field name: Time sent to customer

    Type: Fact (INT)

    56

    UniversalTimeSlotId

    Time slots in 15 minute increments. Leave empty, as Fourth populates this field.

    Field name: Universal time slot ID

    Type: Attribute

    57

    TimeSlotDesc

    RESERVED FOR FUTURE USE.

    Customer-defined time slot. For example:

    • "12:00-12:59"
    • "Lunchtime"

    Field name: Time slot description

    Type: Attribute

    58

    TransactionStartEnd

    Flag that indicates whether this is the first or last record for a transaction (check). The values are:

    • "1" — first record
    • "2" — last record

    Field name: Transaction start and end flag 

    Type: Attribute

    59

    IsDeleted

    RESERVED FOR FUTURE USE.

    (Default set to false.)

    Field name: Is Deleted flag

    Type: Attribute

    60

    CustomField1

    RESERVED FOR FUTURE USE.

    Field name: Custom field 1

    Type: Attribute

    61

    CustomField2

    RESERVED FOR FUTURE USE.

    Field name: Custom field 2

    Type: Attribute

    62

    CustomField3

    RESERVED FOR FUTURE USE.

    Field name: Custom field 3

    Type: Attribute

    63

    CustomFact1

     

    RESERVED FOR FUTURE USE.

    Field name: Custom fact 1

    Type: Fact (INT)

    64

    CustomFact2

     

    RESERVED FOR FUTURE USE.

    Field name: Custom fact 2

    Type: Fact (INT)

    65

    DateFact

     

    Numeric trading-date reference. Leave empty, as Fourth populates this field.

    Field name: Date fact

    Type: Fact (INT)

    How Fourth uses the data

    Once your POS data is delivered to the POS Gateway, Fourth creates individual exports that are forwarded to the different parts of the Fourth Platform that use POS data. These are:

    • Labor Productivity, for use in demand forecasts.
    • Purchasing to Pay and Inventory, for recording the movement of inventory.
    • Analytics, for use in business intelligence reports.

    Each Fourth module uses POS sales data in different ways, and so the exports are tailored to each module. For example, Inventory needs a daily aggregate, while Labor Productivity needs 15 minute intervals, and will also map the POS sales categories to its own. However, the same value for total daily net sales is sent to all Fourth modules.

    How the daily net sales is computed

    Fourth determines the daily net sum by taking the price_paid minus tax, for the following transaction types:

    • SALES_ITEM
    • MODIFIER_ITEM
    • VOID_ITEM
    • VOID_ERROR
    • VOID_WASTE

    This is why it is important that in your dataset:

    • The price_paid already includes any discounts applied to the item (or check).
    • That the tax value is for the price_paid and not the list_price.

    Quantity metrics sent to Fourth modules

    The individual exports forwarded to the Fourth modules will have quantity values that may vary from one another. This is because each module requires different metrics. For example, the export for demand forecasting must include the total number of items prepared and, depending on the Fourth customer's configuration, may include or exclude voided item quantities. Meanwhile, the Inventory export must include voided items (VOID_WASTE) so as to have accurate data about the items used.

    Demand forecasting export

    To create this export, Fourth extracts the quantity of times prepared and the net sales associated, by:

    • location
    • item
    • category
    • 15 minute time slot

    The data is mapped to the three main categories defined in the POS system (e.g. the values of the Majorgroupdesc field). This export relies on the sub-category values (major, family and sub) matching the values that already exist and are maintained by Fourth and the client. If you need to introduce a new group, then you must notify Fourth, so that we can adjust the mapping. Otherwise, any new category or group is ignored from the total net sales calculation and from labor forecasting.

    As well, the labor forecast only uses mains menu items to predict the number of staff needed. The forecast ignores modifiers to mains (for example, added cheese) as this doesn't represent additional work. It also does not count mains that became VOID_ITEM and VOID_ERROR items, as no work was done.

    Normally, the categorization settings for a sales item are maintained by Fourth in collaboration with the client. This includes settings such as whether a transaction type (e.g. VOID_ITEM) is applicable for an item. If, for any reason, the categorization is changed at the POS end, you must notify Fourth so that we can update the configuration.

    Inventory export

    The Inventory export compiles the following data for every location, date and PLU:

    • Quantity of items sold
    • Total net sales
    • Total tax
    • Net price paid
    • Total gross sales
    • Sales type (based on the transaction type)

    Analytics export

    The Analytics export contains the raw POS sales data, which is used to create business intelligence reports.

    Example scenarios

    Example one: simple

    Three customers arrive the restaurant.

    Action Transaction type
    Customers order food and drinks. SALES_ITEM
    Server prints the bill to pass to the customers. PRINT_CHECK
    Two customers pay by card. TENDER
    One customer pays cash. TENDER

    Example two: multiple courses

    Ten customers arrive at the restaurant and order starters and mains.

    Action Transaction type
    Customers order starters and mains. SALES_ITEM
    One customer asks for their main to not include tomato. MODIFIER_ITEM
    Server sees that the customers have finished their starters. MAINS_AWAY
    Server prints the bill to pass to the customers. PRINT_CHECK
    Service charge is added to the bill. SERVICE_CHARGE
    All ten customers pay by card. TENDER

    Example three: voided items

    Three customers decide to dine at Fawlty Towers.

    Action Transaction type
    Customers order drinks and mains (3 pizzas). SALES_ITEM
    Server accidentally enters a 4th pizza. They remove this from the order. VOID_ERROR

    Server accidentally opens the wrong beer. They return the item to stock.

    VOID_ITEM
    Server drops a pizza. They void the dropped pizza. VOID_WASTE
    All customers pay by card. TENDER

    Example four: discounts

    Three customers arrive, ready to use some coupons.

    Action Transaction type
    Customers order drinks and mains. SALES_ITEM
    Customer A has a voucher for 50% off the price of their main only. DISC_ITEM

    Customer B has a voucher for $2 off the price of their main only.

    DISC_ITEM
    All customers pay by card. TENDER

    Example five: Group discount

    Three customers arrive with one coupon for all meals.

    Action Transaction type
    Customers order drinks and mains. SALES_ITEM
    Customer A has a voucher that entitles the group to 50% off all food on the bill. DISC_ITEM
    All customers pay by cash. TENDER