Menu & Recipe Engineering Export API Release Notes

Overview

This page explains the changes that have happened to our Recipe & Menu Engineering Export API since September 2018.

Note that these release notes are for version 2 of our Recipe & Menu Engineering Export API. Version 1 is supported but remains static; that is, we do not add new functionality or changes to that version.

These Release Notes are up-to-date at the time of the release. Further improvements or corrections to our API documentation will normally occur in the guide and reference only.

If you have already integrated with Fourth and would like to be kept abreast of API changes via email, please fill in this form.

18 May 2021 — Update to access rights for Natasha’s Law audit endpoints

These endpoints are accessible only if the customer has the full ingredient list functionality enabled for their organisation:

  • GET /Ingredients/{guid}/fullIngredientListHistory
  • GET /Ingredients/fullIngredientListHistory
  • GET /Recipes/{guid}/fullIngredientListHistory
  • GET /Recipes/fullIngredientListHistory

If the functionality has not been enabled, then requests receive a 403 response.

Note that, to enable this functionality, customers must contact the Fourth team.

7th April 2021 — New endpoints supporting Natasha’s Law

The Food Information (Amendment) (England) Regulations 2019, also known as Natasha’s Law, requires food businesses to label all food that is ‘pre-packaged for direct sale’ with the complete ingredient and allergen details.

To support this legislation, each ingredient and recipe in Fourth now has a field that holds full sub-ingredient data. This data can come from two sources: manually keyed in by our customers, or via our APIs from a partner or supplier. The field is called an Ingredient List. As customers or partners may need to see the changes that have occurred to ingredient lists over time, we have developed auditing endpoints in our RME Export API.

Ingredient auditing

These endpoints are now available:

The response format you receive from both endpoints is the same. The Export API Guide contains a section called Support for Natasha’s Law, which explains how to use these endpoints. Please ensure that you read this, as well as the Export API reference, when integrating with these endpoints.

Example response

[
   {
      "ProductId": 139,
      "FullIngredientList": "Cow's MILK, Salt",
      "FirDate": "2021-02-10T16:06:02.503",
      "ProductGuid": "f6f1630f-1dc3-4e5e-ab56-e38240433cde",
      "ProductName": "Butter Salted",
      "History": [
         {
            "HistoryLogId": 2182,
            "ProductId": 139,
            "FullIngredientListFrom": "",
            "FullIngredientListTo": "Cow's MILK, Salt",
            "LoginName": " apipartner",
            "ModifyDate": "2021-02-11T12:12:03.003"
         }
      ]
   }
]

Recipe auditing

These endpoints are now available:

The response format you receive from both endpoints is the same. The Export API Guide contains a section called Support for Natasha’s Law, which explains how to use these endpoints. Please ensure that you read this, as well as the Export API reference, when integrating with these endpoints.

Example response

[
   {
      "ProductId": 74855,
      "FullIngredientList": " Tofu (SOYA), cornflour, garlic, rapeseed oil, smoked paprika, salt, pepper",
      "FirDate": "2021-03-22T13:33:55.97",
      "ProductGuid": "101ef8a8-e61e-4f8a-9485-e05ff3ee488c",
      "ProductName": "Salt and Pepper Tofu",
      "History": [
         {
            "HistoryLogId": 3455,
            "ProductId": 74855,
            "FullIngredientListFrom": "",
            "FullIngredientListTo": " Tofu (SOYA), cornflour, garlic, rapeseed oil, smoked paprika, salt, pepper",
            "LoginName": "apipartner2",
            "ModifyDate": "2021-03-22T13:33:55.97"
         }
      ]
   }
]

The Recipe & Menu Engineering Import API also includes endpoints related to Natasha’s Law. These endpoints allow you to update or retreive ingredient list. You can find out about these endpoints in the Import API Guide.

For more information about Natasha's Law, see also:

7th April 2021 — Update to alternate ingredients conversion UoMs

Now, when an alternate ingredient is created, its pack size (supply quantity) can be defined using the parent ingredient base Unit of Measure (UoM) or any of the parent ingredient conversion UoMs.

This update means that GET requests that return supply pack size (or supply quantity values) may now return values that are a conversion UoM of the parent ingredient. And, you can use these conversion rates when creating or updating an alternate ingredient using a POST /ingredients request.

For further information about how conversion values work, please see the customer release note.

17 November 2020 — Additional GET Menus field

A new field, CourseGUID, is returned with these endpoints:

  • GET /menus/{guid}
  • GET /menus

This is an identifier for the course that is globally unqiue across the Fourth platform.

Response example (truncated)

