Recipe & Menu Engineering Import API Guide

Introduction

The Recipe & Menu Engineering Import API lets you create or update a wide range of ingredient and supplier details in Fourth.

Quick Facts

Integration type HTTP REST with JSON and XML
Authentication Basic authentication
Availability All customers using our Purchase to Pay and Inventory solution
Testing Test environment available
More information See the Import API Reference

Get access

Contact your Fourth Implementation Consultant. They will provide:

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

CONTACT US

Uniquely identifying each ingredient 

Inside Fourth, ingredients are linked with suppliers. When you send in an ingredient-related request, we rely on supplier information to uniquely recognise a new or existing ingredient:

  • SupplierName — Name of the supplier
  • SupplierCode — A unique identifier for the ingredient, as provided by the supplier

Using both fields stops existing ingredients from being accidentally altered by another supplier’s ingredient (if they coincidentally shared the same unique ID). This can also make integrating faster, as you do not need to create or track IDs separately from Fourth and the supplier.

To update an existing ingredient, you must include both SupplierName and SupplierCode

Resources

Fourth will provide you with the base path for requests. Each resource exposes a single POST method to both create and update entries. There are no path parameters required.

Resource Task
ingredients

Adds or updates one or more ingredients.

Before you can add ingredients, the supplier for the ingredient must exist in Fourth. You can use the suppliers resource to do this.
 
This resource focuses on purchasing information, such as supplier and distributor details, unit types, cost and tax details, and ordering limits. As well, you can specify whether the ingredient is an alternate to an existing ingredient. 

To add category, intolerance, nutrient, priceband or conversion information for an ingredient, you need to use the individual resources for these. 

ingredientcategory

Adds categories for one or more ingredients.

The categories must already exist in Fourth. 

ingredientconversion Adds or updates conversion information for an ingredient. You can remove a conversion for a unit of measure by leaving the quantity and number values empty.
ingredientintolerance

Adds or updates ingredient intolerances for one or more ingredients.

You can remove an intolerance by setting the IntoleranceValue to null.

ingredientnutrient

Adds or updates ingredient nutrition details for one or more ingredients. 

You can remove nutrition details by setting the NutrientValue to null.

ingredientpriceband Adds or updates an ingredient’s price band details.
suppliers Adds or updates one or more suppliers. 

Request header

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

POST /ingredients HTTP/1.1
Host: instance.example.com
Accept: text/json
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Field Description
Authorization

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

Accept The data format you are using for the request. Options are: application/json, text/json, application/xml, text/xml.

Request body

For details about what is required in the request body, see the reference and the examples below.

Response to requests

Successful requests

Successful POST requests receive an HTTP 202 Accepted response with an empty response body.

Unsuccessful requests

Unsuccessful requests receive an HTTP 400-599 response, with an error message in the response body. See the error messages for each of these requests: 

Making suppliers requests

Before you can start adding ingredients, you need to make sure the ingredient supplier exists in Fourth. You can do this using the suppliers resource. 

This example request adds a new supplier. The accountNumber is your unique reference for the supplier. The SupplierCurrencyCode is in standard ISO 4217 codes. 

POST /suppliers  HTTP/1.1
Host: instance.example.com
Content-Type: application/json
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

[
{
   "AccountNumber": "ACME12346",
   "SupplierName": "Chris's produce", 
   "AlternateSupplierName": "CHRISPRO",
   "CountryGuid": "example",
   "SupplierCurrencyCode": "GBP"
}
]

Note that CountryGuid is optional as it is not required for most use cases. The value is a Fourth ID for the country.

Making ingredient requests

Use the ingredient resource to add or update an ingredient. You need to include the ingredient sets to which the ingredient belongs, and the ingredient's supplier (and both the sets and suppliers must already exist in Fourth). 

Simple example

POST /ingredient  HTTP/1.1
Host: instance.example.com
Content-Type: application/xml
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

<ArrayOfIngredient>
   <Ingredient>
      <IngredientName>Ribs</IngredientName>
      <SupplierName>Butcher</SupplierName>
      <SupplierCode>SupplierCode1</SupplierCode>
      <SupplyQuantity>6.0000</SupplyQuantity>
      <SupplyQuantityUnit>kilogram</SupplyQuantityUnit>
      <IngredientType>Food</IngredientType>
      <CostPrice>20.0000</CostPrice>
      <InternalCode>2008</InternalCode>
      <IngredientSets>
         <Set>Master Ingredients</Set>
      </IngredientSets>
      <SupplyQuantityNumber>2.0000</SupplyQuantityNumber>
   </Ingredient>
