Skip to main content

Update Shipping Event

Method: PUT
/data-provider/events/shipping/{id}

As a Data Provider in the iFoodDS partner program, you use the iFoodDS Ship Event API to update FSMA 204 ship event data on behalf of shared customers to the iFoodDS Trace Exchange platform. This streamlines the capture and sharing of customer’s FSMA 204 ship event data promoting efficiency for our shared customers.

Event 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 {id} of the path is the event ID retrieved from:

  1. Completion of a succesful POST. Example: "request_ids": ["9ed5911f-f6a4-4ba2-9eb4-d6428237be28"]
  2. Within the payload results of a GET. Example: "id": "7b5c43c3-3526-4135-a602-0e3979c21d88"

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>",
            "businessUnit": "<business unit>",
            "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>",
            "businessUnit": "<business unit>",
            "market": "<market>",
            "region": "<region>",
            "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": {
        "dataProviderVendorId": "<data provider vendor id>",
        "dataProviderVendorName": "<data provider vendor name>",
        "purchaseOrderDate": "<purchase order date>",
        "purchaseOrderNumber": "<purchase order number>",
        "billOfLadingNumber": "<Bill of Lading number>",
        "asnNumber": "<ASN (advanced shipping notice) number>",
        "eventDateTime": "<event date time>",
        "expectedDeliveryDate": "<expected delivery date>",
        "shipFromLocationCode": "<ship from location code>",
        "shipToLocationCode": "<ship to location code>",
        "productList": [
            {
                "palletId": "<pallet ID>",
                "palletLpn": "<pallet LPN (license plate number)>",
                "palletLayers": 0,
                "cartonsPerLayer": 0,
                "iotDevice": "<IoT device>",
                "poLineNumber": "<PO (purchase order) line number>",
                "vendorItemCode": "<vendor item code>",
                "purchaserItemCode": "<purchaser item code>",
                "caseGtin": "<case GTIN>",
                "caseLotNumber": "<case lot number>",
                "shipQuantity": 0,
                "shipQuantityUom": "<ship quantity UOM (unit of measure)>",
                "expirationDate": "<expiration date>",
                "productionDate": "<production date>",
                "packagingDate": "<packaging date>",
                "bestBeforeDate": "<best before date>",
                "harvestDate": "<harvest date>",
                "countryOfOrigin": "<country of origin>",
                "tlcSourceReferenceDuns": "<TLC source reference DUNS>",
                "tlcSourceReferenceGln": "<TLC source reference GLN>",
                "tlcSourceReferenceFfrn": "<TLC source reference FFRN>",
                "tlcSourceReferenceFei": "<TLC source reference FEI>",
                "tlcSourceReferenceUrl": "<TLC source reference URL>",
                "tlcSourceReferenceOther": "<TLC source reference OTHER>",
                "tlcSourceName": "<TLC source name>",
                "tlcSourceAddress1": "<TLC source address 1>",
                "tlcSourceAddress2": "<TLC source address 2>",
                "tlcSourceCity": "<TLC source city>",
                "tlcSourceState": "<TLC source state>",
                "tlcSourcePostalCode": "<TLC source postal code>",
                "tlcSourceCountry": "<TLC source country>",
                "tlcSourcePhoneNumber": "<TLC source phone number>",
                "itemUpc": "<item UPC>",
                "itemPlu": "<item PLU>",
                "itemDateCode": "<item date code>",
                "itemDateCodeType": "<item date code type>"
            }
        ]
    }
}
tip

While the example payload above includes only one location object in the locationMasterList, your real payload will minimally contain two: the ship from location and the ship to location.

Data Constraints​

