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
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.

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. 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 Y Y Y Y Y Y Y Y Y Y Y Y
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
 

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

Field name: Unit ID

Type: Attribute

3 SiteLocationCode

Customer or POS stock location code.

Leave this field blank if you do not have these types of codes.

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.

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

The ListPrice value, converted into the businesses' main currency.

Use the same value if the local and main currency for the business is the same.

Field name: List price (converted)

Type: Fact

34

TaxConv

The Tax value, converted into the businesses' main currency.

Use the same value if the local and main currency for the business is the same.

Field name: Tax (converted)

Type: Fact

35

PricePaidConv

The PricePaid value, converted into the businesses' main currency.

Use the same value if the local and main currency for the business is the same.

Field name: Price paid (converted)

Type: Fact

36

DeductionConv

The Deduction value, converted into the businesses' main currency.

Use the same value if the local and main currency for the business is the same.

Field name: Deduction (converted)

Type: Fact

37

TenderAmountConv

The TenderAmount value, converted into the businesses' main currency.

Use the same value if the local and main currency for the business is the same.

Field name: Tender amount (converted)

Type: Fact

38

CostPriceTheoConv

The CostPriceTheo value, converted into the businesses' main currency. Use the same value if the local and main currency for the business is the same.

Do not use this field unless otherwise directed by Fourth or the mutual customer.

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 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 Record
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 Record
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 Record
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 Record
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 Record
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