</ArrayOfIngredient>

Alternate ingredients

You can use this resource to add alternate ingredients. Alternate ingredients are always linked to a parent ingredient, so in the request you will need to specify the parent ingredient.  

Alternate ingredients can come from the same or different suppliers from the parent ingredient.

Example with alternate ingredients data

</ArrayOfIngredient>
   <Ingredient>
      <IngredientName>ApiAlternateAutomation Ingredient 021</IngredientName>
      <SupplierName>Dairy</SupplierName>
      <SupplierCode>B391</SupplierCode>
      <SupplyQuantity>12.0000</SupplyQuantity>
      <SupplyQuantityUnit>gram</SupplyQuantityUnit>
      <CostPrice>12.5000</CostPrice>
      <IngredientType>Food</IngredientType>
      <InternalCode>1007</InternalCode>
      <IngredientSets>
         <Set>Test 1</Set>
         <Set>Test 2</Set>
         <Set>Test 3</Set>
      </IngredientSets>
      <SupplyQuantityNumber>1.0000</SupplyQuantityNumber>
      <ParentSupplierName>Dairy</ParentSupplierName>       
      <ParentSupplierCode>B600</ParentSupplierCode>
      <RankOrder>2</RankOrder>
      <ParentStarChefKey>0036858</ParentStarChefKey>
   </Ingredient> 
</ArrayOfIngredient>

AlternativeUnit values

These elements are used with Fourth Inventory: AlternativeUnit1Quantity, AlternativeUnit1Uom, AlternativeUnit1Descriptor, AlternativeUnit2Quantity, AlternativeUnit2Uom and AlternativeUnit2Descriptor.

They create an alternative stock count unit in the Inventory system for the ingredient. If you need to use these values please contact your Fourth Implementation Consultant. 

Example with all stock compatibility values

<ArrayOfIngredient>
   <Ingredient>
      <IngredientName>Ribs</IngredientName>
      <SupplierName>Butcher</SupplierName>
      <SupplierCode>SupplierCode1</SupplierCode>
      <SupplyQuantity>6.0000</SupplyQuantity>
      <SupplyQuantityUnit>kilogram</SupplyQuantityUnit>
      <IngredientType>Food</IngredientType>
      <CostPrice>20.0000</CostPrice>
      <InternalCode>2008</InternalCode>
      <IngredientSets>
         <Set>Test 1</Set>
         <Set>Test 2</Set>
         <Set></Set>
      </IngredientSets>
      <SupplyQuantityNumber>2.0000</SupplyQuantityNumber>
      <DistributorName>Dairy</DistributorName>
      <DistributorCode>Dairy001</DistributorCode>
      <ExternalCode>EXTCODE01</ExternalCode>
      <SupplyQuantityDescriptor>case</SupplyQuantityDescriptor>
      <UnitSizeNumber>10</UnitSizeNumber>
      <UnitSizeUom>ounce</UnitSizeUom>
      <UnitSizeUomDescriptor>Case</UnitSizeUomDescriptor>
      <CostModel>Highest</CostModel>
      <IsAdjustmentItem>True</IsAdjustmentItem>
      <PreventUsageInRecipes>False</PreventUsageInRecipes>
      <TransferRequisitionStatus>False</TransferRequisitionStatus>
      <ExcludeFromGP>False</ExcludeFromGP>
      <ZeroStockCount>True</ZeroStockCount>
      <ItemVatable>Yes</ItemVatable>
      <FirstDelivery>2017-06-28</FirstDelivery>
      <BinNumber>12134</BinNumber>
      <MaxOrderQuantity>50</MaxOrderQuantity>
      <MinOrderQuantity>5</MinOrderQuantity>
      <AlternativeUnit1Quantity>5</AlternativeUnit1Quantity>
      <AlternativeUnit1Uom>centilitre</AlternativeUnit1Uom>
      <AlternativeUnit1Descriptor>Bottle</AlternativeUnit1Descriptor>
      <AlternativeUnit2Quantity>1000</AlternativeUnit2Quantity>
      <AlternativeUnit2Uom>milligram</AlternativeUnit2Uom>
      <AlternativeUnit2Descriptor>Box</AlternativeUnit2Descriptor>
     <SupplierOrderUom>CS</SupplierOrderUom>
     <InvoiceUom>CS</InvoiceUom>
     <InvoicePrice>7.55</InvoicePrice>
   </Ingredient>
