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 no longer available for use.

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.

Breaking change notification

20th August 2023

As part of its ongoing commitment to the security of its customer’s information, Fourth will be updating its platform to require all connections to use TLS 1.2 or higher from 9 January 2024. Older versions of TLS will be retired.

TLS is the encryption method used to secure communications over HTTPS. This will have no impact on SFTP connections.

22 March 2023 — Precision increased for nutrient endpoints & new GET recipeswithoutingredientcost endpoint

Precision increase for nutrient endpoints

For the following endpoints:

We have increased the precision of nutrition data by including more places after the decimal point.

Previously, responses would include values up to three digits after the decimal point. Now, the precision for all nutrient values is six digits after the decimal point. This is done as required; only if there are meaningful digits (that is, values greater than zero) after the decimal point, does the response includes these values. For example, 0.50000 is returned as 0.5, but 0.000200 is returned as 0.0002.

This change occurred as nutrient values in RME API responses are always specified in grams. Before this change, it was not possible to report on the presence of nutrients that were present in tiny amounts. This change will particularly impact sodium which is often displayed in milligrams on the RME Recipe and Ingredient Nutrition screens but returned in the API as a gram value.

New GET /recipeswithoutingredientcost endpoint

The new /recipeswithoutingredientcost resource enables you to retrieve almost all the same information as the GET /recipes resource, excluding three fields related to ingredient cost. These are:

  • RecipeIngredientCost
  • RecipeIngredientPortionCost
  • RecipeIngredientCostPercentage

Removing these fields increases the speed that Fourth can respond to the request. This makes it a better resource to integrate with if you need core recipe information but do not require ingredient cost details. It has the same date-related filter options as the GET /recipes resource:

  • createdAfter
  • lastModifiedAfter
  • scheduledExportAfter
  • lastNutritionModifiedAfter
  • lastNutritionModifiedBefore

For more information, see the /recipeswithoutingredientcost endpoint in the API Reference.

7 March 2023 — Replacement of Base URLs

As part of ongoing security improvements, the base URLs for all Recipe & Menu Engineering Export API requests are changing. For access to the new URLs, please get in contact with us.

Access via these URLs is available now. You can use your existing usernames and passwords to authenticate with the service. Note that users accessing it via a web browser or similar will need to manually enter credentials when signing in for the first time.

Please note that none of the responses will change as a result of this base URL change.

22 February 2022 — Version 1 deprecation complete

Version 1 of the Recipe & Menu Engineering Export API is now deprecated. Please read the original release note below to find out more.

3 February 2022 — Version 1 deprecation

As part of our continued commitment to the health of our products, Fourth is planning to deprecate Version 1 of the Recipe and Menu Engineering API. The API will stop functioning on the 22nd of February 2022.

This API is accessible from the URL: api.starchef.net/[resource] 

Existing API users should move to using V2, available from: api.starchef.net/v2/[resource]

Documentation for V2 is on our Developer Hub here:

Notes

  • You can use V1 credentials for V2 requests.
  • All requests that are available in V1 are available in V2.
  • However, there are additional properties in some of the V2 responses.

What we recommend

If you use V1 of the RME GET API, we strongly recommend that you start using the V2 URL (api.starchef.net/v2/[resource]) as soon as possible to allow sufficient time for any required changes to integrations. Any existing integrations should be tested to ensure they continue to work without error with the V2 URL and V2 responses.

How to contact us

We have created a group on our Community for partners and customers to collaborate with our solution experts and provide feedback. We welcome the opportunity to work together on this change and thank you in advance for communicating this to your team.

27 October 2021 — Sets information now in GET responses; and override price added to GET /ingredients endpoints

Sets in GET responses

The following GET requests now return Sets information:

  • GET /ingredients
  • GET /ingredients/{guid}
  • GET /recipes
  • GET /recipes/{guid}
  • GET /menus
  • GET /menus/{guid}

GET /ingredients and GET /ingredients/{guid} response snippet

"IngredientSets": {
    "Set": ["drink", "food", "Menu Development", "Cafe Metros"]

GET /recipes and GET /recipes/{guid} response snippet

"RecipeSets": {
    "Set": ["drink", "food", "Menu Development", "Cafe Metros"]

GET /menus and GET /menus/{guid} response snippet

"MenuSets": {
    "Set": ["drink", "food", "Menu Development", "Cafe Metros"]

See the API reference for full examples of these requests.

Addition of Override price to GET /ingredients and GET /ingredients/{guid}

The GET /ingredients and GET /ingredients/{guid} endpoints now return an override price as part of the SuppliedPackSize for an ingredient.

An override price is the price of the ingredient for the specified price band. For information about price bands, see the Import API Guide.

Example response (truncated)

    ...
    "SuppliedPackSizes": [
      {
        "StarChefKey": "0012345",
        "InternalCode": "A11B2332",
        ...
        "SuppliedProductGUID": "string",
        "OverridePrice": "5.67"
      }
      ...

See the API reference for full examples of these requests.

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.