Submit Initial Pack Events
Method: POST
/events/initial-pack
As a Customer of iFoodDS, you use the iFoodDS Initial Pack API to send FSMA 204 Initial Pack data to the iFoodDS Trace Exchange platform. Records will be stored for a minimum of two years.
info
This endpoint is being refined and thus subject to change. These docs will update when changes are made.
Request
Type: application/json
The body of the request comprises three main sections: the productMasterDataList, the locationMasterList, and the eventList. The first two sections are there to reduce the duplication of data you need to provide for the eventList.
{
"productMasterDataList": [
{
"itemCode": "<item code>",
"itemDescription": "<item description>",
"isFtlItem": true,
"ftlCategory": "<FTL (Food Traceability List) category>",
"brandName": "<brand name>",
"packStyle": "<pack style>",
"packSize": "<pack size>",
"productCommodity": "<product commodity>",
"productVariety": "<product variety>",
"scientificName": "<scientific name>",
"acceptableSpeciesName": "<acceptable species name>",
"gtin": "<GTIN (Global Trade Item Number)>",
"itemUpc": "<item UPC (Universal Product Code)>",
"innerPackUpc": "<inner pack UPC>",
"plu": "<PLU (Price Look-up)>",
"alternateItemCode": "<alternate item code>",
"isCoveredByGdst": true
}
],
"locationMasterList": [
{
"locationName": "<location name>",
"locationCode": "<location code>",
"locationType": "<location type>",
"parentLocationId": "<parent location id>",
"gln": "<GLN (global location number)>",
"glnAssignedBy": "<GLN assigned by>",
"duns": "<DUNS number>",
"alternateLocationCode": "<alternate location id>",
"phoneNumber": "<phone number>",
"isPrimaryLocation": true,
"isCoveredByGdst": false,
"address": {
"streetAddress1": "<street address 1>",
"streetAddress2": "<street address 2>",
"city": "<city>",
"state": "<state>",
"postalCode": "<postal code>",
"country": "<country code>"
},
"geoLocation": {
"gpsCoordinates": [
"<latitude>",
"<longitude>"
],
"geoFence": [
[
"<latitude1>",
"<longitude1>"
],
[
"<latitude2>",
"<longitude2>"
]
]
}
}
],
"eventList": [
{
"workOrderNumber": "<work order number>",
"eventDateTime": "<event date time>",
"initialPackingLocationId": "<initial packing location id>",
"racsUsedInInitialPacking": [
{
"woLineNumber": "<work order line number>",
"racProductId": "<raw agricultural commodity product id>",
"racUsedQuantity": <raw agricultural commodity used quantity>,
"racUsedUom": "<raw agricultural commodity used uom>",
"harvestFarmLocationId": "<harvest farm location id>",
"harvestFieldLocationId": "<harvest field location id>",
"harvestPondLocationId": "<harvest pond location id>",
"harvestCompany": "<harvest company>",
"harvestCompanyPhone": "<harvest company phone>",
"harvestDate": "<harvest date>",
"coolingLocationId": "<cooling location id>",
"coolingDate": "<cooling date>",
}
],
"foodsProducedInInitialPacking": {
"woLineNumber": "<work order line number>",
"foodProducedProductId": "<food produced product id>",
"foodProducedLotNumber": "<food produced lot number>",
"foodProducedCaseGtin": "<food produced case gtin>",
"foodProducedQuantity": <food produced quantity>,
"foodProducedUom": "<food produced uom>",
"foodProducedExpirationDate": "<food produced expiration date>",
"foodProducedProductionDate": "<food produced production date>",
"foodProducedPackagingDate": "<food produced packaging date>",
"foodProducedBestBeforeDate": "<food produced best before date>",
"foodProducedHarvestDate": "<food produced harvest date>"
}
}
]
}
Data Constraints
Please note the following data constraints:
stringsallow a maximum of 100 charactersdatesmust use the format:yyyy-MM-dddatetimesmust use the format:yyyy-MM-ddTHH:mm:ssZ(UTC) oryyyy-MM-ddTHH:mm:ss-hh:00(UTC minus) oryyyy-MM-ddTHH:mm:ss+hh:00(UTC plus)
Product Data
Required
itemCode(string): The vendor or purchaser item code that will be referenced in the eventitemDescription(string): Product Description from the product owner or original purchase order
Additional information will be required in the eventList section.
Optional
alternateItemCode(string): This field provides sender and shipper to use and alternate identifier for products. This could be a URL, a UUID, or other globally unique identification scheme. The important thing is that it is unique per product and shared between shipper and receiver. For example, this could be a GS1 Digital Link URL for the productgtin(string): Case-level Global Trade Identification Number (GTIN-14). GS1 GTIN Executive SummaryitemUpc(string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive SummaryinnerPackUpc(string): Point of sale barcode, may be GTIN-8, GTIN-12, GTIN-13, or GTIN-14. GS1 GTIN Executive Summaryplu(string): Item-level Price Look-up Code. PLU Codes Search — IFPSisFtlItem(boolean): Indicates whether product is on the Food Traceability List (FTL)ftlCategory(string)*: Indicates the product's FTL category, i.e. “soft cheese”, “shell eggs”, “nut butter”, “cucumbers”, “herbs”, “leafy greens”, “melons”, “peppers”, “sprouts”, “tomatoes”, “tropical tree fruits”, “fresh-cut fruits”, “fresh-cut vegetables”, “finfish”, “smoked finfish”, “crustaceans”, “molluscan shellfish”, “ready-to-eat deli salads”, or “multiple-ftl-ingredients” *Required if on the FTL -brandName(string): The brand of the product that appears on the consumer packagepackStyle(string): Product's pack style, e.g. "Case", "Carton", "Tray", "Clamshell", etc.packSize(string): Product's pack size as Packaging Configuration OR Count OR Weight + Unit of Measure, e.g. "20 x 12 oz bags"productCommodity(string): For fresh produce, a description of the commodity, e.g. "Peppers"productVariety(string): For fresh produce a description of the variety when applicable, e.g. "Jalapeno"scientificName(string): For seafood the scientific name of the species, see: FDA Seafood ListacceptableSpeciesName(string): For seafood a description of the common species name, see: FDA Seafood ListisCoveredByGdst(boolean): Flag to indicate that product is part of GDST
Location Data
Required
locationName(string): Name of vendor's or purchaser's location referenced in the eventlocationCode(string): Vendor's or purchaser's location code referenced in the event
If address and contact information is already set up in master data with locationCode, then the address information is not required. Otherwise, it is required. Provide at least one of the following:
gln(string): GS1 Global Location Number, a 13-digit string. GS1 GTIN Executive Summaryduns(string): Dun & Bradstreet Data Universal Numbering System number, a 9-digit stringaddress(object):streetAddress1(string): Physical street address line 1 informationstreetAddress2(string): Physical street address line 2 information, if applicablecity(string): City locationstate(string): State or region locationpostalCode(string): ZIP or postal codecountry(string): Country locationgeoLocationoptional (object): Consisting of either...gpsCoordinatesas anarray of stringsrepresenting the latitude followed by longitude expressed in degrees and minutes ORgeoFenceas anarray of string arraysrepresenting the latitude followed by longitude expressed in degrees and minutes for each set of coordinates defining the geo fence
Optional
locationType(string): Indicates whether the location is "Internal", "Supplier", or "Customer"parentLocationId(string): To create a hierarchy of locations (divisions, regions, etc.), use this field to point to the location’s parent locationglnAssignedBy(string): Indicates whether it was assigned by "GS1", "GLOBALGAP", "Internal", "Trading Partner", or "Other"alternateLocationCode(string): This field provides sender and shipper to use and alternate identifier for connecting locations. This could be a URL, a UUID, or other globally unique identification scheme. The important thing is that it is unique per location and is shared between shipper and receiver. For example, this could be a GS1 Digital Link or Google Place IDphoneNumber(string)*: Phone number including country code with format: +1.999.999.999 *This field is required ifaddressis used to identify locationisPrimaryLocation(boolean): This indicates that the location is the primary headquarter location for the organizationisCoveredByGdst(boolean): Indicates that this location is covered by the Global Dialogue on Seafood Traceability requirements
Event Data
warning
When sending an event payload, the payload must contain the complete set of records for the corresponding event date time. DO NOT send more than one payload with the same event date time.
Required
workOrderNumber(string): The work order or production order number you assigned.eventDateTime(datetime): Date when initial packing is complete.racProductId(string): This is your internal Product ID for the raw agricultural commodity used in initial packing. This should be stored in your master data.racUsedQuantity(string): The number of units of this TLC used in Initial Packing.foodProducedProductId(string): This Product ID should be stored in your master data. If the cases you produce in initial packing are labeled with case GTIN-14s, the GTIN should be stored in the product master data record for the Product ID referenced.foodProducedLotNumber(string): This is the Lot Number for the foods produced in initial packing.foodProducedQuantity(number): The number of units of this TLC produced in initial packing.
One of the following is required, the others are Optional
foodProducedExpirationDate(date): Food Produced Expiration DatefoodProducedProductionDate(date): Food Produced Production DatefoodProducedPackagingDate(date): Food Produced Packaging DatefoodProducedBestBeforeDate(date): Food Produced Best Before DatefoodProducedHarvestDate(date): Food Produced Harvest Date
Optional
initialPackingLocationId(string): Location of initial packing.racUsedUom(string): Unit of measure (e.g., Case) for TLC received.harvestFarmLocationId(string): References a location set up in master data.harvestFieldLocationId(string): References a location set up in master data for the specific field where harvesting occurred.harvestPondLocationId(string): References a location set up in master data for the specific pond where harvesting occurred.harvestCompany(string): Name of the company that performed the harvesting.harvestCompanyPhone(string): Contact phone number for the harvest company.harvestDate(date): This is the date of harvest for the RAC.coolingLocationId(string): This points to the master data record for the cooling location (prior to initial packing).coolingDate(date): This is the date of cooling prior to initial packingwoLineNumber(string): This links the TLC to the line item on the work order.foodProducedCaseGtin(string): GTIN-14 of cases of food producedfoodProducedUom(string): Unit of measure (e.g., Case) produced in initial packing
Sample Payload
{
"productMasterDataList": [
{
"itemCode": "123",
"itemDescription": "Fresh Oysters",
"isFtlItem": true,
"ftlCategory": "seafood",
"brandName": "Sea Fresh",
"packStyle": "",
"packSize": "",
"productCommodity": "",
"productVariety": "",
"scientificName": "",
"acceptableSpeciesName": "",
"gtin": "",
"innerPackUpc": "",
"itemUpc": "",
"plu": "",
"alternateItemCode": "",
"isCoveredByGdst": true
},
{
"itemCode": "456",
"itemDescription": "Fresh Scallops",
"isFtlItem": true,
"ftlCategory": "seafood",
"brandName": "Sea Fresh",
"packStyle": "",
"packSize": "",
"productCommodity": "",
"productVariety": "",
"scientificName": "",
"acceptableSpeciesName": "",
"gtin": "01234567890123",
"innerPackUpc": "",
"itemUpc": "",
"plu": "",
"alternateItemCode": "2714-a",
"isCoveredByGdst": true
},
{
"itemCode": "123456",
"itemDescription": "Fresh Scallops/Oysters",
"isFtlItem": true,
"ftlCategory": "seafood",
"brandName": "Sea Fresh",
"packStyle": "",
"packSize": "",
"productCommodity": "",
"productVariety": "",
"scientificName": "",
"acceptableSpeciesName": "",
"gtin": "02345678901234",
"innerPackUpc": "",
"itemUpc": "",
"plu": "",
"alternateItemCode": "",
"isCoveredByGdst": true
}
],
"locationMasterList": [
{
"locationCode": "2790",
"locationType": "Internal",
"locationName": "Location 1",
"gln": "gln1",
"glnAssignedBy": "me",
"duns": "duns1",
"alternateLocationCode": "altid2480",
"phoneNumber": "+15555555555",
"isPrimaryLocation": true,
"isCoveredByGdst": true,
"parentLocationId": "3",
"address": {
"streetAddress1": "121 Seaway",
"streetAddress2": "Dock 121",
"city": "Seaside",
"state": "WA",
"postalCode": "99999",
"country": "USA"
},
"geoLocation": {
"gpsCoordinates": [
"36.271142",
"-78.593557"
],
"geoFence": [
[
"50.942499",
"6.898247"
],
[
"50.942275",
"6.898292"
],
[
"50.942263",
"6.898094"
],
[
"50.942106",
"6.898126"
],
[
"50.942130",
"6.898526"
],
[
"50.942512",
"6.898451"
],
[
"50.942499",
"6.898247"
]
]
}
},
{
"locationCode": "5596",
"locationType": "Internal",
"locationName": "Location 2",
"gln": "",
"glnAssignedBy": "",
"duns": "",
"alternateLocationCode": "altid2480",
"phoneNumber": "+15555555555",
"isPrimaryLocation": true,
"isCoveredByGdst": true,
"parentLocationId": "3",
"address": {
"streetAddress1": "121 Seaway",
"streetAddress2": "Dock 121",
"city": "Seaside",
"state": "WA",
"postalCode": "99999",
"country": "USA"
},
"geoLocation": {
"gpsCoordinates": [
"36.271142",
"-78.593557"
],
"geoFence": [
[
"50.942499",
"6.898247"
],
[
"50.942275",
"6.898292"
],
[
"50.942263",
"6.898094"
],
[
"50.942106",
"6.898126"
],
[
"50.942130",
"6.898526"
],
[
"50.942512",
"6.898451"
],
[
"50.942499",
"6.898247"
]
]
}
},
{
"locationCode": "07504550000005",
"locationType": "Customer",
"locationName": "Sea Farms R2",
"gln": "",
"glnAssignedBy": "",
"duns": "",
"alternateLocationCode": "",
"phoneNumber": "+15555555555",
"isPrimaryLocation": true,
"isCoveredByGdst": true,
"address": {
"streetAddress1": "1 Seaway",
"streetAddress2": "Dock 11",
"city": "Seaside",
"state": "WA",
"postalCode": "99999",
"country": "USA"
}
},
{
"locationCode": "2407",
"locationType": "Customer",
"locationName": "Location 3",
"gln": "",
"glnAssignedBy": "",
"duns": "",
"alternateLocationCode": "",
"phoneNumber": "+15555555555",
"isPrimaryLocation": true,
"isCoveredByGdst": true,
"address": {
"streetAddress1": "1 Seaway",
"streetAddress2": "Dock 11",
"city": "Seaside",
"state": "WA",
"postalCode": "99999",
"country": "USA"
}
},
{
"locationCode": "9874",
"locationType": "Customer",
"locationName": "Location 4",
"gln": "",
"glnAssignedBy": "",
"duns": "",
"alternateLocationCode": "",
"phoneNumber": "+15555555555",
"isPrimaryLocation": true,
"isCoveredByGdst": true,
"address": {
"streetAddress1": "1 Seaway",
"streetAddress2": "Dock 11",
"city": "Seaside",
"state": "WA",
"postalCode": "99999",
"country": "USA"
}
}
],
"eventList": [
{
"workOrderNumber": "w012345",
"eventDateTime": "2024-10-10T00:12:34Z",
"initialPackingLocationCode": "07504550000005",
"racsUsedInInitialPacking": [
{
"woLineNumber": "1",
"racItemCode": "123",
"racUsedQuantity": 4,
"racUsedUom": "Case",
"harvestFarmLocationCode": "2790",
"harvestFieldLocationCode": "5596",
"harvestPondLocationCode": "2407",
"harvestCompany": "HC Inc.",
"harvestCompanyPhone": "+15555551212",
"harvestDate": "2024-12-01",
"coolingLocationCode": "8974",
"coolingDate": "2024-12-01"
},
{
"woLineNumber": "2",
"racItemCode": "456",
"racUsedQuantity": 9,
"racUsedUom": "Case",
"harvestFarmLocationCode": "2790",
"harvestFieldLocationCode": "5596",
"harvestPondLocationCode": "2407",
"harvestCompany": "HC Inc",
"harvestCompanyPhone": "+15555550101",
"harvestDate": "2024-12-01",
"coolingLocationCode": "9874",
"coolingDate": "2024-12-01"
}
],
"foodsProducedInInitialPacking": {
"woLineNumber": "1",
"foodProducedItemCode": "123456",
"foodProducedLotNumber": "MM",
"foodProducedCaseGtin": "NN",
"foodProducedQuantity": 13,
"foodProducedUom": "Case",
"foodProducedExpirationDate": "2025-06-01",
"foodProducedProductionDate": "2025-01-02",
"foodProducedPackagingDate": "2025-02-01",
"foodProducedBestBeforeDate": "2025-03-01",
"foodProducedHarvestDate": "2025-01-01"
}
},
{
"workOrderNumber": "w454151",
"eventDateTime": "2024-10-10T00:13:34Z",
"initialPackingLocationCode": "07504550000005",
"racsUsedInInitialPacking": [
{
"woLineNumber": "1",
"racItemCode": "123",
"racUsedQuantity": 4,
"racUsedUom": "Case",
"harvestFarmLocationCode": "2790",
"harvestFieldLocationCode": "5596",
"harvestPondLocationCode": "2407",
"harvestCompany": "WE FISH",
"harvestCompanyPhone": "+15555541154",
"harvestDate": "2024-12-01",
"coolingLocationCode": "2790",
"coolingDate": "2024-12-01"
}
],
"foodsProducedInInitialPacking": {
"woLineNumber": "1",
"foodProducedItemCode": "123456",
"foodProducedLotNumber": "145154-1",
"foodProducedCaseGtin": "",
"foodProducedQuantity": 130,
"foodProducedUom": "Case",
"foodProducedExpirationDate": "2025-06-01",
"foodProducedProductionDate": "2025-01-02",
"foodProducedPackagingDate": "2025-02-01",
"foodProducedBestBeforeDate": "2025-03-01",
"foodProducedHarvestDate": "2025-01-01"
}
}
]
}
Response
- 200
- 400
Initial Pack data ingested successfully
{
"request_ids": ["e8107014-7b89-48b7-83bd-aaa4fb21ece0"]
}
Description of what user-fixable validation error occurred and in what part of the payload
{
"detail": "'eventDateTime' is a required property - 'eventList.0'",
"status": 400,
"title": "Bad Request",
"type": "about:blank"
}