Adaco Sales Item API Guide & Reference

Introduction

This API retrieves sales items within a Fourth Adaco outlet for display on a POS or other system. You can get:

  • All retail items or menu items for an outlet
  • Details of an individual item in a property, identified by its PLU
  • IDs for Adaco properties (locations) and outlets (sites)

Quick Facts

Integration type HTTP REST with JSON
Authentication Basic authentication
Availability Purchase to Pay and Inventory - Hotel customers
Testing Test environment is available on request
More information N/A

Get Access

Before integrating, you’ll need a new user account set up in Fourth with access rights to the API.

Step 1: create a user group 

Create a user group for accessing the API within one of the Fourth properties — we recommend the central purchasing property where there is one. 

For security, we also recommend that you limit the user group to access to just the “Sales Item API”. The setting for this is within the user group's Property > API Access sub-section.

Screenshot showing settings location

Step 2: create a user account

In the same property, create a user account. Assign it to the API user group. When saving the new user account we recommend that the system-generated password is ignored, as this will not be used for accessing the application.

Step 3: Get the API key

Right click on the user account and select the option “Reset API Key”.  When confirmed this will display a randomly-generated 40 character API key. Copy and provide this value, as well as the property number in which you created the user account, to whoever is accessing to the API.

Adaco Users screenshot, showing the Reset API Key option

Request header

For all requests, you must include Basic authentication in the header.

Example header:

GET //Locations/{Location Number}/Sites HTTP/1.1
Host: instance.example.com
Authorization: Basic MTI6NW1SVWMyejRJSEc4MjJUa0FiWXNQWHV4cllselhYeFFSbE8yaXBUdg==
Accept: application/json
Field Description
Authorization

The property number and the API key, separated by a colon, and then base64 encoded. The values are case-sensitive. For example, if the property number is 12, and the API key is 5mRUc2z4IHG822TkAbYsPXuxrYlzXXxQRlO2ipTv, then you need to create the string:

12:5mRUc2z4IHG822TkAbYsPXuxrYlzXXxQRlO2ipTv

Then base64 encode this. The result is:

MTI6NW1SVWMyejRJSEc4MjJUa0FiWXNQWHV4cllselhYeFFSbE8yaXBUdg==

Accept The data format for the response. Options are: application/json, text/json.

Resources

Fourth will provide you with the base path for requests. Each resource exposes a single GET method. Some of the resources do have query parameters for filtering requests. 

Resource name Description
Locations The Locations resource returns all properties within the Adaco instance.
Note: Locations are synonymous with Adaco properties.
Locations/{Location Number}/Sites The Sites resource returns all outlets within the specified property.
Note: Sites are synonymous with Adaco Outlets.
Locations/{Location Number}/Sites/{Site Number}/RetailItems

The RetailItems resource returns retail products listed in the order guide of the specified Adaco outlet. 

You can retrieve the full details for each sales item, including up to 15 customizable fields that you can use to record information specific to your POS system.

Only products which are assigned a PLU are returned.

Locations/{Location Number}/Sites/{Site Number}/MenuItems

The MenuItems resource returns recipes listed in the order guide of the specified Adaco outlet. 

You can retrieve the full details for each sales item, including up to 15 customizable fields that you can use to record information specific to your POS system.

Only recipes which are assigned a PLU are returned.

Locations/{Location Number}/PLU/{PLU} The PLU resource returns the details of any sales item with the PLU number, including the order quantities in outlets which list the item.
 
As a single PLU could be assigned to different items in different outlets this resource can return a collection of items.

Filtering RetailItems and MenuItems results

You can filter results from the RetailItems and MenuItems resources using query parameters. 

Query parameter Description
date

Returns only records created or modified since the specified date. The format you must use is dd/MM/yyyy. For example, New Year's Eve is: 31/12/2018

nutrition

Specifies that you want the full nutritional values for the menu item. This parameter does not require a value.

To add nutrition data in the response, Fourth needs to perform additional processing. This can slow response times, so we recommend only including this parameter if your use case requires it (rather than by default).

This query parameter works with MenuItems requests only. 

full

Specifies that you want three additional fields included in the response: costPrice, onOrder, and retailAttributes. This parameter does not require a value. 

