Recipe & Menu Engineering Export API Guide

Introduction

With the Recipe & Menu Engineering Export API, you can access the recipe, ingredient and supplier data in Fourth for use on POS, stock and other systems.

Quick Facts

API type HTTP REST with JSON and XML
Authentication Basic authentication
Availability All customers using our Fourth Inventory for Restaurants solution
Testing A test environment is available
More information See the Export API Reference

Get access

To get started with this API, you will need:

  • A Recipe & Menu Engineering Export API account to access this API
  • The root URL for requests to both test and live environments

Your mutual Fourth customer must request credentials on your behalf. Please ensure they do this as soon as possible. The Fourth Professional Services team member managing the integration can provide the above information and help you with any integration questions you may have.

Unique identifiers 

Each item or data concept available through this API — like ingredients, intolerances, or categories — has a unique identifier (GUID). In responses, the JSON property (or XML element) with the GUID is always appended with “Guid”; for example: 

  • IngredientGuid
  • IntoleranceGuid
  • CategoryGuid

Many of the resources have an option to include the GUID as a path parameter, so that you can get the details of a specific item. 

Category types

The Fourth Inventory for Restaurants solution has a hierarchy of user-defined categories. In responses in this API, the hierarchy is:

  1. Category Type
  2. Main Category
  3. SubCategory
  4. SubCategory
  5. SubCategory

In the API responses that include category information, you will see nested SubCategories to represent the above.

For Main Categories, the API will include a flag to indicate whether it is a “smart” or “system” category. Smart categories align with categories in Fourth Inventory. Items can have multiple system categories, but typically have only one smart category. 

Groups

Groups (also called admin groups) are used to silo business units and data in Fourth. Groups enable customers to restrict access to data — such as menus or recipes — to user groups. For example, if there are separate brands run independently from one another (that require separate data) then these will be groups inside a parent group.

Each customer will have one or more API user groups set up by Fourth. This defines the data areas that users can access with the API. If you find requests to the API return blank results, it is likely that the API user group does not have permission to access the data.

Resources that are relevant to groups are:

  • admingroups and groups — returns the hierarchy and details of the groups
  • ingredients/{}/groups, menus/{}/groups, and recipes/{}/groups — for each ingredient, menu or recipe, this returns the groups that have access to that item. 

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.

Resources Description

category/Ingredient

category/Menu

category/Recipe

Returns the category information and hierarchy for either ingredients, menus or recipes. This includes whether a Main category is a “smart” or “system” category.

Useful for: Stock and warehousing systems; finance reporting.

admingroups

groups

Returns the business’s group hierarchy.

The groups resource returns just the group names and GUIDs with implied hierarchy.

The admingroups resource returns more explicitly described hierarchy as well as details such as the UOM standard, language and currency for the group.

ingredients

ingredients/{guid}

Returns details about all ingredients or a specified ingredient (if you include a GUID). The data returned includes wastage, portions, whether it is sellable, unit sizes, and supplied pack sizes (with supplier details, category and costs).

It does not include the nutrition or intolerance data for the ingredient, nor any images.

Useful for: Stock and warehousing systems; finance reporting.

ingredients/{guid}/groups

Returns the groups that have access to an ingredient. For example, you could check that a luxury ingredient item was available only in luxury venues.

Useful for: Stock and warehousing systems; finance systems.

ingredients/{guid}/intolerances

Gets all the intolerances listed for an ingredient. This is structured to show the intolerance groups (e.g. nuts) and then the specific intolerance (e.g. hazelnuts).

ingredients/intolerancehistory

ingredients/{guid}/intolerancehistory

Returns the intolerance audit history for an ingredient (or all ingredients). The response returns the date, user, previous intolerance status, and new status. Only intolerances that have had a change occur are returned; if you need a full list of intolerances, use ingredients/{guid}/intolerances endpoint.

An example request is below.

ingredients/{guid}/nutrition

Gets all the nutrient data listed for an ingredient. The nutrient amount is calculated per 100 grams.

ingredients/{guid}/pictures

Returns all images for a specified ingredient.

Images are stored as base64 strings. The properties for each image will indicate whether it is the default image or not.