</ArrayOfIngredient>

Unit Code (UnitSizeUom) values 

These are the possible values you can set for UnitSizeUom.

UnitSizeUom values Unit code that appears in UI

litre

l

millilitre

ml

kilogram

kg

gram

g

floz (US)

floz (US)

tbsp (US)

tbsp (US)

tsp (US)

tsp (US)

pound

lb

ounce

oz

milligram

mg

pint (UK)

pt (UK)

quart (UK)

qt (UK)

single

single

centilitre

cl

slice

slice

loaf

loaf

serving(s)

serving

cup (US)

cup (US)

cup (UK)

cup (UK)

floz (UK)

floz (UK)

gallon (US)

gal (US)

gallon (UK)

gal (UK)

gill (US)

gill (US)

gill (UK)

gill (UK)

pint (US)

pt (US)

quart (US)

qt (US)

tbsp (UK)

tbsp (UK)

tsp (UK)

tsp (UK)

tsp

tsp

tbsp

tbsp

stone

stone

bottle

btl

tin

tin

clove

clv

bunch

bnch

each

ea

piece

piece

UnitSizeUomDescriptor values

These are the possible values you can set for UnitSizeUomDescriptor.

Valid UoM descriptors to be used for import

Bottle

Case

Box

Bag

Pack

Carton

Keg

Can

Jar

Punnet

Each

Bunch

Tin

Container

Tub

Bucket

Roll

Sleeve

Portion

Sheet

Error messages for ingredients

Error Message Description

Ingredient Name is mandatory and must be less than 150 characters.

Ingredient name missing or too long.

Supplier Name does not exist in StarChef or Value is missing.

Supplier Name value not provided or does not exist in StarChef.

Supplier Code is mandatory and must be less than 50 characters.

Supplier Code value missing or too long.

Supply Quantity Number is mandatory and must be valid decimal value.

Supply Quantity Number value missing or incorrect format.

Supply Quantity Quantity is mandatory and must be valid decimal value.

Supply Quantity Quantity value missing or incorrect format.

Cost Price is mandatory and must be valid decimal value.

Cost Price value missing or invalid format.

Ingredient Set(s) does not exist in StarChef or Value is missing.

Ingredient set value not provided or does not exist in StarChef.

Multiple Records exist with same Supplier Name and Supplier Code combination.

Trying to import the same ingredient (defined by the combination of Supplier Name and Supplier Code) more than once or ingredient already exists in StarChef.

Multiple Records exist with same Distributor Name and Distributor code combination.

Trying to import the same ingredient (defined by the combination of Distributor Name and Distributor Code) more than once or ingredient already exists in StarChef.

Ingredient Type could be only food or non-food.

Trying to import an ingredient with type different than food or non-food.

External Code must be less than 50 characters.

External code contains more than 50 characters.

Supply Quantity descriptor does not exist in StarChef or Value is missing.

Supplier Quantity Descriptor value doesn't exists in StarChef.

Unit Size number must be valid decimal value.

Unit Size number value is not a decimal value.

Unit Size UoM does not exist in StarChef or Value is missing

Unit Size UoM value doesn't exist in the StarChef UoM table. See the UnitSizeUom table for valid values. 

Unit Size UoM descriptor does not exist in StarChef or Value is missing.

Unit Size UoM Descriptor value doesn't exists in StarChef. See the UnitSizeUomDescriptor table for valid values. 

Cost model does not exist in StarChef or Value is missing.

Cost Model value doesn't exist in StarChef.

Flag Adjustment Item value is not Boolean.

Is Adjustment Item value is not entered as True or False.

Flag Prevent Usage in Recipes value is not Boolean.

Prevent Usage in Recipes value is not entered as True or False.

Transfer Requisition Status value is not Boolean.

Transfer Requisition Status value is not entered as True or False.

Exclude from GP value is not Boolean.

Exclude From GP value is not entered as True or False.

Zero Stock Count value is not Boolean.

Zero Stock Count value is not entered as True or False.

Item Vatable does not exist in StarChef or Value is missing.

Item Vatable value is not entered as Yes, No or - .