To add this data in the response, Fourth needs to perform additional processing. This can significantly slow the response time, so we recommend only including this parameter if your use case requires it. 

For example, to include the nutrition information for your menu items:

GET <ROOT>/Locations/1/Sites/1/MenuItems?nutrition

To include the sales-related data for retail items:

GET <ROOT>/Locations/1/Sites/1/retailItems?full

To retrieve only retail items created or modified since 2018:

GET <ROOT>/Locations/1/Sites/1/retailItems?date=01/01/2018

To include all nutrition and sales-related data for menu items, created or modified since April 2018:

GET <ROOT>/Locations/1/Sites/1/MenuItems?full&nutrition&date=01/04/2018

Response to requests

Successful requests

Successful GET requests receive an HTTP 200 OK response with the data requested in the response body. 

Unsuccessful requests

Requests with invalid credentials will receive an HTTP 403 Prohibited response, while requests to the wrong URL will receive an HTTP 404 Not Found response.

Making Locations requests

To get a list of your Adaco properties, use the request: 

GET <ROOT>/Locations

Response body

If your request is accepted then Fourth sends an HTTP 200 OK response with an array of properties. 

[
{
   "Description": "Hotel Deluxe",
   "LocationId": 1
},
{
   "Description": "Hotel Klasy Średniej",
   "LocationId": 2
},
{
   "Description": "Hotel Barato",
   "LocationId": 3
}
]
Member Type Description

Description

string

The name of the Adaco property.  E.g. “Hotel Deluxe”

LocationId

number

The number of the Adaco property E.g. 2

Making Site requests

To get a list of your Adaco outlets for a property (in this example, "1"), use the request: 

GET <ROOT>/Locations/1/Sites

Response body

If your request is accepted then Fourth sends an HTTP 200 OK response with an array of sites for the specified property. 

[
{
   "RevenueCenter": "1|1, 1|2, 1|99, 1|10",
   "SiteId": 1, 
   "SiteName": "PIZZERIA ITALIANO"
},
{
   "RevenueCenter": "2|1, 2|2, 2|99",
   "SiteId": 2, 
   "SiteName": "L 'ESCARGOT BRASSERIE"
},
{
   "RevenueCenter": "3|1, 3|2",
   "SiteId": 3, 
   "SiteName": "GOLF SHOP"
}
]
Member Type Description
SiteName  string

The name of the Adaco Outlet E.g “All Day Dining Restaurant”

SiteId  number

The number of the Adaco outlet E.g. 200

RevenueCenter string

A comma separated list of any POS revenue centers associated with the Adaco outlet

Making RetailItems requests

To get a list of retail items for a specific Adaco outlet (in this example, at property "1" and outlet "20"), use the request: 

GET <ROOT>/Locations/1/Sites/20/retailItems

Response body

If your request is accepted then Fourth sends an HTTP 200 OK response with an array of retail items for the specified outlet.

