Skip to main content

Submit Transformation Events

Method: POST
/events/transformation

As a Customer of iFoodDS, you use the iFoodDS Transformation Event API to send FSMA 204 transformation event data to 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 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​

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

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",
      "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": ["e8107014-7b89-48b7-83bd-aaa4fb21ece0"]
}