First delivery must be valid date value.

Date into Warehouse value is not entered in the correct format yyyy-mm-dd.

Max order quantity must be valid decimal value.

Maximum Order Quantity value is not entered as a decimal value.

Min order quantity must be valid decimal value.

Minimum Order Quantity value is not entered as a decimal value.

Alternative Unit1 quantity must be valid decimal value.

Alternative Unit1 quantity value is not entered as a decimal value.

Alternative Unit1 UoM does not exist in StarChef or Value is missing.

Alternative Unit1 UoM value doesn't exist in the StarChef UoM table.

Alternative Unit1 descriptor does not exist in StarChef or Value is missing.

Alternative Unit1 descriptor value doesn't exist in StarChef.

Alternative Unit2 quantity must be valid decimal value.

Alternative Unit2 quantity value is not entered as a decimal value.

Alternative Unit2 UoM does not exist in StarChef or Value is missing.

Alternative Unit2 UoM value doesn't exist in the StarChef UoM table.

Alternative Unit2 descriptor does not exist in StarChef or Value is missing.

Alternative Unit2 descriptor value doesn't exist in the StarChef descriptor table.

Supplier Order UoM does not exist in StarChef or Value is missing.

Supplier Order UoM value is not one of the valid values: CS, EA, KGM.

Invoice UoM does not exist in StarChef or Value is missing.

Invoice UoM value is not one of the valid values: CS, EA, KGM.

Invoice Price must be valid decimal value

Invoice Price value is not entered as a decimal value.

Parent Supplier Name does not exist in StarChef or Value is missing.

Parent Supplier Name value is not provided or does not exist in StarChef.

Parent Supplier Name and Parent Supplier Code combination is not full

Either Parent Supplier Name value is not provided or does not exist in StarChef or the Supplier Code value is not provided.

Parent Supplier StarChef Key does not exist or Value is missing.

StarChef Key value is not provided or is not valid.

Parent Supplier Name must be less than 150 characters.

Parent Supplier Name value should not exceed 150 characters.

Parent Supplier Code must be less than 50 characters.

Parent Supplier Code value should not exceed 50 characters.

Rank Order is not valid number.

Rank Order should be a valid number.

Multiple Records exist with the same rank order.

Two or more alternate ingredients that are associated with the same parent ingredient cannot be imported with the same rank order.

Supplied Unit name is not part of the family.

Unit of measure of the alternate ingredient must correspond to the parent unit of measure.

Making ingredientnutrient requests

Use ingredientnutrient to add nutrition details for an ingredient.

If you need to remove a nutrient from an ingredient's information, send in the nutrient with no value (or null) for NutrientValue.  

In this example, the request adds two nutrients (Energy_KJ and Cal_Carb_Pct), and removes one (Caffeine) from the ingredient CHRI332

POST /ingredientnutrient  HTTP/1.1
Host: instance.example.com
Content-Type: application/xml
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

<ArrayOfIngredientNutrient>
   <IngredientNutrient>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRI332</SupplierCode>
      <NutrientName>Energy_KJ</NutrientName>   
      <NutrientValue>10.235</NutrientValue>
   </IngredientNutrient>
   <IngredientNutrient>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRI332</SupplierCode>
      <NutrientName>Cal_Carb_Pct</NutrientName>   
      <NutrientValue>6.115</NutrientValue>
   </IngredientNutrient>
   <IngredientNutrient>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRI332</SupplierCode>
      <NutrientName>Caffeine</NutrientName>   
      <NutrientValue></NutrientValue>
   </IngredientNutrient>
</ArrayOfIngredientNutrient>

Nutrient values table

NutrientName Display Description on Starchef Screen

Cal_Carb_Pct

% Calories from Carbohydrate

Cal_Fat_Pct

% Calories from Fat

Cal_MUFA_Pct

% Calories from Monounsaturated Fatty Acid (MUFA)

Cal_PUFA_Pct

% Calories from Polyunsaturated Fatty Acid (PUFA)

Cal_Prot_Pct

% Calories from Protein

Cal_SatFat_Pct

% Calories from Saturated Fat (SFA)

Alpha_Tocopherol

Alpha Tocopherol (mg)

Biotin

Biotin (μg)

Caffeine

Caffeine (mg)

Calcium

Calcium (mg)

Cal_Details

Calorie Breakdown

Cal_Fat

Calories from Fat

Cal_SatFat