[
{
   "Allergen": [],
   "BarCodes": 
   [
   {
      "BarCode": "000039804",
      "Symbology": "CODE39"
   },
   {
      "BarCode": "0000398041",
      "Symbology": "CODE39"
   },
   {
      "BarCode": "0398040001010",
      "Symbology": "EAN13"
   }
   ],
   "BinNumber": null,
   "Brand": null,
   "CategoryName": "BEVRAGES - SOFT",
   "CategoryNumber": 1200013,
   "CostPrice": 315,
   "CreatedDate": "09-02-2016 12:53:47 GMT-05:00",
   "Description": "7UP CAN 150ML ",
   "DetailNumber": 1,
   "DietaryGuidelines": [],
   "Intolerance": [],
   "LanguageDescriptions":
   [
   {
      "Name": "fr-FR",
      "Value": "7UP CAN 150ML "
   }
   ],
   "ModifiedDate": "09-01-2018 13:19:50 GMT-05:00",
   "OnOrder": 0,
   "PLU": "4532x",
   "POSFields": 
   [
   {
      "Name": "ServiceCharge",
      "Value": "RC3"
   },
   {
      "Name": "MenuGroup",
      "Value": "2"
   },
   {
      "Name": "WeightedItem",
      "Value": "Y"
   },
   {
      "Name": "LabelText",
      "Value": "SS"
   },
   {
      "Name": "Tax",
      "Value": "10"
   }
   ],
   "ParStock": -0.03333333333333333,
   "Price": 0,
   "ProductNumber": 39804,
   "ReOrder": 0,
   "RetailAttributes": "",
   "SKU": null,
   "SegmentName": "Food and Bev",
   "SegmentNumber": 26,
   "SellingPrice": 12.5,
   "SellingUnit": "CA",
   "SellingWeight": 0,
   "ShortDescription": "7UP CAN 15",
   "StockQuantity": 0,
   "SubCategoryName": "CANS & BOTTLES",
   "SubCategoryNumber": 1
},
{
   "Allergen": [],
   "BarCodes": 
   [
   {
      "BarCode": "000039809",
      "Symbology": "CODE39"
   }
   ],
   "BinNumber": "123",
   "Brand": null,
   "CategoryName": "BEVRAGES - SOFT",
   "CategoryNumber": 1200013,
   "CostPrice": 10,
   "CreatedDate": "09-02-2016 12:53:47 GMT-05:00",
   "Description": "7UP CAN 300ML ",
   "DetailNumber": 1,
   "DietaryGuidelines": [],
   "Intolerance": [],
   "LanguageDescriptions": 
   [
   {
      "Name": "fr-FR",
      "Value": "7UP CAN 300ML "
   }
   ],
   "ModifiedDate": "27-03-2018 03:18:24 GMT-04:00",
   "OnOrder": 0,
   "PLU": "0398090102",
   "POSFields": 
   [
   {
      "Name": "ServiceCharge",
      "Value": "0"
   },
   {
      "Name": "MenuGroup",
      "Value": "2"
   },
   {
      "Name": "WeightedItem",
      "Value": "N"
   },
   {
      "Name": "LabelText",
      "Value": "10"
   },
   {
      "Name": "Tax",
      "Value": "10"
   }
   ],
   "ParStock": -1,
   "Price": 0,
   "ProductNumber": 39809,
   "ReOrder": 0,
   "RetailAttributes": "",
   "SKU": null,
   "SegmentName": "Food and Bev",
   "SegmentNumber": 26,
   "SellingPrice": 2.5,
   "SellingUnit": "CN",
   "SellingWeight": 0,
   "ShortDescription": "LEMONADE",
   "StockQuantity": 0,
   "SubCategoryName": "CANS & BOTTLES",
   "SubCategoryNumber": 1
}
]
Member Type Description

PLU

String

The PLU is typically the code assigned to the item within the POS system.  The PLU is the primary key for the RetailItems collection. A single Product detail in Adaco can have 4 different PLUs; one assigned to each of the possible selling units.  If more than one PLU is assigned to a single product detail a separate record for each PLU will be returned

Description

String

The full description of the product as defined in the Adaco product master. E.g. “Cloudy Bay Chardonnay”

SellingPrice

Decimal

The selling price of the PLU / Item E.g. $25.00

CostPrice

(optional)

Decimal

The weighted average inventory cost of the item expressed in the selling unit; e.g. $12.50. This value is specific to each Site (Adaco outlet).

If you want this field in the response, you must include the full query parameter in your request.

SellingUnit

String

The unit of measure code of the sales unit. For example: EA, BX, BO.
See the Units of Measure table.

SegmentNumber

Number

The number of the segment to which the item is assigned.  Note in Adaco items are assigned to a 3 tier classification:  A segment contains one or more Categories which contains one or more Sub-Categories.

SegmentName

String

The name of the segment to which the item is assigned.  E.g. “Beverages”

CategoryNumber

Number

The number of the Category to which the item is assigned.

CategoryName

String

The name of the Category to which the item is assigned E.g. “Wines”

SubCategoryNumber

Number

The number of the Sub-Category to which the item is assigned

SubCategoryName

String

The name of the Sub-Category to which the item is assigned E.g. “White Wines”

RetailAttributes

(optional)

Collection

Customer defined retail attributes.  These are returned as a collection of Name : Value pairs.  E.g. Size : Large, Colour : Blue. Note in Adaco versions prior to 4.6.63 this field is returned as a single concatenated string value.  