This is useful for ingredients that are hard to identify from written descriptions, including non-food items (like spoons or lightbulbs).

ingredients/{guid}/processdata

Returns the cooking instructions, ingredients, and other data for the ingredient. This is relevant for ingredients that are processed or manufactured in some way and in themselves have separate ingredients; for example, sausages.

ingredients/{guid}/supplierspec Returns the ingredient's specification, as from the supplier. This covers indepth information about the ingredient's packaging, delivery and other data.

intolerances

Returns the intolerances of all ingredients and recipes for the business. The returned list does not identify which ingredients or recipes include the intolerance.

menuguids

Returns only the high-level details (menu GUIDs, names, and sales tax status) of all menus. Use this request if you want to retrieve a list of menu GUIDs.

menus

menus/{guid}

Returns details about all menus or a specific menu (if you include a GUID). The data returned includes courses, recipes and categories; as well as finer details around wastage, tax, revenue and profitability.

It does not include the nutrition or intolerance data for recipes in the menu, nor any images.

Useful for: Printed and on-screen menus.

menus/{guid}/groups

Returns the groups that have access to a menu. For example, you could check that the ACME menus are only available to ACME-branded restaurants.

nutrients

Returns a generic list of nutrients from Fourth. It includes just the name and description for a nutrient. The data is not linked to any ingredients or recipes.

recipes/optimized
recipes/optimized/{guid}

Returns details about all recipes or a specific recipe (if you include a GUID). The data returned includes PLU, ingredients, menu description, preparation time, storage and shelf-life, price details, servings, weight, portions, and categories.  

It does not include the nutrition or intolerance data, nor any images.

To get recipe steps, use the Recipes/{guid}/preparation resource.

recipes

recipes/{guid}

Returns the same details as the optimized endpoints above. However, requests to these endpoints take longer to return than the optimized endpoints. We recommend all new and existing integrations use the optimized endpoints.

recipes/{guid}/groups

Returns the groups that have access to a recipe. For example, you could check that lobster recipes are only available to restaurants serving fish.

recipes/{guid}/intolerances

Gets all the intolerances listed for a recipe. This is structured to show the intolerance groups (e.g. nuts) and then the specific intolerance (e.g. hazelnuts).

/Recipes/intolerancehistory
/Recipes/{guid}/intolerancehistory

Returns the intolerance audit history for a recipe (or all recipes). The response returns the date, user, previous intolerance status, and new status. Only intolerances that have had a change occur are returned; if you need a full list of intolerances, use the recipes/{guid}/intolerances endpoint.

An example request is below.

recipes/{guid}/nutrition

Gets the nutrient values for an recipe. Both serving size and per 100 grams values are provided for each nutrient.

recipes/{guid}/pictures

Returns all images for a specified recipe. Images are stored as base64 strings. The properties for each image will indicate whether it is the default image or not.  

Useful for: Digital displays; kitchen screens.

recipes/{guid}/preparation

Returns recipe preparation steps. This includes full steps, mise en place, critical control points (CCP), service/presentation and any associated images.

An example response is below.

Useful for: Kitchen screens.

suppliers

Returns the name, description and website of the business' suppliers in Fourth. 

Useful for: Stock and warehousing systems and reporting. Another use case is adding vendor details to a retail website.

units

Returns a generic list of the units of measure (UOM) from Fourth.

Filtering menu, recipe and ingredient results 

You can filter results from the ingredients, menus and recipes resources using query parameters. You can find the available filters for each endpoint in the API Reference.

For example, this request will return only menus created from 2016 onwards: 

<ROOT>/Menus?createdAfter=2016-01-01

You can include multiple parameters in the request to filter results further. For example, imagine a major menu revision in April 2018 occurred to menus. You could look for menus that needed updating by comparing the previous results with the following: 

<ROOT>/Menus?createdAfter=2016-01-01&lastModifiedAfter=2018-04-01

This would provide a list of all the menus that were created after 2016, and had been revised after the start of April. You would just need to subtract these from your original list to find any menus that had not had updates in April.

scheduledExportAfter filter

