Recipe & Menu Engineering Import API Release Notes

Overview

This page explains the changes that have happened to our Recipe & Menu Engineering Import API since August 2020.

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.

Note: Access to new POST and DELETE operations is provided only on request. If you wish to use a new POST or DELETE operation, please get your customer to request access on your behalf. New GET operations are normally available to integrated partners immediately, unless otherwise indicated.

28 July 2021 — New endpoints for alternate ingredients; and additional validation for ingredient endpoints

New endpoints for managing alternate ingredients

Two new endpoints are available for managing alternate ingredients:

• GET /ingredientsalternates
• POST /ingredientsalternates

These endpoints are intended to permanently replace the GET and POST /ingredients endpoint for managing alternate ingredients. This will make your managing ingredient requests simpler, as you will be able to send through just the relevant data to update either a parent or alternate ingredient.  

Warning: After the 1st of February 2022, the POST and GET /ingredients endpoint will stop supporting alternate ingredients. If you are using the POST /ingredients endpoint, you will need to update your integration to reflect this change.

Parent ingredients will continue to be managed via the GET and POST /ingredients requests.

Please see the API reference for integration details.

Additional validation for ingredient endpoints

Additional validation now exists that prevents an ingredient in the “Approval” workflow from being updated by the API.

The endpoints this applies to are:

• POST /ingredients
• POST /ingredientintolerance
• POST /ingredientcategory
• POST /ingredientnutrient
• POST /ingredientpriceband
• POST /ingredientconversion      

If you attempt to update an ingredient that is in the approval workflow via these endpoints, Fourth now returns an error message.

18 May 2021 — New shelf life endpoints, updates for Natasha's Law, and additional validation for UoMs

Update to access rights for Natasha’s Law ingredient list endpoints

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

• POST /ingredientlist
• GET /ingredientlist
• GET /recipeingredientlist

To enable this functionality, customers must contact the Fourth team. If it is not enabled, then requests receive a 403 response.

New ReadyForUse field for ingredient lists

A new field, ReadyForUse is now required in the request body for the Update Ingredient List endpoint:

• POST /ingredientlist

Possible values are:

• yes — the ingredient's Ingredient List is ready for use in recipe Ingredient Lists. This means the ingredient's Ingredient List is included in the combined ingredient list of any recipes that it is in.
• no — the ingredient's Ingredient List is not ready for use in recipe Ingredient Lists. Any recipe that includes this ingredient will not have an auto-calculated ingredient list.

Example request body

[
   {
      "StarchefKey": "3422",
      "SupplierName": "Grocer",
      "SupplierCode": "N101",
      "FullIngredientList": "Orange Juice, Vitamin C, Calcium",
      "LabelDescription": "Fortified Orange Juice",
      "ReadyForUse": "yes"
   }
]

The same field is now returned in the GET request for the endpoint:

• GET /ingredientlist

Example response body

[
   {
      "IngredientName": "Calcium Plus Vitamin D (No Pulp) Orange Juice",
      "StarchefKey": "3422",
      "ParentGuid": "ce769cd4-c84a-4144-84f4-4ac912646152",
      "AlternateGuid": "aa869cd4-c84a-4144-84f4-4ac912646152",
      "FullIngredientList": "Orange Juice, Vitamin C, Calcium",
      "LabelDescription": "Fortified Orange Juice",
      "ReadyForUse": "yes"
   }
]

New Ingredient Shelf Life endpoint

A new endpoint with POST and GET methods is available for managing the shelf life of ingredients:

• POST /ingredientshelflife
• GET /ingredientshelflife

You will need to talk to your customer about their Fourth settings when integrating with this endpoint. Customers can tailor the six shelf life fields in Fourth for their own use (normally done during the Fourth implementation stage). Therefore, the names that customers use for the fields may not match the ones in the API request. For example, ShelfLifeTwo may be named “Maximum shelf life from freezer” in the UI. Most customers only use a few of the shelf life fields.