If you want this field in the response, you must include the full query parameter in your request.

Allergen

Collection

A collection of string values representing the Allergens which are assigned to the product.  E.g. “Crustaceans”, “Barley”, “Peanuts”

DietaryGuidelines

Collection

A collection of string values representing the Dietary Guidelines which are assigned to the product.  E.g. “Pork”, “Alcohol”

Intolerances

Collection

A collection of string values representing the Intolerances which are assigned to the product.  E.g. “Gluten”, “Lactose”, “Yeast”

Brand

String

E.g. Heinz

BinNumber

String

A customer assigned bin number. E.g. 123

POSFields

Collection

Customer defined custom fields specifically required by the 3rd party system. These are returned as a collection of Name : Value pairs. E.g.:

{ “Meal Period” : “Lunch” },
{ “Preparation Time” : “20 mins” }

SKU

String

A customer defined identifier for the item

BarCode

Collection

Each item can be assigned zero or more bar codes.  These are returned as a collection of pairs including the Bar Code Symbology and the Bar Code Value. E.g. EAN13, 123456789018

StockQuantity

Decimal

The quantity of the item on hand within the specified outlet expressed in the selling unit.  E.g. 12.5

OnOrder

(optional)

Decimal

The quantity of the item on order expressed in the selling unit.  On order quantity will include outstanding internal requisitions or outstanding purchase orders.  

If you want this field in the response, you must include the full query parameter in your request.

Price

Decimal

The location level inventory cost of the item.  This is location wide and not site specific

ParStock

Decimal

The optimal stock holding quantity of the item

ReOrder

Decimal

The minimum stock holding quantity for the item at which additional stock should be ordered

ShortDescription

String

An alternative description for the item which may be more appropriate for inclusion on a customer facing POS receipt.  E.g. “House White”

ProductNumber

Number

The Adaco product number

DetailNumber

Number

The Adaco Product Detail Number. Note that each product in Adaco can have multiple product details assigned for different purchase unit configurations.

LanguageDescription

Collection

A collection of name : value pairs including the culture code and language description for an item (an item can have multiple language descriptions). For example:

LanguageDescriptions":[{
   "Name":"fr-FR",
   "Value":"Vin Blanc"}]

CreatedDate

DateTime

The date and time that the product or product detail was created expressed in UTC.

ModifiedDate

DateTime

The date and time that the product or product detail was last modified expressed in UTC.

Making MenuItem requests

To get a list of menu items for a specific Adaco outlet (in this example, at property "1" and outlet "20"), use the request: 

GET <ROOT>/Locations/1/Sites/20/MenuItems

Response body

If your request is accepted then Fourth sends an HTTP 200 OK response with an array of menu items for the specified outlet.