Calories from Saturated Fat

Carb

Carbohydrate

Carotene

Carotene (μg)

Carotene_alpha

Carotene, alpha (μg)

Carotene_beta

Carotene, beta (μg)

Chloride

Chloride (mg)

Fat_Chol_mg

Cholesterol (mg)

Choline

Choline (mg)

Chromium

Chromium (μg)

Copper

Copper (mg)

Cryptoxanthins

Cryptoxanthins (μg)

Energy_kCal

Energy (kcal)

Energy_KJ

Energy (kJ)

Fat_sol

Fat soluble vitamins

Fibre_AOAC

Fibre (AOAC)

Fibre_NSP

Fibre (NSP)

Fluoride

Fluoride (mg)

Folate

Folate, food (μg)

Folic_Acid

Folic Acid (Folate) (μg)

Fructose

Fructose

Glucose

Glucose

Iodine

Iodine (μg)

Iron

Iron (mg)

Lactose

Lactose

Lutein_zeaxanthin

Lutein + zeaxanthin (μg)

Lycopene

Lycopene (μg)

Magnesium

Magnesium (mg)

Maltose

Maltose

Manganese

Manganese (mg)

Mineral

Minerals

Molybdenum

Molybdenum (μg)

Fat_Mono

mono-unsaturates

Niacin

Niacin (mg)

NMES

NMES

Pantothenic_Acid

Pantothenic acid (mg)

Phosphorus

Phosphorus (mg)

Fat_Poly

poly-unsaturates

Potassium

Potassium (mg)

Protein

Protein

Retinol

Retinol (μg)

Riboflavin

Riboflavin (mg)

Fat_Sat

saturates

Selenium

Selenium (μg)

Sodium

Sodium (mg)

Carb_Starch

starch

Sucrose

Sucrose

Thiamin

Thiamin (mg)

Fat

Total Fat

Carb_Sugars

total sugars

Vitamin_A_μg

Vitamin A (μg)

Vitamin_A

Vitamin A (IU)

Vitamin_A_RE

Vitamin A (RE)

Vitamin_B12

Vitamin B12 (μg)

Vitamin_B6

Vitamin B6 (mg)

Vitamin_C

Vitamin C (mg)

Vitamin_D

Vitamin D (μg)

Vitamin_D_IU

Vitamin D (IU)

Vitamin_E

Vitamin E (mg)

Vitamin_K1

Vitamin K1 (μg)

Water

Water

Water_sol

Water soluble vitamins

Zinc

Zinc (mg)

Error messages for ingredientnutrient 

Error Message Description
Supplier Name does not exist in StarChef or Value is missing. Supplier Name value is missing or does not exist in StarChef.
Supplier Code is mandatory and must be less than 50 characters. Supplier Code value missing or too long.
No ingredient exists for this Supplier Name and Supplier Code combination. Such ingredient does not exist.
Invalid nutrient name. Incorrect nutrient name. 
Invalid nutrient value. Nutrient value is not in the correct format.
Duplicate nutrient_name. Trying to update the same nutrient value twice.

Making ingredientintolerance requests

Use ingredientintolerance to add intolerance details for an ingredient.

If you need to remove an intolerance from an ingredient's information, send in the intolerance with IntoleranceValue set to null.  

In this example, the request adds two intolerances and removes one from the ingredient CHRI201

POST /ingredientintolerance  HTTP/1.1
Host: instance.example.com
Content-Type: application/xml
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

<ArrayOfIngredientIntolerance>
   <IngredientIntolerance>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRI201</SupplierCode>
      <IntoleranceCode>AddSalt</IntoleranceCode> 
      <IntoleranceValue>Yes</IntoleranceValue>
   </IngredientIntolerance>
   <IngredientIntolerance>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRI201</SupplierCode>
      <IntoleranceCode>Nuts</IntoleranceCode> 
      <IntoleranceValue>May</IntoleranceValue>
   </IngredientIntolerance>
   <IngredientIntolerance>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRI201</SupplierCode>
      <IntoleranceCode>AddSalt</IntoleranceCode> 
      <IntoleranceValue>null</IntoleranceValue>
   </IngredientIntolerance>
</ArrayOfIngredientIntolerance>

Intolerance values table

IntoleranceCode - API Import Display Description on StarChef Screen

Glutamates

Contains Added Glutamates

AddSalt

Contains Added Salt