{
   ...
   "MenuCourses": [
   {
      "CourseName": "Course name",
      "CourseID": "234567",
      "CourseGUID": "123e4567-e89b-12d3-a456-426614174000",
      "CourseOrder": "1",
      "BuffetSellingPrice": "1.23",
      "BuffetSales": "2.21",
      ...  

29 September 2020 — GET Ingredients and GET Recipe Nutrition updates

GET ingredients CostPrice update

The GET ingredients endpoint now returns the CostPrice field for an ingredient with a zero (or null) cost. The value will be 0.00.

Previously this property was not included in the response if the ingredient had zero cost.

GET recipes/{guid}/nutrition: sodium value standardized

Previously, depending on the customer's Fourth configuration, the sodium value returned by the GET recipes/{guid}/nutrition endpoint would be either in grams or milligrams, despite the field being named PerServingGram:

            {
                "NutrientName": "Sodium",
                "NutrientDescription": "Sodium (g)",
                "PerServingGram": "0.549",
                "Per100g": "0.354",
                "PercentageOfGDA": "22.879",
                "NutrientGuid": "887d699b-4c2e-4f2d-90df-6afdf801e5bc"
            },

To ensure that there is no confusion for API integrations, this value is now always in grams.

GET recipes/{guid}/nutrition now returns salt in response

The GET recipes/{guid}/nutrition endpoint now includes salt in the response. For example: 

[
    {
        "RecipeGuid": "a672fd1e-85b5-476c-9337-833d4c76a270",
        "PLU": "0000495",
        "Name": "Caesar Salad",
        "CalculationMethod": "Auto-calculate",
        "SelectedStandard": "Reference Intake (RI) of an average adult, Adults, Adults (general)",
        "Nutrients": [
            ...
            {
                "NutrientName": "Salt(g)",
                "NutrientDescription": "Salt(g)",
                "PerServingGram": "1.373",
                "Per100g": "0.886",
                "PercentageOfGDA": "22.879",
                "NutrientGuid": "887d699b-4c2e-4f2d-90df-6afdf801e5bc"
            }
        ]
    }
]

26 August 2020 — supplierspec endpoint allows group GUIDs

For this endpoint:

  • GET /ingredients/{guid}/supplierspec

you can now use a group GUID rather than an ingredient GUID as the path parameter. When you use a group GUID, you get an array of supplier specification details for all ingredients that are available to that group.

For information on groups see the guide.

For information on this endpoint see the reference.

02 June 2020 — New intolerance history endpoints for recipes and ingredients

Additional endpoints are now available for checking when and what changes have happened to intolerances for recipes and ingredients.

These endpoints are:

  • GET /Ingredients/intolerancehistory
  • GET /Ingredients/{guid}/intolerancehistory
  • GET /Recipes/intolerancehistory
  • GET /Recipes/{guid}/intolerancehistory

JSON example response for an ingredient intolerance:

[
  {
    "IngredientGuid": "e3a02582-d36b-4670-a12e-fc6a7b39ccfd",
    "Name": "Vegan Cheddar Cheese",
    "IntoleranceItems": [
      {
        "Name": " Contains Milk or Milk Products",
        "Events": [
          {
            "From": "Y",
            "To": "N",
            "Id": 12345,
            "ChangeDate": "2020-06-09T15:34:55.91",
            "UserId": "ishmael",
            "Action": "Modify"
          }
        ]
      }
    ]
  }
]

The fields within IntoleranceItems are:

Name
The name of the intolerance.

Events
An array of events that have occurred for the intolerance.

From
The original status for whether the intolerance is in the recipe or ingredient. One of:

  • Y — Yes
  • N — No
  • M — Maybe   

The status can also be null. The From field isn't included when the Action is Add.

To
The new status for whether the intolerance is in the recipe or ingredient. One of Y, N, M and null.

The To field isn't included when the Action is Remove.

Id (number)
A reference ID for the change.

ChangeDate
When the change occurred; in the format: yyyy-mm-ddT00:00:00:000.

UserId
The user ID of the person who made the change. This is the same as their login name.

Action
One of:

  • Add — The event changed a status from null to Y, N, M.
  • Modify — The event changed a status from: Y, N, M to Y, N, M.
  • Remove — The event changed a status from Y, N, M to null.

XML example showing the Add and Remove actions:

<Ingredients>
  <Ingredient>
    <IngredientGuid>34489c7b-8462-4db2-bcc7-a3c0981da1b9</IngredientGuid>
    <Name>Champagne, Vintage</Name>
    <IntoleranceItems>
      <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>caadmin</UserId>
          <Action>Remove</Action>
        </Event>
        <Event>
          <To>Y</To>
          <Id>22795</Id>
          <ChangeDate>2020-06-03T09:04:59.91</ChangeDate>
          <UserId>caadmin</UserId>
          <Action>Add</Action>
        </Event>
      </Events>
    </IntoleranceItem>
    <IntoleranceItem>
      <Name>Contains Molluscs</Name>
      <Events>
        <Event>
          <To>Y</To>
          <Id>22796</Id>
          <ChangeDate>2020-06-03T09:04:59.91</ChangeDate>
          <UserId>caadmin</UserId>
          <Action>Add</Action>
        </Event>
      </Events>
    </IntoleranceItem>
  </IntoleranceItems>
</Ingredient>
</Ingredients>

15 April 2020 — Updates to /processdata and /recipes/{guid}/intolerances endpoints

The Recipe & Menu Engineering Export API has had the following improvements.

Alternate ingredients now return the parent ingredient’s food processing data

Alternate ingredients are always linked to a parent ingredient, and do not have their own food processing data.

Previously, if you made an ingredients/{guid}/processdata request for an alternate ingredient, the response would not return any data. Now, the response will contain the processing data for the parent ingredient. (The GUID returned will be for the alternate ingredient however.)

For more information about alternate ingredients, please see the guide.

New filter for the /recipes/{guid}/intolerances endpoint

The /recipes/{guid}/intolerances endpoint can now be filtered by LastModifiedAfter.

Example request:

  • /recipes/{GUID}/intolerances?lastModifiedAfter=YYYY-MM-DD

This returns only records modified on or after the date. Use the format: yyyy-mm-dd.

11 March 2020 — Update to support recipes as a portion for sellable ingredients

Note: this update applies only to customer integrations using Recipe & Menu Engineering as a standalone product (without Fourth Inventory), and using sellable ingredients.

The following endpoints are impacted:

  • /ingredients
  • /ingredients/{guid}

Customers can now specify a recipe as a portion option for a sellable ingredient. In the Export API, the recipe is identified via a RecipeGuid.

JSON Sample:

"Portions": [
   {
    "Position": 0,
    "Name": "string",
    "Quantity": "string",
    "UoMGuid": "string",
    "UoM": "string",
    "Cost": "string",
    "RecipeGuid": "13a02582-d36b-4670-a12e-fc6a7b3934fd"
   }
]

6 February 2020 — Support for alternate ingredients added to three GET requests

The following endpoints now include better support for alternate ingredients:

  • /ingredients/{guid}
  • /ingredients/{guid}/intolerances
  • /ingredients/{guid}/nutrition

Alternate ingredients do not have their own intolerance and nutrient data. Instead, the parent ingredient defines this information, as well as a range of other data points.

Previously, if a request was made to one of these endpoints for an alternate ingredient, you would not receive a response back with relevant data. Now, if a request is made for an alternate ingredient, then the response will contain:

  • /ingredients/{guid} — the alternate ingredient's data, plus the additional data that is defined by the parent ingredient.
  • /ingredients/{guid}/intolerances — the intolerance data for the parent ingredient.
  • /ingredients/{guid}/nutrition — the nutrition data for the parent ingredient.

All three endpoints will return the alternate ingredient's GUID in the response.

22 January 2020 — Addition of two alcohol fields for recipes

Additional alcohol-related fields are now available on the following recipe endpoints:

  • Recipes
  • Recipes/{guid}

The fields are:

  • AlcoholByVolume (double) — The standardised measure of alcohol as a percentage of the overall content. For example, 14.5 would refer to 14.5% alcohol by volume.
  • AlcoholUnits (double) — The number of alcohol units in the recipe; e.g. 2.5. UK recipes should use the standard of one unit of alcohol equalling 10ml (or 8g) of pure alcohol. Customers and products in other countries may have differing ways of measuring this concept.

Both of these fields are in the top-level of the JSON/XML structure.

20 November 2019 — New /supplierspec endpoint for ingredients

A new GET endpoint is available for ingredients:

  • /Ingredients/{guid}/supplierspec

This endpoint provides the same information for an ingredient as shown in the Supplier Details screen of Fourth Recipe & Menu Engineering. This covers indepth information about data such as the ingredient's packaging and delivery.

For information on how to integrate with this endpoint, please see the guide and reference.

Sample JSON:

"ProductGuid": "00000000-0000-0000-0000-000000000000",
"IngredientName": "string",
"StarchefKey": 0,
"FullCaseCostPriceNotSplit": "string",
"GrossWeight": "string",
"NettWeight": "string",
"CaseDimensionLength": "string",
"CaseDimensionWidth": "string",
"CaseDimensionHeight": "string",
"CasesOnLayer": "string",
"CasesOnPallet": "string",
"LayersOnPallet": "string",
"CasesOnContainer": "string",
"PalletType": "string",
"PalletDimensionLength": "string",
"PalletDimensionWidth": "string",
"PalletDimensionHeight": "string",
"PackagingInnerCard": "string",
"PackagingOuterCard": "string",
"PackagingInnerPaper": "string",
"PackagingOuterPaper": "string",
"PackagingInnerGlass": "string",
"PackagingOuterGlass": "string",
"PackagingInnerAluminium": "string",
"PackagingOuterAluminium": "string",
"PackagingInnerSteel": "string",
"PackagingOuterSteel": "string",
"PackagingInnerPlastic": "string",
"PackagingOuterPlastic": "string",
"PackagingInnerWood": "string",
"PackagingOuterWood": "string",
"PackagingInnerCork": "string",
"PackagingOuterCork": "string",
"PackagingInnerOther": "string",
"PackagingOuterOther": "string",
"Temperature": "string",
"RetailBarCodeDetails": "string",
"EuropeanCommodityCode": "string",
"AgreedMinDeliveryCases": "string",
"AgreedMinDeliveryQuantity": "string",
"OrderLeadTime": "string",
"CasesHeldBySupplier": "string",
"SupplierOrderLeadTime": "string",
"ManufacturerSupplierSite": "string",
"ItemVatable": "string",
"IsBespoke": true,
"CountryOfOrigin": "string",
"CountryOfOriginLink":
[
    "string"
],
"ABV": "string",
"AlcoholUnitPerCase": "string",
"DeliveryCharge": "string",
"InstallationCharge": "string",
"DisposalCharge": "string",
"Vintage": "string",
"InvoiceUOM": "string",
"InvoicePrice": "string",
"PendingInvoicePrice": "string",
"IsAvaliable": true,
"IsAztecFlag": true,
"IsStockForInvoiceManagment": true,
"IsIgnorePriceInInvoiceMatching": true,
"ImageUrls": "string",
"ConsignmentLocation": "string",
"RouteToMarket": "string",
"Depots":
    [
        "string"
    ],
    "IsConsignment": true
}

21 August 2019 — Two fields added to support buffet menus

To additional fields are now available from the following endpoints:

  • /menus
  • /menus/{guid}

The fields are RecipeGuid and RecipeName. The addition of these fields will make identifying individual menu items in a buffet menu easier. They are included in the MenuItems array.

JSON example:

"MenuItems": [
    {
    "RecipeGuid": "0cba0806-c8c0-457d-b275-c1c92c3d679c",
    "RecipeName": "Pasta salad",

XML example:

<MenuItems>
  <MenuCourseProduct>
    <RecipeGuid>713e4017-1eb3a-aa66-c75f69460197</RecipeGuid>
    <RecipeName>Shrimp cocktail</RecipeName>

22 May 2019 — Barcodes now available for recipes

The Recipes & Menu Export API (v2) now includes barcode data for recipes. This data is returned in the following endpoints:

  • /Recipes
  • /Recipes/{guid}

The endpoint includes an array for barcodes, as some customers, may include multiple variants of the exact same product in a recipe (e.g. a chocolate bar that is using seasonal packaging but is otherwise identical to it's non-seasonal packaging).

"Barcodes": [
    "5000254020408",
    "5036017140166",
    "5077553211721"
],

23 January 2019 — New "Added Sugar" nutrient returned in responses

A new nutrient: "Added sugars" is now returned in nutrient data for ingredients and recipes. The impacted endpoints are:

  • /ingredients/{guid}/nutrition
  • /recipes/{guid}/nutrition
  • /nutrients

Note that to receive this value, the API user account must have the "extended nutrition view" enabled.

19 September 2018 — New /processdata endpoint available for ingredients

The Recipe & Menu Engineering Export API now includes a new endpoint for ingredients:

  • /ingredients/{guid}/processdata

This endpoint is relevant for ingredients that are processed or manufactured in some way and in themselves have separate ingredients; for example, sausages. The endpoint provides information such as:

  • Manufacturing site and address
  • Manufacturing processes
  • Ingredients declaration
  • Protein specification
  • Minimum and average protein pieces
  • List of all particulates
  • Manufacturers regeneration and cooking instructions
  • Legal description for use on menus
  • Product organoleptic data, appearance, and texture
  • Packaging information

For information on making requests to this endpoint, please see the Export API reference.