Skip to main content

Update Transformation Event

Method: PUT
/events/transformation/{id}

As a Customer of iFoodDS, you use the iFoodDS Transformation Event API to update FSMA 204 transformation event data in the iFoodDS Trace Exchange platform.

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 successful 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 of three main sections: the productMasterDataList, the locationMasterList, the eventList. The first two sections are there to reduce the duplication of data you need to provide for the eventList. The eventList includes foodUsedInTransformation and the foodProducedInTransformation.

{
    "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>",
        "transformationLocationId": "<transformation location id>",
        "foodUsedInTransformation": [
            {
                "woLineNumber": "<work order line number>",
                "ssccPalletUsed": "<sscc pallet used>",
                "lpnPalletUsed": "<lpn pallet used>",
                "iotDevicePalletUsed": "<iot device pallet used>",
                "foodUsedProductId": "<food used product id>",
                "foodUsedLotCode": "<food used lot code>",
                "foodUsedCaseGtin": "<food used case gtin>",
                "foodUsedQuantity": <food used quantity>,
                "foodUsedUom": "<food used uom>"
            }
        ],
        "foodsProducedInTransformation": {
            "woLineNumber": "<work order line number>",
            "ssccPalletProduced": "<sscc pallet produced>",
            "lpnPalletProduced": "<lpn pallet produced>",
            "iotDevicePalletProduced": "<iot device pallet produced>",
            "foodProducedProductId": "<food produced product id>",
            "foodProducedLotCode": "<food produced lot code>",
            "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:

  • 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​

  • 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​

  • eventDateTime (datetime): Date and time the transformation occurred

Optional​

  • workOrderNumber (string): Work order number
  • transformationLocationId (string): References a location setup in master data. This is also known as the TLC Source.

Food Used in Transformation​

Required​

  • foodUsedProductId (string): This Product ID should be stored in your master data. If the cases you use in transformation are labeled with case GTIN-14s, the GTIN should be stored in the product master data record for the Product ID referenced. For a product used in transformation you might want to include the supplier's product id captured at receiving and your own internal product id.
  • foodUsedQuantity (number): The number of units of this TLC used in Transformation.

Optional​

  • woLineNumber (string): This links the TLC to the line item on the work order.
  • ssccPalletUsed (string): Instead of the product and lot information, you may elect to provide the SSCC your supplier provided. The receiving event will be used to identify the lot codes for the Transformation event.
  • lpnPalletUsed (string): Instead of the product and lot information, you may elect to provide the LPN you assigned at receiving. The receiving event will be used to identify the lot codes for the Transformation event.
  • iotDevicePalletUsed (string): Instead of the product and lot information, you may elect to provide the IoT Device that you or your supplier associated to the pallet.The receiving event will be used to identify the lot codes for the Transformation event.
  • foodUsedLotCode (string): This is the Lot Number for the foods used in transformation.
  • foodUsedCaseGtin (string): GTIN-14 of cases of food used
  • foodUsedUom (string): Unit of measure (e.g., Case) for food used in Transformation

Food Produced in Transformation​

Required​

  • foodProducedProductId (string): This Product ID should be stored in your master data. If the cases you use in transformation are labeled with case GTIN-14s, the GTIN should be stored in the product master data record for the Product ID referenced. For a product produced in transformation you may want to include your product id and your customer's product id if it is a private label product.
  • foodProducedLotNumber (string): This is the Lot Number for the foods produced in transformation.
  • foodProducedQuantity (number): The number of units of this TLC produced in Transformation

Optional​

  • woLineNumber (string): This links the TLC to the line item on the work order.
  • ssccPalletProduced (string): Link the TLC to a pallet SSCC in preparation for outbound shipment.
  • lpnPalletProduced (string): Link the TLC to a pallet LPN in preparation for outbound shipment.
  • iotDevicePalletProduced (string): Link the TLC and Pallet LPN or SSCC to an IoT device in preparation for outbound shipment.
  • foodProducedCaseGtin (string): GTIN-14 of cases of food produced
  • foodProducedUom (string): Unit of measure (e.g., Case) for food produced in Transformation

One of the following is required, the others are Optional​

  • foodReceivedExpirationDate (date): Food Received expiration Date
  • foodReceivedProductionDate (date): Food Received Production Date
  • foodReceivedPackagingDate (date): Food Received Packaging Date
  • foodReceivedBestBeforeDate (date): Food Received Best Before Date
  • foodReceivedHarvestDate (date): Food Received Harvest Date

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": "pstyle",
            "packSize": "psize",
            "productCommodity": "pcom",
            "productVariety": "pvar",
            "scientificName": "sciname",
            "acceptableSpeciesName": "speciesnm",
            "gtin": "01234567890123",
            "innerPackUpc": "",
            "itemUpc": "itemupc",
            "plu": "",
            "alternateItemCode": "altitem",
            "isCoveredByGdst": true
        },
        {
            "itemCode": "123456",
            "itemDescription": "Fresh Scallops/Oysters",
            "isFtlItem": true,
            "ftlCategory": "seafood",
            "brandName": "Sea Fresh",
            "packStyle": "",
            "packSize": "",
            "productCommodity": "",
            "productVariety": "",
            "scientificName": "",
            "acceptableSpeciesName": "",
            "gtin": "",
            "innerPackUpc": "",
            "itemUpc": "",
            "plu": "",
            "alternateItemCode": "",
            "isCoveredByGdst": true
        }
    ],
    "locationMasterList": [
        {
            "locationCode": "2790",
            "locationType": "Internal",
            "locationName": "Sea Farms R1",
            "gln": "",
            "glnAssignedBy": "",
            "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": "",
            "phoneNumber": "+15555555555",
            "isPrimaryLocation": true,
            "isCoveredByGdst": true,
            "address": {
                "streetAddress1": "1 Seaway",
                "streetAddress2": "Dock 11",
                "city": "Seaside",
                "state": "WA",
                "postalCode": "99999",
                "country": "USA"
            }
        }
    ],
    "eventList": {
        "workOrderNumber": "WO9999999999999999999",
        "eventDateTime": "2024-10-10T00:13:34Z",
        "eventId": "54157",
        "transformationLocationCode": "2790",
        "foodUsedInTransformation": [
            {
                "woLineNumber": "3",
                "ssccPalletUsed": "",
                "lpnPalletUsed": "",
                "iotDevicePalletUsed": "",
                "foodUsedItemCode": "99999999999999999999",
                "foodUsedLotCode": "F52",
                "foodUsedCaseGtin": "98294723",
                "foodUsedQuantity": 21,
                "foodUsedUom": "lbs"
            },
            {
                "woLineNumber": "4",
                "ssccPalletUsed": "",
                "lpnPalletUsed": "",
                "iotDevicePalletUsed": "11",
                "foodUsedItemCode": "345",
                "foodUsedLotCode": "F51",
                "foodUsedCaseGtin": "",
                "foodUsedQuantity": 2,
                "foodUsedUom": "lbs"
            }
        ],
        "foodsProducedInTransformation": {
            "woLineNumber": "FP0003",
            "ssccPalletProduced": "",
            "lpnPalletProduced": "",
            "iotDevicePalletProduced": "",
            "foodProducedItemCode": "12345688888888888888888888",
            "foodProducedLotCode": "248-12",
            "foodProducedCaseGtin": "",
            "foodProducedQuantity": 30,
            "foodProducedExpirationDate": "2025-03-30",
            "foodProducedUom": "lbs",
            "foodProducedProductionDate": "2025-03-30",
            "foodProducedPackagingDate": "2025-03-30",
            "foodProducedBestBeforeDate": "2025-03-30",
            "foodProducedHarvestDate": "2025-03-30"
        }
    }
}

Response​

Transformation event data ingested successfully

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