AddedTransFats

Contains Added Trans Fats

OtherAdditives

Contains Additives

Alcohol

Contains Alcohol or Alcohol Based Products

AnimalFat

Contains Animal Fat (excluding milk fat)

AnimalProd

Contains Animal Products (excluding rennet free milk products)

ArtCol

Contains Artificial Colours

ArtFlav

Contains Artificial Flavours

Preserv

Contains Artificial Preservatives

ArtSweet

Contains Artificial Sweeteners

Azo

Contains Azo Dyes

Benz

Contains Benzoates (if greater than 1mg/kg or l)

BHA_BHT

Contains BHA/BHT (if greater than 1mg/kg or l)

Celery

Contains Celery / Celeriac Products

Wheat

Contains Cereals that Contain Gluten

Coconut

Contains Coconut

Crustaceans

Contains Crustaceans

E110_E102_E122_E124_E104_E129

Contains E110/E102/E122/E124/E104/E129

E211_Sodium_Benzoate

Contains E211 Sodium Benzoate

Egg

Contains Eggs / Egg Derivatives

Fish

Contains Fish or Fish Products

FlavEnhan

Contains Flavour Enhancers

GM

Contains G.M. Material / Ingredients

Garlic_Onions

Contains Garlic / Onion Products

Gluten

Contains Gluten or Gluten Products

HydrogenatedVegOils

Contains Hydrogenated Vegetable Oils >1%

Irradiated

Contains Irradiated Food

Lactose

Contains Lactose

Lupin

Contains Lupin Flour / Lupin Products

Maize

Contains Maize or Maize Derivatives

Milk

Contains Milk or Milk Products

ModifiedStarch

Contains Modified Starch

Molluscs

Contains Molluscs

MSG

Contains MSG

Mushrooms

Contains Mushrooms or Mushroom Products

Mustard

Contains Mustard or Mustard Products

NatFlav

Contains Natural Flavourings

Nuts

Contains Nuts or Nut Trace

NatCol

Contains Only Natural Colours

Seeds

Contains Seeds / Seed Oil

Sesame

Contains Sesame Seed or Sesame Seed Products

ShellFish

Contains Shellfish

Soya

Contains Soya

Sulph_Diox

Contains Sulphur Dioxide/Sulphites

Organic

Organically Produced

Coeliacs

Suitable for Coeliacs

Halaal

Suitable for Halaal Diet

Kosher

Suitable for Kosher Diet

LactoseIntol

Suitable for Lactose Intolerants

Vegan

Suitable for Vegans

Veg

Suitable for Vegetarians

Barley

Barley

Chestnuts

Chestnuts

Sulphites

Contains Sulphites

Sulph

Contains Sulphur Dioxide (if greater than 10mg/kg)

CottonSeed

Cotton seed

Kamut

Kamut (Wheat)

Oats

Oats

OtherNuts

Other

OtherSeeds

Other

Peanuts

Peanuts

PineNuts

Pine Nuts

PoppySeed

Poppy Seed

Rye

Rye

SeedOils

Seed Oils

Spelt

Spelt (Wheat)

SunflowerSeed

Sunflower Seed

TreeNuts

Tree Nuts

CerealsWheat

Wheat

Almonds

Almonds

BrazilNuts

Brazil Nuts

CashewNuts

Cashew Nuts

Hazelnuts

Hazelnuts

Macadamias

Macadamia or Queensland Nuts

PecanNuts

Pecan Nuts

Pistachios

Pistachios

Walnuts

Walnuts

Error messages for ingredientintolerance

Error Message Description
Supplier Name does not exist in StarChef or Value is missing. Supplier Name value is missing or does not exist in StarChef.
Supplier Code is mandatory and must be less than 50 characters. Supplier Code value missing or too long.
No ingredient exists for this Supplier Name and Supplier Code combination. Such ingredient does not exist.
Intolerance value is invalid. Intolerance value must be yes / no / may / null.
Intolerance Code does not exist in Starchef or Value is missing Intolerance code missing or incorrect. See the intolerance values table for possible values.

Making ingredientcategory requests

The ingredientcategory resource lets you add categories to an ingredient. 

The Fourth Purchase to Pay & Inventory system has a hierarchy of user-defined categories. You can include the top three levels in this request, which are:

  1. Category Type
  2. Main Category
  3. SubCategory 