Please note the following data constraints:

  • strings allow a maximum of 100 characters
  • dates must use the format: yyyy-MM-dd
  • datetimes must use the format: yyyy-MM-ddTHH:mm:ssZ (UTC) or yyyy-MM-ddTHH:mm:ss-hh:00 (UTC minus) or yyyy-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 event
  • itemDescription (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 product
  • gtin (string): Case-level Global Trade Identification Number (GTIN-14). GS1 GTIN Executive Summary
  • itemUpc (string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive Summary
  • innerPackUpc (string): Point of sale barcode, may be GTIN-8, GTIN-12, GTIN-13, or GTIN-14. GS1 GTIN Executive Summary
  • plu (string): Item-level Price Look-up Code. PLU Codes Search — IFPS
  • isFtlItem (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 package
  • packStyle (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 List
  • acceptableSpeciesName (string): For seafood a description of the common species name, see: FDA Seafood List
  • isCoveredByGdst (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 event
  • locationCode (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 Summary
  • duns (string): Dun & Bradstreet Data Universal Numbering System number, a 9-digit string
  • address (object):
    • streetAddress1 (string): Physical street address line 1 information
    • streetAddress2 (string): Physical street address line 2 information, if applicable
    • city (string): City location
    • state (string): State or region location
    • postalCode (string): ZIP or postal code
    • country (string): Country location
    • geoLocation optional (object): Consisting of either...
      • gpsCoordinates as an array of strings representing the latitude followed by longitude expressed in degrees and minutes OR
      • geoFence as an array of string arrays representing the latitude followed by longitude expressed in degrees and minutes for each set of coordinates defining the geo fence

Optional​

  • businessUnit (string): Indicates the business unit associated with the location.
  • market (string): Indicates the market associated with the location.
  • region (string): Indicates the region associated with the location.
  • 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 location
  • glnAssignedBy (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 ID
  • phoneNumber (string)*: Phone number including country code with format: +1.999.999.999 *This field is required if address is used to identify location
  • isPrimaryLocation (boolean): This indicates that the location is the primary headquarter location for the organization
  • isCoveredByGdst (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​

  • dataProviderVendorId (string): Your ID for the vendor/supplier
  • purchaseOrderNumber (string): The purchase order number you received from your customer
  • eventDateTime (datetime): Date and time the order was actually shipped
  • shipFromLocationCode (string): References a location from locationMasterList. The vendor’s location code for ship from location
  • shipToLocationCode (string): References a location from locationMasterList. The buyer’s location code for ship to location. This should be provided as part of the Purchase Order
  • productList (array): List of items shipped in the event

Optional​

  • dataProviderVendorName (string): Name of the vendor/supplier
  • purchaseOrderDate (date): Purchase order date
  • billOfLadingNumber (string): The Bill of Lading provided by you to your customer
  • asnNumber (string): This is the unique identifier for the ASN you provide to your customer (if you provide one)
  • expectedDeliveryDate (date): Date when shipper expects to deliver goods to recipient

Products​

Required​
  • vendorItemCode (string): This is the vendor's (or your) internal product id or item code stored in their master data. If the cases shipped are labeled with a case GTIN-14, this information should be stored in the product master data record for the item code / product id referenced
  • shipQuantity (number): The number of units of this Traceability Lot Code on the pallet
  • shipQuantityUom (string): Unit of measure (e.g., Case)

Traceability Lot Code (TLC) Source could be either the address and phone of the facility that produced the TLC, or a reference to a database that provides the address and phone for the TLC Source. Provide at least one of the following as a reference:

  • tlcSourceReferenceDuns (string): 9 Digit Dun & Bradstreet Number, must be registered in DUNS and available to FDA. The TLC Source reference DUNS + 4
  • tlcSourceReferenceGln (string): 13 Digit GS1 Global Location Number. Must be registered in GS1 US Data Hub | Location. The TLC Source reference GLN
  • tlcSourceReferenceFfrn (string): FDA Food Facility Registration Number, must be current in FDA Facility Registration Database. The TLC Source reference FFRN
  • tlcSourceReferenceFei (string): FDA Establishment Identifier. This number may be requested at no cost from FDA. The TLC Source reference FEI
  • tlcSourceReferenceUrl (string): A web link point to a site where FDA may access the TLC Source Reference. The TLC Source reference URL
  • tlcSourceReferenceOther (string): This could be another identifier. One can prefix the ID with a type to make it easier to lookup. For example: 'USDAEgg: Plant 42"

If a TLC Source Reference is not provided, you must include all of the following information:

  • tlcSourceName (string): The TLC source name
  • tlcSourceAddress1 (string): The TLC Source physical street address line 1 information
  • tlcSourceAddress2 (string): The TLC Source physical street address line 2 information, if applicable
  • tlcSourceCity (string): The TLC Source city location
  • tlcSourceState (string): The TLC Source state or region location
  • tlcSourcePostalCode (string): The TLC Source ZIP or postal code
  • tlcSourceCountry (string): The TLC Source country
  • tlcSourcePhoneNumber (string): The TLC Source phone number
Optional​
  • businessUnit (string): Indicates the business unit associated with the product.
  • palletId (string): GS1 Serial Shipping Container Code, SSCC-18 (if provided) 
  • palletLpn (string): Internally generated License Plate Number (e.g., from Warehouse Management System)
  • palletLayers (number): Number of layers per pallet
  • cartonsPerLayer (number): Number of cartons per layer
  • iotDevice (string): If you provide an IoT device attached to the pallet, capture its identifier here
  • poLineNumber (string): Line number in the purchase order for this item; this links the Traceability Lot Code to the line item on the PO
  • purchaserItemCode (string): This is the purchaser's product item code provided via their PO or other form of data sharing. This information is stored in your master data. If the customer has shared a GTIN, it should be stored in the master data record. The purchaser's item code may also be the purchaser’s GTIN, but not necessarily-–it could be a SKU or another type of ID. This may point to the receiver’s master product data record
  • caseGtin (string): GTIN-14 of cases on pallet
  • caseLotNumber (string): This is the Lot Number displayed on the case label you are providing to the customer. This will be required starting in January 2026
  • expirationDate (date): The expiration date
  • productionDate (date): The production date
  • packagingDate (date): The packaging date
  • bestBeforeDate (date): The best before date
  • harvestDate (date): The harvesting date
  • countryOfOrigin (string): The three letter country code of origin
  • itemUpc (string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive Summary
  • itemPlu (string): Include if items in the case are marked with PLU numbers; this may be used instead of UPC
  • itemDateCode (date): Often items are marked with a date code; if so, this field can be used to capture it
  • itemDateCodeType (string): Indicate the type of date code if provided

Sample Payload​

{
    "productMasterDataList": [
        {
            "itemCode": "10750455000106",
            "businessUnit": "01",
            "itemDescription": "Bailey Farms Hotties Jalapeno Peppers",
            "isFtlItem": true,
            "ftlCategory": "peppers-fresh",
            "brandName": "Bailey Farms",
            "packStyle": "Case",
            "packSize": "20 x 12 oz bags",
            "productCommodity": "Peppers",
            "productVariety": "Jalapeno",
            "scientificName": "sname1",
            "acceptableSpeciesName": "sci1",
            "gtin": "10750455000106",
            "innerPackUpc": "00234567",
            "itemUpc": "00750455000109",
            "plu": "4693",
            "alternateItemCode": "ALT123",
            "isCoveredByGdst": true
        },
        {
            "itemCode": "SYS1350271",
            "businessUnit": "01",
            "itemDescription": "Jalapeno Peppers",
            "isFtlItem": false,
            "ftlCategory": "peppers-fresh",
            "brandName": "",
            "packStyle": "Case",
            "packSize": "",
            "productCommodity": "Peppers",
            "productVariety": "Jalapeno",
            "scientificName": "sname",
            "acceptableSpeciesName": "sci",
            "gtin": "11720455000106",
            "innerPackUpc": "00233267",
            "itemUpc": "00750452300109",
            "plu": "469",
            "alternateItemCode": "ALT234",
            "isCoveredByGdst": true
        }
    ],
    "locationMasterList": [
        {
            "locationCode": "0750455000017",
            "businessUnit": "01",
            "market": "North",
            "region": "03",
            "locationType": "Internal",
            "locationName": "Bailey Farms Packing",
            "parentLocationId": "145741",
            "gln": "750455000017",
            "glnAssignedBy": "Internal",
            "duns": "17",
            "alternateLocationCode": "",
            "phoneNumber": "+19196901524",
            "isPrimaryLocation": true,
            "isCoveredByGdst": false,
            "address": {
                "streetAddress1": "107 Enterprise Ct",
                "streetAddress2": "",
                "city": "Oxford",
                "state": "NC",
                "postalCode": "27565",
                "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": "191446525",
            "businessUnit": "01",
            "market": "North",
            "region": "03",
            "locationType": "Customer",
            "locationName": "Bob's Restaurant",
            "parentLocationId": "451841",
            "gln": "12345678901234",
            "glnAssignedBy": "Internal",
            "duns": "415648888",
            "alternateLocationCode": "ALT123",
            "phoneNumber": "+16154541123",
            "isPrimaryLocation": false,
            "isCoveredByGdst": true,
            "address": {
                "streetAddress1": "107 Enterprise Ct",
                "streetAddress2": "Suite 22",
                "city": "Oxford",
                "state": "NC",
                "postalCode": "27565",
                "country": "USA"
            }
        }
    ],
    "eventList": {
        "dataProviderVendorId": "9999",
        "dataProviderVendorName": "Test",
        "purchaseOrderDate": "2024-09-12",
        "purchaseOrderNumber": "82345689",
        "billOfLadingNumber": "38423",
        "asnNumber": "384385843",
        "eventDateTime": "2024-09-13T13:02:01Z",
        "expectedDeliveryDate": "2024-09-16",
        "shipFromLocationCode": "0750455000017",
        "shipToLocationCode": "191446525",
        "productList": [
            {
                "palletId": "107504550400708930",
                "palletLpn": "",
                "palletLayers": 3,
                "cartonsPerLayer": 6,
                "poLineNumber": "4",
                "vendorItemCode": "10750455000106",
                "purchaserItemCode": "SYS1350271",
                "caseGtin": "12750455000106",
                "caseLotNumber": "BFNCF1091024",
                "shipQuantity": 3,
                "shipQuantityUom": "CS",
                "expirationDate": "2024-09-27",
                "productionDate": "2024-09-01",
                "packagingDate": "2024-09-12",
                "bestBeforeDate": "2024-09-20",
                "harvestDate": "2024-09-10",
                "countryOfOrigin": "USA",
                "tlcSourceName": "Bailey Farms Packing",
                "tlcSourceAddress1": "123 Front St",
                "tlcSourceAddress2": "Apartment 1",
                "tlcSourceCity": "Columbus",
                "tlcSourceState": "Ohio",
                "tlcSourcePostalCode": "43026",
                "tlcSourceCountry": "USA",
                "tlcSourcePhoneNumber": "6145551212",
                "tlcSourceReferenceDuns": "",
                "tlcSourceReferenceGln": "0750455000017",
                "tlcSourceReferenceFfrn": "ffrn",
                "tlcSourceReferenceFei": "fei",
                "tlcSourceReferenceOther": "other",
                "tlcSourceReferenceUrl": "url",
                "itemUpc": "00750455000109",
                "itemPlu": "46193",
                "itemDateCode": "20240927",
                "itemDateCodeType": "expiration"
            }
        ]
    }
}

Response​

Shipping event data ingested successfully

{
    "request_ids": ["1abc2f7e-6ca2-40ec-9566-19a850945d7f"]
}