As well, each customer can have a global setting for the minimum and maximum accepted shelf life for items. When Fourth receives a POST /ingredientshelflife request, we check that the values sent are within the customer’s limits. If one or more of the values is outside a limit, Fourth returns an error message in the format:

The value should be between [min - max] value.

The POST /ingredientshelflife method lets you both add or update shelf life values. To update an existing record, either include its StarChefKey or the original SupplierName and SupplierCode.

Unlike the other POST requests for this API, you can choose to update ONLY the shelf life fields that are relevant. Any fields you don’t include in the request retain their current value.

You cannot send through a null value. However, 0 is an accepted value — you should discuss with your customer what this value would mean for them.

Example POST /ingredientshelflife request body

This example shows all the possible shelf life fields.

[
   {
      "ShelfLife": "12", 
      "ShelfLifeTwo": "2",
      "ShelfLifeThree": "0",
      "ShelfLifeFour": "0",
      "MinShelfLifeIntoUnit": "0",
      "MinShelfLifeDays": "0",
      "SupplierName": "Dairy",
      "SupplierCode": "B365",
      "StarChefKey": "0030702"
   }
]

The GET /ingredientShelfLife method returns the shelf life values for an ingredient. This can include empty strings, as most customers do not use all the shelf life fields.

You can filter these requests by ingredient productId, guid, and groupGuid.

Example GET /ingredientShelfLife response body

[
   {
      "ShelfLife": "7",
      "ShelfLifeTwo": "3",
      "ShelfLifeThree": "",
      "ShelfLifeFour": "",
      "MinShelfLifeIntoUnit": "",
      "MinShelfLifeDays": "",
      "SupplierName": "The Farm",
      "SupplierCode": "C132",
      "StarChefKey": "0031291"
   }
]

For more information about integrating, see the API Reference:

• POST /ingredientshelflife
• GET /ingredientshelflife

Additional validation added for ingredient Unit of Measure fields

This update includes additional validation for the POST /ingredients Unit of Measure (UoM) fields.

This update supports our customers who use the Fourth Inventory system for stock management. It ensures that the supplied product UoM and the stock-taking UoM use the same types of unit.

There are three sets of fields in the Ingredients endpoint that relate to the unit size and type:

• Supply fields: the details of the supplied product. E.g. SupplyQuantity and SupplyQuantityUnit.
• Invoice fields: the details of a supplied product as invoiced. E.g. invoiceUom.
• Unit fields: the details used in Inventory for stocktake. E.g. UnitSizeNumber, and UnitSizeUom.

Catch weight ingredients

For catch weight ingredients, the UoMs of the Invoice and Unit must now match. For example:

   "UnitSizeUom": "KG",
   "InvoiceUom": "KGM",
   ...

Note that the only valid UoMs for catch weight products are KG (KGM) or LB.

All other ingredients

For all other ingredients, the UoMs of the Supply and Unit must logically match. This means that if an ingredient's UnitSizeUom is:

• A weight, the SupplyQuantityUnit must also be a weight.
• A volume, the SupplyQuantityUnit must also be a volume.
• Other, the SupplyQuantityUnit must be the same value; e.g. each, slice or bottle.

Volume example

   ...
   "SupplyQuantity": "12", 
   "SupplyQuantityNumber": "150",  
   "SupplyQuantityUnit": "millilitre",
   "SupplyQuantityDescriptor": "Carton",
   ...
   "UnitSizeNumber": "15",  
   "UnitSizeUom": "centilitre",  
   "UnitSizeUomDescriptor": "Can",
   ...

Settings that restrict access to updating UoMs

There are two global settings in Fourth that can stop you from updating UoM values via the API. These are:

• Supply Quantity read-only for Live Ingredients — when enabled, you cannot update these supply fields for an ingredient: SupplyQuantityNumber, SupplyQuantity, and SupplyQuantityUnit.
• Unit Size read-only for Live Ingredients —  when enabled, you cannot update the values for these fields: UnitSizeNumber, and UnitSizeUom.

To enable or disable 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. Partners can view and update data in ingredient lists using the following new endpoints:

• GET /ingredientlist — Gets the ingredient lists for ingredients. This retrieves the current value of the ingredient list for an ingredient, and any supporting data that you need to supply when updating an ingredient list.
• POST /ingredientlist — Updates an ingredient’s ingredient lists. Use this to replace the current ingredient list with a new list.
• GET /recipeingredientlist — Gets the ingredient list for a recipe. This retrieves the current value of a recipe’s ingredient list.

The Import API Guide contains a section called Support for Natasha’s Law, which explains how to use these endpoints and how they interact with the settings available to users in the Fourth user interface. Please ensure that you read this, as well as the Import API reference, when integrating with these endpoints. 

Additionally, to support the creation of consumer-friendly labels, there are these additional new endpoints:

• POST /recipenames — Add or update recipe names. This endpoint lets you add a recipe name that is label and consumer-friendly.
• GET /recipenames — Gets the recipe names. This retrieves the recipe names, and any supporting data that you need to supply when updating recipe names.

The Recipe & Menu Engineering Export API also includes endpoints related to Natasha’s Law. These endpoints allow you to audit a recipe or ingredient's ingredient list history. You can find out about these endpoints in the Export API Guide.

For more information about Natasha's Law:

• Visit help.fourth.com and search for "Natasha's Law" for articles published by us.
• View the Food Standards Agency's technical guidance on their website.
• View the Legislation online.

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 — New Delete Alternate Ingredients endpoint

A new endpoint is available that lets you delete an alternate ingredient. This removes the alternate’s details from the parent ingredient with any information that is owned by the parent ingredient remaining the same.

Parent ingredients cannot be deleted via this endpoint, and you cannot delete an alternate ingredient that is currently in use in a recipe.

The endpoint is:

• [ROOT]/deletealternates

The request includes a body with the details of the ingredient you wish to delete. You can choose to identify the ingredient using either its StarChefKey or the SupplierName and SupplierCode. If you use StarChefKey, the other two fields are ignored.

Request body example

[
   {
        "StarChefKey": "22",
        "SupplierName": "Grocer",
        "SuppplierCode": "N101"
    }
]

For more information on this endpoint, see the API reference.

29 September 2020

Manual approval step available for intolerance values

Please note that customers can now choose to manually review and approve any intolerance values updated via the API.

This does not have any impact on the behavior of the API itself.

New recipeidentifiers endpoint

The new GET recipeIdentifiers endpoint lets you retrieve just the identifiers for recipes. This will particular benefit API users who retrieve large data sets.

The filters available for the endpoint are:

• lastModifiedAfter
• lastModifiedNutrientsAfter
• lastModifiedIntolerancesAfter

Sample response

{
   "RecipeName": "Seasoning Salt & Pepper",
   "StarChefKey": 358,
   "RecipeGuid": "F4F29170-2344-4B20-A0AE-534EB34C4FB7",
   "DateLastUpdated": "2021-02-16T09:18:49"
}

For further information on this endpoint, please see the API reference.

Additional field in POST ingredients endpoint

The POST /ingredient endpoint now includes a new request body field: ParentIngredientProductName.

The value is optional. However, if you are updating an ingredient, please remember that if you leave this field blank, this will remove any existing value for the field.

Example request body (truncated)

[
  {
    "IngredientName": "Orange",
    "IngredientGuid": "5FD5ED46-C254-4002-9EF4-6513C623CD0D",
    "ParentIngredientProductName": "Fresh Orange",
    "SupplierName": "Beetniks Beets and Beverages",
    "SupplierCode": "B112",
    "StarChefKey": "0231703",
    …
    }
]

26 August 2020 — New endpoints for ingredient costs and price bands

Two new endpoints have been introduced to GET ingredient costs and price bands.

Ingredient costs

The new endpoint is:

• GET [ROOT]/ingredientcosts

By default, this returns details for all ingredients. You can filter the response using query parameters:

• lastModifiedAfter — Returns only records modified on or after the date. Use the format: yyyy-mm-dd
• groupGuid — The logical business group within Recipe & Menu Engineering.
• productId — The StarChefKey for an ingredient
• GUID — The IngredientGuid for an ingredient
• setType — The ingredient set type, if these are in use. Options are: Blank, Trial, Archive, and Live.

This returns the existing and pending price details for an ingredient. If there is no value for a price it will be set to 0.00; for a date it will be set to null. For example:

[
  {
    "SupplierName": "The Vegan Butcher",
    "SupplierCode": "12A4D63C",
    "StarChefKey": 213,
    "ProductGUID": "a429bf60-bd54-4b82-8e28-151c4d94a1fb",
    "IngredientCostPrice": "13.99",
    "PendingIngredientCostPrice": "25.00",
    "PendingCostEffectiveDate": "8/21/2020 12:00:00 AM",
    "InvoicePrice": "0.00",
    "PendingInvoicePrice": "0.00",
    "PendingInvoicePriceEffectiveDate": null
  }
]

For more information on this endpoint, please see the API guide and reference.

Ingredients price bands

The new endpoint is:

• GET [ROOT]/ingredientspricebands

By default, this returns details for all ingredients. You can filter the response using query parameters:

• lastModifiedAfter — Returns only records modified on or after the date. Use the format: yyyy-mm-dd
• groupGuid — The business group within Recipe & Menu Engineering.

This returns the price bands for ingredients.

[
  {
    "StarChefKey": 0036858,
    "ProductGUID": "00000000-0000-0000-0000-000000000000",
    "SupplierName": "Dairy",
    "SupplierCode": "B365",
    "PriceBandName": "Default",
    "OverridePrice": "12.14",
    "SupplierAccountCode": "21323"
  }
]

For more information on this endpoint, please see the API guide and reference.

26 August 2020 — New batch endpoint for checking request processing

For successfully submitted POST requests, Fourth returns a status in the synchronous response body. For example:

{
  "Status": "Processed;Aug 10 2020 8:32AM",
  "BatchId": "2345"
}

The two possible states are Processed (with a timestamp) and Not processed. To check the processing status later, you can now use the /batches endpoint:

• [ROOT]/api/ingredientandaccessimport/batches

You can filter the response by individual request; for example:

• [ROOT]/api/ingredientandaccessimport/batches?batchId=3722

Or filter by the number of results want returned (from 1 to 100). For example, this returns the last processing status of the last two requests made:

• [ROOT]/api/ingredientandaccessimport/batches?batchSize=2

Sample response:

[
  {
    "Status": "Not processed",
    "BatchId": 3724
  },
{
    "Status": "Processed;Aug 28 2020  8:32AM",
    "BatchId": 3722
  }
]

26 August 2020 — New Units of Measure

New Units of Measure

Fourteen new standard RME UoMs (units of measure) have been created. These UoMs are compatible for use with the Inventory application.

Unit Name (RME)	Unit Type (RME)	Unit Abbreviation	Equates to [number + UoM]
KEG (D) 1/2	Volume	KEG (D) 1/2	1984 Floz (US)
KEG (D) 1/4	Volume	KEG (D) 1/4	992  Floz (US)
KEG (D) 1/6	Volume	KEG (D) 1/6	661 Floz (US)
KEG (I) 1/2	Volume	KEG (I) 1/2	1690.70 Fl oz (US)
KEG (I) 1/3	Volume	KEG (I) 1/3	1014.42 Fl oz (US)
KEG (I) 1/4	Volume	KEG (I) 1/4	845.35 Fl oz (US)
PACK	Each	PK	1 Each
TRAY	Each	TRAY	1 Each
SHEET	Each	SHT	1 Each
Pan 1/3 4 " Deep	Volume	Pan 1/3 x 4"	4.5 Quarts (US)
PAN 1/6 6" Deep	Volume	Pan 1/6 x 6"	2.5 Quarts (US)
Quart, Dry (US)	Volume	QT, Dry (US)	37.2364 Fl oz (US)
Bushel	Volume	BU	1191.57 Fl oz (US)
BARREL	Volume	BRL	5376 Fl oz (US)