In the Fourth UI, customers can set the Scheduled Export After field for menus, recipes and ingredients. This is an editable field that allows customers to add a date for their own custom use cases, and it is otherwise ignored from within Fourth. For example, it allows customers to set their own dates for filtering and reviewing records in an external reporting tool.

Specifying this parameter will return only records with a date on or after any set Scheduled Export After date. The default value for this field is the “created on” date. 

Displaying alternate and add-on items in a POS

For customers using Recipe & Menu Engineering standalone, there are additional options that may be useful for showing alternate and add-on items in the POS system. They need to initially be enabled in Fourth for the customer, after which the customer can create the recipe types.

Choice recipes

These recipes are used to manage alternatives within a main recipe. For example, the customer may have three potato options (chips, mashed, and sweet) that they offer diners for no additional charge. One of the choices will be the default choice — this recipe is included in the cost, nutrition, and intolerance values for the main recipe.

For the general-detail recipe endpoints:

  • /recipes
  • /recipes/{guid}
  • /recipes/optimized
  • /recipes/optimized/{guid}

The Type value identifies if it is a Choice recipe:

"RecipeGuid": "6c3fec7d-97c9-48f8-b84e-13bb179b9fa6",
"PLU": "PLUCode",
"StarChefKey": "00123567",
"Type": "Choice",
"Name": "mashed potato",

For the main recipe, the available choice recipes are listed in the response sent back for these endpoints:

  • /recipes
  • /recipes/{guid}
  • /recipes/optimized
  • /recipes/optimized/{guid}

The choice recipes are listed in the RecipeIngredients array. The default choice recipe will have a value of true for ChoiceDefault, while alternative recipes will be false. All other recipes and ingredients will have a null value for ChoiceDefault.

   "RecipeIngredients": [
      {
         "RecipeIngredientType": "Choice Recipe",
         "RecipeIngredientGuid": "10b9d9a1-d97c-4699-be97-fa57a8a3b779",
         "RecipeIngredientName": "Dauphinoise potatoes",
         "WastageRemoved": "",
         "ChoiceDefault": "false",
         ...
      }
   ]

Option recipes

Option recipes are used to manage add-ons to a main recipe that are normally charged. For example, a main recipe may allow for charged add-ons such as avocado or cheese.

For the general-detail recipe endpoints:

  • /recipes
  • /recipes/{guid}
  • /recipes/optimized
  • /recipes/optimized/{guid}

The Type value identifies if it is an Option recipe:

"RecipeGuid": "6c3fec7d-97c9-48f8-b84e-13bb179b9fa6",
"PLU": "PLUCode",
"StarChefKey": "00123567",
"Type": "Option",
"Name": "Goats Cheese",
...

For the main recipe, the available option recipes are listed in the response sent back for these endpoints:

  • /recipes
  • /recipes/{guid}
  • /recipes/optimized
  • /recipes/optimized/{guid}

The option recipes are listed in the RecipeIngredients array:

   "RecipeIngredients": [
      {
         "RecipeIngredientType": "Option Recipe",
         "RecipeIngredientGuid": "10ab9d91-dc97-9959-e9b7-648a3b537",
         "RecipeIngredientName": "Goats Cheese",
         "WastageRemoved": "",
         "ChoiceDefault": "",
         ...
      }
   ]

Understanding alternate and parent ingredients

For our customers, there is often a need to be able to purchase the same product from more than one supplier. To support this, Fourth has the concept of a parent ingredient, under which you can have multiple alternate ingredients. An alternate ingredient can have a different supplier, purchase quantity and cost price to the master product; but it always shares the same nutritional and intolerance properties. This means that in most cases the alternative ingredients are the same brand as the parent ingredient.

To support API users, our GET endpoints return the shared data — such as process data, nutrient and intolerance information — of the parent ingredient where necessary.

Request header

For all requests, you must provide your authentication details using Basic authentication in the header.

Example header:
GET /Recipes/12345/preparation  HTTP/1.1
Host: instance.example.com
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Field Description
Authorization

Your Recipes & Menu Engineering Export ID and password, separated by a colon, and then base64 encoded. Your ID and password are case-sensitive. 

Content-Type The data format you are using for POST request. Options are: application/json, text/json, application/xml, text/xml.

Response 

Successful requests

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

