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:

Completion of a successful POST. Example: "request_ids": ["9ed5911f-f6a4-4ba2-9eb4-d6428237be28"]
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 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>",
      "innerPackUpc": "<inner pack UPC>",
      "itemUpc": "<item UPC>",
      "plu": "<PLU>",
      "alternateItemCode": "<alternate item code>",
      "isCoveredByGdst": true,
      "businessUnit": "<business unit>"
    }
  ],

  "locationMasterList": [
    {
      "locationCode": "<location code>",
      "locationName": "<location name>",
      "locationType": "<location type>",
      "phoneNumber": "<phone number>",
      "gln": "<GLN>",
      "glnAssignedBy": "<GLN assigned by>",
      "duns": "<DUNS number>",
      "alternateLocationCode": "<alternate location code>",
      "parentLocationId": "<parent location id>",
      "isPrimaryLocation": true,
      "isCoveredByGdst": false,
      "businessUnit": "<business unit>",
      "region": "<region>",
      "market": "<market>",
      "address": {
        "streetAddress1": "<street address 1>",
        "streetAddress2": "<street address 2>",
        "city": "<city>",
        "state": "<state>",
        "postalCode": "<postal code>",
        "country": "<country>"
      },
      "geoLocation": {
        "gpsCoordinates": [
          "<latitude>",
          "<longitude>"
        ],
        "geoFence": [
          ["<latitude1>", "<longitude1>"],
          ["<latitude2>", "<longitude2>"]
        ]
      }
    }
  ],

  "eventList": [
    {
      "eventId": "<event id>",
      "id": "<internal id>",
      "businessUnit": "<business unit>",
      "eventTransactionTime": "<event transaction datetime>",
      "workOrderNumber": "<work order number>",
      "eventDateTime": "<event datetime>",
      "transformationLocationCode": "<location code>",
      "transformationLocationName": "<location name>",

      "foodUsedInTransformation": [
        {
          "woLineNumber": "<work order line number>",
          "ssccPalletUsed": "<SSCC pallet>",
          "lpnPalletUsed": "<LPN pallet>",
          "iotDevicePalletUsed": "<IoT device>",
          "foodUsedItemCode": "<item code>",
          "foodUsedItemDescription": "<item description>",
          "foodUsedLotCode": "<lot code>",
          "foodUsedCaseGtin": "<case GTIN>",
          "foodUsedQuantity": <quantity>,
          "foodUsedUom": "<unit of measure>",

          "tlcSourceName": "<source name>",
          "tlcSourceReferenceGln": "<source GLN>",
          "tlcSourceReferenceDuns": "<source DUNS>",
          "tlcSourceReferenceFfrn": "<source FFRN>",
          "tlcSourceReferenceFei": "<source FEI>",
          "tlcSourceReferenceUrl": "<source URL>",
          "tlcSourceReferenceOther": "<other reference>",
          "tlcSourceAddress1": "<source address line 1>",
          "tlcSourceAddress2": "<source address line 2>",
          "tlcSourceCity": "<source city>",
          "tlcSourceState": "<source state>",
          "tlcSourcePostalCode": "<source postal code>",
          "tlcSourceCountry": "<source country>",
          "tlcSourcePhoneNumber": "<source phone>"
        }
      ],

      "foodsProducedInTransformation": {
        "woLineNumber": "<work order line number>",
        "ssccPalletProduced": "<SSCC pallet>",
        "lpnPalletProduced": "<LPN pallet>",
        "iotDevicePalletProduced": "<IoT device>",
        "foodProducedItemCode": "<item code>",
        "foodProducedItemDescription": "<item description>",
        "foodProducedLotCode": "<lot code>",
        "foodProducedCaseGtin": "<case GTIN>",
        "foodProducedQuantity": <quantity>,
        "foodProducedUom": "<unit of measure>",
        "foodProducedExpirationDate": "<yyyy-MM-dd>",
        "foodProducedProductionDate": "<yyyy-MM-dd>",
        "foodProducedPackagingDate": "<yyyy-MM-dd>",
        "foodProducedBestBeforeDate": "<yyyy-MM-dd>",
        "foodProducedHarvestDate": "<yyyy-MM-dd>"
      }
    }
  ]
}

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

Payload Data

Optional

payloadId (string): A unique payload id supplied by the party submitting the event.
transmissionDateTime (datetime): The date and time the payload was sent.

Required

productMasterDataList (array): List of product master records referenced by transformation events.
locationMasterDataList (array): List of location master records referenced by transformation events.
eventList (array): List of transformation events.

Product Data

Required

itemCode (string): Product identifier supplied by the vendor or purchaser.
itemDescription (string): Product description from the product owner or original purchase order.

Optional