[
{
   "Allergen": [],
   "BarCodes": [],
   "Categories": [],
   "CostPrice": 11.42,
   "CreatedDate": "03-04-2017 08:13:00 GMT-04:00",
   "CriticalDetails": "",
   "Description": "SMOKED SALMON SANDWICH",
   "DietaryGuidelines": [],
   "Intolerance": [],
   "LanguageDescriptions": 
   [
   {
      "Name": "en-GB",
      "Value": "SMOKED SALMON SANDWICH"
   },
   {
      "Name": "is-IS",
      "Value": "SMOKED SALMON SANDWICH"
   }
   ],
   "Method": "",
   "MicrobiologicalStatement": "",
   "ModifiedDate": "12-03-2018 09:31:00 GMT-04:00",
   "Nutrition": [],
   "OnOrder": 0,
   "PLU": "445566",
   "POSFields": 
   [
   {
      "Name": "ServiceCharge",
      "Value": "RC004"
   },
   {
      "Name": "MenuGroup",
      "Value": "1"
   },
   {
      "Name": "WeightedItem",
      "Value": "Y"
   },
   {
      "Name": "LabelText",
      "Value": "SMOKED SALMON SANDWICH"
   },
   {
      "Name": "Tax",
      "Value": "10"
   }
   ],
   "ParStock": -1,
   "PreparedSize": "10.000DZ",
   "Price": 11.42,
   "ReOrder": 0,
   "RecipeNumber": 519383,
   "SellingPrice": 12.95,
   "SellingUnit": "1.000EA",
   "ServingSuggestions": "",
   "ShortDescription": "",
   "StockQuantity": 0,
   "UsageType": "Recipe"
},
{
   "Allergen": [],
   "BarCodes": [],
   "Categories": [],
   "CostPrice": 0,
   "CreatedDate": "16-02-2007 00:00:00 GMT-05:00",
   "CriticalDetails": "",
   "Description": "PIZZA PESTO SB 2009",
   "DietaryGuidelines": [],
   "Intolerance": [],
   "LanguageDescriptions": 
   [
   {
      "Name": "en-GB",
      "Value": "PIZZA PESTO SB 2009"
   }
   ],
   "Method": "",
   "MicrobiologicalStatement": "",
   "ModifiedDate": "13-12-2017 05:08:00 GMT-05:00",
   "Nutrition": [],
   "OnOrder": 0,
   "PLU": "501671",
   "POSFields": 
   [
   {
      "Name": "ServiceCharge",
      "Value": "RC004"
   },
   {
      "Name": "MenuGroup",
      "Value": "2"
   },
   {
      "Name": "WeightedItem",
      "Value": "Y"
   },
   {
      "Name": "LabelText",
      "Value": "PIZZA PESTO SB 2009"
   },
   {
      "Name": "Tax",
      "Value": "10"
   }
   ],
   "ParStock": -1,
   "PreparedSize": "1.000EA",
   "Price": 0,
   "ReOrder": 0,
   "RecipeNumber": 501671,
   "SellingPrice": 9.52,
   "SellingUnit": "1.000EA",
   "ServingSuggestions": "",
   "ShortDescription": "",
   "StockQuantity": 0,
   "UsageType": "Recipe"
}
]
Member Type Description

PLU

String

The PLU is typically the code assigned to the item within the POS system.  The PLU is the primary key for the MenuItems collection.

Description

String

The full name of the Adaco Recipe E.g. “Cheese and Tomato Pizza”

SellingPrice

Decimal

The selling price of the item.  Note the selling price can be specific for the site or where there is no site specific selling price the default selling price is returned.  E.g. $12.95

CostPrice

Decimal

The recipe Cost per Serving is the average across all sites. Where a recipe contains an inactive or uncosted ingredient the CostPrice returned could be null

PreparedSize

String

The prepared quantity and unit for the recipe.  E.g. 12 kg

SellingUnit

String

The portion size of the item  E.g. 200g

SegmentNumber

Number

The number of the segment to which the item is assigned.  Note in Adaco items are assigned to a 3 tier classification:  A segment contains one or more Categories which contains one or more Sub-Categories.

SegmentName

String

The name of the segment to which the item is assigned.  E.g. “Beverages”

CategoryNumber

Number

The number of the Category to which the item is assigned.

CategoryName

String

The name of the Category to which the item is assigned E.g. “Wines”

SubCategoryNumber

Number

The number of the Sub-Category to which the item is assigned

SubCategoryName

String

The name of the Sub-Category to which the item is assigned E.g. “White Wines”

Allergen

Collection

A collection of string values representing the Allergens which are assigned to the product.  E.g. “Crustaceans”, “Barley”, “Peanuts”

DietaryGuidelines

Collection

A collection of string values representing the Dietary Guidelines which are assigned to the product.  E.g. “Pork”, “Alcohol”

Intolerances

Collection

A collection of string values representing the Intolerances which are assigned to the product.  E.g. “Gluten”, “Lactose”, “Yeast”

Nutrition

(optional)

Collection

A collection of Name : Value pairs which will contain the name of each nutrient and the value of the nutrient present in the item. For example:

{  "Name" : "Calories",
   "Value": 156.25 },
{  "Name" : "Saturated Fat",
   "Value": 123.5 }

Note: This field is optional and will only be populated if you include the nutrition query parameter in your request.

POSFields

Collection

Customer defined custom fields specifically required by the 3rd party system. These are returned as a collection of Name : Value pairs. For example:

{  "Meal Period" : "Lunch"  },
{  "Preparation Time" : "20 mins"  }