Unsuccessful requests

Unsuccessful requests receive an HTTP 400-599 response, with an error message in the response body. 

Example responses

Ingredient or recipe intolerance history request

This example applies to any of the /intolerancehistory endpoints. Note that the example does not include the recipe or ingredient specific XML elements that start and end the full response.

In the example, the following events occur:

  • Add: The value for Contains Molluscs changes from null to N (no).
  • Remove: The value for Contains Milk or Milk Products changes from Y (yes) to null.
  • Modify: The value for Contains Soya changes from M (may contain) to Y
    <Name>House Dressing</Name>
    <IntoleranceItems>
      <IntoleranceItem>
        <Name>Contains Molluscs</Name>
        <Events>
          <Event>
            <To>Y</To>
            <Id>22796</Id>
            <ChangeDate>2020-06-03T09:04:59.91</ChangeDate>
            <UserId>brad</UserId>
            <Action>Add</Action>
          </Event>
        </Events>
      </IntoleranceItem>
      <IntoleranceItem>
        <Name>Contains Milk or Milk Products</Name>
        <Events>
          <Event>
            <From>Y</From>
            <Id>22823</Id>
            <ChangeDate>2020-06-03T09:20:16.673</ChangeDate>
            <UserId>brad</UserId>
            <Action>Remove</Action>
          </Event>
      </IntoleranceItem>
      <IntoleranceItem>
        <Name>Contains Soya</Name>
        <Events>
          <Event>
            <From>M</From>
            <To>Y</To> 
            <Id>22823</Id>
            <ChangeDate>2020-06-03T10:03:23.125</ChangeDate>
            <UserId>brad</UserId>
            <Action>Modify</Action>
          </Event>
      </IntoleranceItem>
    </IntoleranceItems>

Recipe preparation request

The following shows the response to a recipe preparation request. Note that, for the <image> elements, the content is truncated to make this example simpler to read.  

<?xml version="1.0" encoding="utf-8"?>
<RecipePreparations>
   <RecipePreparation>
      <RecipeGuid>eb8c2bed-f8ed-4c3b-89b0-2034b3400f9f</RecipeGuid>
      <Name>Toast</Name>
      <Method>
         <ContentType>text/plain</ContentType>
         <MethodList>
            <Step>
               <Text>Toast bread in a toaster until brown but not burnt.</Text>
               <Image />
               <Order>1</Order>
            </Step>
            <Step>
               <Text>Add avocado and drizzle with oil.</Text>
               <Image />
               <Order>2</Order>
            </Step>
            <Step>
               <Text>Top with cherry tomatoes.  Lay the toast on a service plate and arrange a salad garnish to one side.</Text>
               <Image />
               <Order>3</Order>
            </Step>
            <Step>
               <Text>Drizzle the salad garnish with the dressing and serve immediately.</Text>
               <Image />
               <Order>4</Order>
            </Step>
         </MethodList>
      </Method>
      <MiseEnPlace>
         <ContentType>text/plain</ContentType>
         <MiseEnPlaceList>
            <Step>
               <Text>Slice bread and cherry tomatoes and store.</Text>
               <Image />
               <Order>1</Order>
            </Step>
            <Step>
               <Text>Prepare salad garnishes as per recipe.</Text>
               <Image />
               <Order>2</Order>
            </Step>
         </MiseEnPlaceList>
      </MiseEnPlace>
      <Ccp>
         <ContentType>text/plain</ContentType>
         <CcpList>
            <Step>
               <Text>Wash hands first</Text>
               <Image>...</Image>
               <Order>1</Order>
            </Step>
            <Step>
               <Text>Do not freeze</Text>
               <Image>...</Image>
               <Order>2</Order>
            </Step>
            <Step>
               <Text>Salad and Fruit Chopping Board</Text>
               <Image>...</Image>
               <Order>3</Order>
            </Step>
         </CcpList>
      </Ccp>
      <Service>
         <ContentType>text/plain</ContentType>
         <Service />
         <ServiceVehicleText>10 inch white plate for toast plus small white bowl for salad garnish.</ServiceVehicleText>
      </Service>
   </RecipePreparation>
</RecipePreparations>