isFtlItem (boolean): Indicates whether the product is on the Food Traceability List (FTL).
ftlCategory (string): Food Traceability List category for the product.
brandName (string): Brand name appearing on the consumer package.
packStyle (string): Packaging style (e.g., Case, Carton, Tray).
packSize (string): Packaging configuration or count.
productCommodity (string): Commodity description.
productVariety (string): Variety description.
scientificName (string): Scientific species name.
acceptableSpeciesName (string): Common species name.
gtin (string): Case-level Global Trade Item Number (GTIN-14).
innerPackUpc (string): Inner-pack UPC.
itemUpc (string): Item-level UPC.
plu (string): Price Look-Up (PLU) code.
alternateItemCode (string): Alternate product identifier.
isCoveredByGdst (boolean): Indicates participation in GDST.
businessUnit (string): Business unit associated with the product.

Location Data

Required

locationCode (string): Location identifier referenced by transformation events.
locationName (string): Name of the location.

Optional

locationType (string): Location classification.
phoneNumber (string): Contact phone number.
gln (string): Global Location Number.
glnAssignedBy (string): Entity that assigned the GLN.
duns (string): DUNS number.
alternateLocationCode (string): Alternate location identifier.
parentLocationId (string): Identifier of the parent location.
isPrimaryLocation (boolean): Indicates the primary location.
isCoveredByGdst (boolean): Indicates GDST participation.
businessUnit (string): Business unit associated with the location.
region (string): Region associated with the location.
market (string): Market associated with the location.
address (object): Physical address of the location.
geoLocation (object): Geographic location data.

Address

Optional

streetAddress1 (string): Physical street address line 1.
streetAddress2 (string): Physical street address line 2.
city (string): City.
state (string): State or region.
postalCode (string): Postal or ZIP code.
country (string): Country.

Geo Location

Optional

gpsCoordinates (array[string]): Latitude and longitude pair.
geoFence (array[array[string]]): List of latitude/longitude coordinate pairs defining a geofence.

Event Data

Required

workOrderNumber (string): Identifier for the work order associated with the transformation event.
eventDateTime (datetime): Date and time the transformation occurred.

Optional

type (string): Event type; when provided, must be transformation.
eventId (string): Caller-provided unique identifier for the event.
id (string): Additional identifier for the event.
eventTransactionTime (datetime): Timestamp when the event record was created or transmitted.
businessUnit (string): Business unit associated with the event.
transformationLocationCode (string): Location code where the transformation occurred.
transformationLocationName (string): Human-readable location name.
foodUsedInTransformation (array): Input TLCs used in the transformation.
foodsProducedInTransformation (object): Output TLC produced by the transformation.

Food Used in Transformation

Required

foodUsedItemCode (string): Product identifier for the food used.
foodUsedQuantity (number): Quantity of this TLC used in the transformation.

Optional

woLineNumber (string): Links the TLC to the line item on the work order.
ssccPalletUsed (string): SSCC identifying the pallet used in the transformation.
lpnPalletUsed (string): License Plate Number (LPN) identifying the pallet used.
iotDevicePalletUsed (string): IoT device identifier associated with the pallet used.
foodUsedItemDescription (string): Description of the food used.
foodUsedLotCode (string): Lot code for the food used.
foodUsedCaseGtin (string): GTIN-14 of cases of food used.
foodUsedUom (string): Unit of measure (e.g., Case, lbs) for food used in transformation.
tlcSourceName (string): Name of the TLC source.
tlcSourceReferenceGln (string): GLN of the TLC source.
tlcSourceReferenceDuns (string): DUNS number of the TLC source.
tlcSourceReferenceFfrn (string): FDA Food Facility Registration Number of the TLC source.
tlcSourceReferenceFei (string): FDA Establishment Identifier of the TLC source.
tlcSourceReferenceUrl (string): URL identifying the TLC source.
tlcSourceReferenceOther (string): Other identifier for the TLC source.
tlcSourceAddress1 (string): TLC source address line 1.
tlcSourceAddress2 (string): TLC source address line 2.
tlcSourceCity (string): TLC source city.
tlcSourceState (string): TLC source state.
tlcSourcePostalCode (string): TLC source postal code.
tlcSourceCountry (string): TLC source country.
tlcSourcePhoneNumber (string): TLC source phone number.

Food Produced in Transformation

Required

foodProducedItemCode (string): Product identifier for the food produced.
foodProducedLotCode (string): Lot code for the food produced.
foodProducedQuantity (number): Quantity produced in the transformation.

Optional