RecipeNumber

Number

The Adaco recipe number.

Method

String

A Plain Text field with RTF tags removed

ServingSuggestions

String

A Plain Text field with RTF tags removed

CriticalDetails

String

A Plain Text field with RTF tags removed

MicrobiologicalStatement

String

A Plain Text field with RTF tags removed

UsageType

String

Used As Recipe, Add-On, Menu etc

BarCode

Collection

Each item can be assigned zero or more bar codes.  These are returned as a collection of pairs including the Bar Code Symbology and the Bar Code Value. E.g. EAN13, 123456789018

StockQuantity

Decimal

The stock on hand for the item within the specified site expressed in selling units

OnOrder

Decimal

The quantity of the item on finally approved but not yet issued internal requisitions expressed in selling units

Price

Decimal

The location level inventory cost of the item.  This is location wide and not site specific

ParStock

Decimal

The optimal stock holding quantity of the item

ReOrder

Decimal

The minimum stock holding quantity for the item at which additional stock should be ordered

ShortDescription

String

An alternative description for the item which may be more appropriate for inclusion on a customer facing POS receipt.  E.g. “Tomato Pizza”

Language Description

Collection

A collection of name : value pairs including the culture code and language description for an item (an item can have multiple language descriptions).  For example:

"LanguageDescriptions":[{
   "Name":"it-IT",
   "Value":"Pizza Margherita"}]

CreatedDate

DateTime 

The date and time that the product or product detail was created expressed in UTC.

ModifiedDate

DateTime

The date and time that the product or product detail was last modified expressed in UTC.

Making PLU requests

To get a list of sales items using the specified PLU for a property (in this example, property "1"), use the request: 

GET <ROOT>/Locations/1/PLU/15620

Response body

If your request is accepted then Fourth sends an HTTP 200 OK response with an array of sames items by PLU for the specified property.

[
{
   "AdacoItemNumber": "39809-1",
   "ItemType": "Product",
   "Outlets": 
   [
   {
      "CostPrice": 1.25,
      "InventoryOnHand": 126 ,
      "OnOrder": 36,
      "OutletName": "PIZZERIA ITALIANO",
      "OutletNumber": 1,
      "SellingPrice": 2.5
   },
   {
      "CostPrice": 1.26,
      "InventoryOnHand": 11,
      "OnOrder": 24,
      "OutletName": "L'ESCARGOT BRASSERIE",
      "OutletNumber": 2,
      "SellingPrice": 2.5
   },
   {
      "CostPrice": 1.25,
      "InventoryOnHand": 17,
      "OnOrder": 0,
      "OutletName": "GOLF SHOP",
      "OutletNumber": 3,
      "SellingPrice": 2.5
   }
   ],
   "PLU": "0398090102",
   "PLUDescription": "7UP CAN 300ML ",
   "PLUShortDescription": "LEMONADE",
   "Status": "Active",
   "Unit": "Can"
}
]
Member Type Description

AdacoItemNumber

String

Either the Adaco product number or the Adaco recipe number.  For products the product number will be appended with the product detail number (separated by a hyphen, e.g. 123-1)

ItemType

String

Will return either Product or Recipe according to the Adaco item to which the PLU is assigned

PLU

String

The PLU which is submitted in the request

PLUDescription

String

The name of the retail product or recipe against which the PLU is assigned

PLUShortDescription

String

An optional second, abbreviated name for the item (typically the name which is exposed to and used by the POS system)

Status

String

Will be either “Active” or “Inactive”

Unit

String

The unit of measure to which the PLU is assigned e.g. “Each”

Outlets

Collection

A collection containing each outlet where the returned item is listed in the inventory guide

Outlets.OutletNumber

Integer

The number of the Adaco outlet

Outlets.OutletName

String

The name of the Adaco outlet

Outlets.CostPrice

Number

The cost of the item in the specified outlet

Outlets.SellingPrice

Number

The designated selling price for the item within the specified outlet (recipes can be sold at different prices in different outlets)

Outlets.InventoryOnHand

Number

The current on hand inventory of the item within the specified outlet

Outlets.OnOrder

Number

The number of units on order for the specified outlet