Before you can add an ingredient to ingredient categories, the categories must already exist in Fourth. You can use the Recipe & Menu Engineering Export API to retrieve a list of existing categories. 

An ingredient may have more than one category applied to it. In which case, one of the categories must become the default category for the ingredient. 

 <ArrayOfIngredientCategory>
   <IngredientCategory>
       <SupplierName>Chris's produce</SupplierName>
       <SupplierCode>CHRI103</SupplierCode>
       <CategoryTypeName>Cost Center</CategoryTypeName>
       <MainCategoryName>Food</MainCategoryName>
       <SubCategoryName>Vegetables</SubCategoryName>
       <IsDefault>yes</IsDefault>
   </IngredientCategory>
</ArrayOfIngredientCategory>

Error messages for ingredientcategory

Error Message Description

Supplier Name does not exist in StarChef or Value is missing.

Supplier Name value not provided or does not exist in StarChef.

Supplier Code is mandatory and must be less than 50 characters.

Supplier Code value is missing or too long.

Category type does not exist in Starchef or Value is missing.

Missing Category Type value or Category Type does not exist in StarChef.

Required Ingredient Category Type not found.

Mandatory Category Type not provided for the ingredient.

Invalid category tree structure provided.

All provided categories exist but structure is incorrect.

is_default value is invalid

Incorrect is_default value.

Invalid category for alternate ingredients

Category provided is applicable only for parent ingredients.

Categories cannot be set for alternate ingredients inherited from parent ingredients

Alternates with "Inherit Parent Values" cannot have category value updated.

Making ingredientconversion requests

This request adds or updates conversion information for an ingredient.

Conversions let you take the unit of measure for purchasing (the "supply quantity") and provide a more recipe-friendly unit of measure elsewhere in Fourth. 

In the screenshot:

  • quantity is the left column (values 1, 1, and 1)
  • number is the middle (values: 800, 1 and 12) 

Screenshot showing example conversions in the Fourth user interface

To remove a conversion for a unit of measure, leave the quantity and number values empty. You can only delete conversions that are not in use. 

For a list of unit of measures for UnitCode, see the UnitSizeUom values table

The following example shows the same ingredient having two new conversions added (for piece and cup), and one removed (for btl). 

POST /ingredientconversion  HTTP/1.1
Host: instance.example.com
Content-Type: application/xml
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

<ArrayOfIngredientConversion>
   <IngredientConversion>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRIS201</SupplierCode>
      <UnitCode>piece</UnitCode>
      <Quantity>8</Quantity>
      <Number>1</Number>
   </IngredientConversion>
   <IngredientConversion>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRIS201</SupplierCode>
      <UnitCode>cup</UnitCode>
      <Quantity>4</Quantity>
      <Number>1.5</Number>
   </IngredientConversion>
   <IngredientConversion>
      <SupplierName>Chris's produce</SupplierName>
      <SupplierCode>CHRIS201</SupplierCode>
      <UnitCode>btl</UnitCode>
      <Quantity></Quantity>
      <Number></Number>
   </IngredientConversion>
</ArrayOfIngredientConversion>

Error messages for ingredientconversion 

Error Message Description

Invalid product.

The combination of Supplier Name value and Supplier Code value does not exist in StarChef.

Supplier Name does not exist in StarChef or Value is missing.

Supplier Name value not provided or does not exist in StarChef.

Supplier Code is mandatory and must be less than 50 characters.

Supplier Code value missing or too long.

Invalid UoM name

UoM UnitCode missing or incorrect. See the UnitSizeUom values table for a list of possible values.

Invalid UoM quantity value.

UoM Quantity value incorrect.

Missing UoM quantity value.

UoM Quantity value is missing.

Invalid UoM number value.

UoM Number value is incorrect.

Missing UoM number value.

UoM Number value is missing.

Duplicate UoM Conversion.

UoM conversion for this particular UoM already exists.

Duplicate UoM Weight. Only one Weight UoM per ingredient is allowed.

Only one Weight UoM per ingredient is allowed.

Duplicate UoM Volume. Only one Volume UoM per ingredient is allowed.

Only one Volume UoM per ingredient is allowed.

Unable to delete non-existent UoM Conversion.

Trying to delete UoM conversion that does not exist.

Unable to delete UoM Conversion. It is used in recipe/menu/alternates.

Trying to delete UoM conversion which is used in another item, remove the usage first.