woLineNumber (string): Links the produced TLC to the work order line.
ssccPalletProduced (string): SSCC identifying the produced pallet.
lpnPalletProduced (string): License Plate Number (LPN) identifying the produced pallet.
iotDevicePalletProduced (string): IoT device identifier associated with the produced pallet.
foodProducedItemDescription (string): Description of the food produced.
foodProducedCaseGtin (string): GTIN-14 of cases produced.
foodProducedUom (string): Unit of measure (e.g., Case, lbs) for food produced.

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": "ITEM-123",
      "itemDescription": "Fresh Oysters - 10 lb case",
      "isFtlItem": true,
      "ftlCategory": "molluscan shellfish",
      "brandName": "Sea Fresh",
      "packStyle": "Case",
      "packSize": "1 x 10 lb",
      "productCommodity": "Oysters",
      "productVariety": "Eastern",
      "scientificName": "Crassostrea virginica",
      "acceptableSpeciesName": "Eastern oyster",
      "gtin": "00123456789012",
      "innerPackUpc": "0123456789012",
      "itemUpc": "123456789012",
      "plu": "4929",
      "alternateItemCode": "https://id.example.com/products/ITEM-123",
      "isCoveredByGdst": false,
      "businessUnit": "Seafood"
    }
  ],
  "locationMasterList": [
    {
      "locationCode": "LOC-2790",
      "locationName": "Sea Farms R1",
      "locationType": "Internal",
      "phoneNumber": "+15555555555",
      "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"]
        ]
      },
      "gln": "1234567890123",
      "glnAssignedBy": "GS1",
      "duns": "123456789",
      "alternateLocationCode": "https://id.example.com/locations/LOC-2790",
      "parentLocationId": "LOC-HQ-001",
      "isCoveredByGdst": true,
      "isPrimaryLocation": true,
      "businessUnit": "Seafood",
      "region": "Pacific Northwest",
      "market": "US-West"
    }
  ],
  "eventList": [
    {
      "eventId": "EVT-TRANS-000001",
      "id": "INT-TRANS-000001",
      "businessUnit": "Seafood",
      "eventTransactionTime": "2024-10-10T00:12:40Z",
      "workOrderNumber": "WO-999",
      "eventDateTime": "2024-10-10T00:12:34Z",
      "transformationLocationCode": "LOC-2790",
      "transformationLocationName": "Sea Farms R1",
      "foodUsedInTransformation": [
        {
          "woLineNumber": "3",
          "ssccPalletUsed": "003400000000000001",
          "lpnPalletUsed": "LPN-USED-0001",
          "iotDevicePalletUsed": "IOT-USED-0001",
          "foodUsedItemCode": "ITEM-123",
          "foodUsedItemDescription": "Fresh Oysters - 10 lb case",
          "foodUsedLotCode": "LOT-USED-20241009-A",
          "foodUsedCaseGtin": "00123456789012",
          "foodUsedQuantity": 21,
          "foodUsedUom": "lbs",
          "tlcSourceName": "Coastal Shellfish Supplier",
          "tlcSourceReferenceGln": "9876543210987",
          "tlcSourceReferenceDuns": "987654321",
          "tlcSourceReferenceFfrn": "FFRN-1234567890",
          "tlcSourceReferenceFei": "FEI-1234567890",
          "tlcSourceReferenceUrl": "https://supplier.example.com/facility/123",
          "tlcSourceReferenceOther": "SupplierInternalId-55",
          "tlcSourceAddress1": "500 Harbor Rd",
          "tlcSourceAddress2": "Building B",
          "tlcSourceCity": "Baytown",
          "tlcSourceState": "OR",
          "tlcSourcePostalCode": "97000",
          "tlcSourceCountry": "USA",
          "tlcSourcePhoneNumber": "+15035551212"
        }
      ],
      "foodsProducedInTransformation": {
        "woLineNumber": "FP-0003",
        "ssccPalletProduced": "003400000000000099",
        "lpnPalletProduced": "LPN-PROD-0099",
        "iotDevicePalletProduced": "IOT-PROD-0099",
        "foodProducedItemCode": "ITEM-123",
        "foodProducedItemDescription": "Fresh Oysters - 10 lb case",
        "foodProducedLotCode": "LOT-PROD-20241010-B",
        "foodProducedCaseGtin": "00123456789012",
        "foodProducedQuantity": 30,
        "foodProducedUom": "lbs",
        "foodProducedExpirationDate": "2025-03-30",
        "foodProducedProductionDate": "2024-10-10",
        "foodProducedPackagingDate": "2024-10-10",
        "foodProducedBestBeforeDate": "2025-03-15",
        "foodProducedHarvestDate": "2024-10-08"
      }
    }
  ]
}

Response

Transformation event data ingested successfully

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

Description of what user-fixable validation error occurred and in what part of the payload

{
    "detail": [
        {
            "type": "missing",
            "loc": [
                "body",
                "eventList",
                "purchaseOrderNumber"
            ],
            "msg": "Field required",
        }
    ]
}

Request​

Data Constraints​

Payload Data​

Optional​

Required​

Product Data​

Required​

Optional​

Location Data​

Required​

Optional​

Address​

Optional​

Geo Location​

Optional​

Event Data​

Required​

Optional​

Food Used in Transformation​

Required​

Optional​

Food Produced in Transformation​

Required​

Optional​

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

Sample Payload​

Response​

Request

Data Constraints

Payload Data

Optional

Required

Product Data

Required

Optional

Location Data

Required

Optional

Address

Optional

Geo Location

Optional

Event Data

Required

Optional

Food Used in Transformation

Required

Optional

Food Produced in Transformation

Required

Optional

One of the following is required, the others are Optional

Sample Payload

Response