FSMA Compliance

Creates a Commission event including the location and product master data required to create them on the go. For TlcSource, choose either reference data or master data.

curl -X POST "https://connect.wholechain.com/Integration/Events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Events": [
    {
      "$type": "commission",
      "Location": {
        "Id": "processing_001",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Processing Street",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001_FSMA",
          "Product": {
            "Id": "rawgoods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Raw Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          },
          "TraceabilityLotCode": "TLC-2026-000184",
          "TlcSource": {
            "Type": "Identifier",
            "Reference": "FDA Food Facility Registration Number",
            "Identifier": "11111111111"
          },
          "MasterData": [
            {
              "name": "quality_grade",
              "namespace": "gdst:lot",
              "value": "A"
            }
          ]
        }
      ],
      "Id": "commission_001_FSMA",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T13:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
}'

import requests
import json

url = "https://connect.wholechain.com/Integration/Events"
headers = {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string"
}
data = {
  "Events": [
    {
      "$type": "commission",
      "Location": {
        "Id": "processing_001",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Processing Street",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001_FSMA",
          "Product": {
            "Id": "rawgoods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Raw Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          },
          "TraceabilityLotCode": "TLC-2026-000184",
          "TlcSource": {
            "Type": "Identifier",
            "Reference": "FDA Food Facility Registration Number",
            "Identifier": "11111111111"
          },
          "MasterData": [
            {
              "name": "quality_grade",
              "namespace": "gdst:lot",
              "value": "A"
            }
          ]
        }
      ],
      "Id": "commission_001_FSMA",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T13:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://connect.wholechain.com/Integration/Events", {
  method: "POST",
  headers: {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string"
},
  body: JSON.stringify({
  "Events": [
    {
      "$type": "commission",
      "Location": {
        "Id": "processing_001",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Processing Street",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001_FSMA",
          "Product": {
            "Id": "rawgoods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Raw Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          },
          "TraceabilityLotCode": "TLC-2026-000184",
          "TlcSource": {
            "Type": "Identifier",
            "Reference": "FDA Food Facility Registration Number",
            "Identifier": "11111111111"
          },
          "MasterData": [
            {
              "name": "quality_grade",
              "namespace": "gdst:lot",
              "value": "A"
            }
          ]
        }
      ],
      "Id": "commission_001_FSMA",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T13:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
})
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    data := []byte(`{
  "Events": [
    {
      "$type": "commission",
      "Location": {
        "Id": "processing_001",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Processing Street",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001_FSMA",
          "Product": {
            "Id": "rawgoods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Raw Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          },
          "TraceabilityLotCode": "TLC-2026-000184",
          "TlcSource": {
            "Type": "Identifier",
            "Reference": "FDA Food Facility Registration Number",
            "Identifier": "11111111111"
          },
          "MasterData": [
            {
              "name": "quality_grade",
              "namespace": "gdst:lot",
              "value": "A"
            }
          ]
        }
      ],
      "Id": "commission_001_FSMA",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T13:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
}`)

    req, err := http.NewRequest("POST", "https://connect.wholechain.com/Integration/Events", bytes.NewBuffer(data))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-KEY", "example_string")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://connect.wholechain.com/Integration/Events')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-KEY'] = 'example_string'
request.body = '{
  "Events": [
    {
      "$type": "commission",
      "Location": {
        "Id": "processing_001",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Processing Street",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001_FSMA",
          "Product": {
            "Id": "rawgoods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Raw Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          },
          "TraceabilityLotCode": "TLC-2026-000184",
          "TlcSource": {
            "Type": "Identifier",
            "Reference": "FDA Food Facility Registration Number",
            "Identifier": "11111111111"
          },
          "MasterData": [
            {
              "name": "quality_grade",
              "namespace": "gdst:lot",
              "value": "A"
            }
          ]
        }
      ],
      "Id": "commission_001_FSMA",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T13:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
}'

response = http.request(request)
puts response.body

{
  "message": "Events processed successfully",
  "result": [
    {
      "id": "commission_001",
      "status": "Created",
      "products": [
        {
          "id": "rawgoods_001",
          "status": "Created"
        }
      ],
      "locations": [
        {
          "id": "processing_001",
          "status": "Created"
        }
      ]
    }
  ]
}

POST

/Integration/Events

POST

Base URLstring

Target server for requests. Edit to use your own host.

Content-Typestring

Required

The media type of the request body

Options: application/json

Request Preview

Response

Response will appear here after sending the request

Responses

messagestring

resultarray

Introduction

Use Wholechain event payloads to record the traceability lot code (TLC), its source, and the event data needed to link a food to its movement through the supply chain.

Terminology: This page covers FSMA Section 204, also called the FDA Food Traceability Rule. It is not FISMA, the federal information-security law.

Required Account Settings

Enable TLC tracking in your Wholechain account by going to Settings -> Traceability Lot Code (TLC) -> Toggle this on

If TLC tracking is not enabled for the account, the TraceabilityLotCode and TlcSource you send are not stored. The lot's LotSerial is used as the traceability lot code and the TLC source is taken from the event's location.

Before you integrate

Determine whether the food appears on the FDA Food Traceability List and whether an exemption applies.
Identify the FDA Critical Tracking Event (CTE) represented by the Wholechain event.
Determine whether your organization is assigning a new TLC or preserving one received from an upstream source.
Ensure the TLC is linked to all required Key Data Elements (KDEs) for the traceability lot.
Document the record format, record location, TLC-assignment process, and point of contact in your traceability plan.

As of September 28, 2026, FDA states that the original compliance date was January 20, 2026; FDA proposed moving it to July 20, 2028, and Congress directed FDA not to enforce the rule before July 20, 2028. Check the FDA Food Traceability Rule page for the current status.

Map Wholechain events to FDA activities

The mapping depends on the real-world activity, not only the Wholechain event name.

Wholechain event	FSMA 204 guidance
Commission	Can represent initial packing or first land-based receiving when configured with the appropriate locations, dates, product data, and business step.
Internal Ship / External Ship	Use for a Shipping CTE. FDA shipping includes an intracompany movement between different street addresses. Preserve the existing TLC.
Receive	Use for a Receiving CTE. Preserve the upstream TLC unless the food came from an exempt entity and the rule requires you to assign one, or the activity is first land-based receiving.
Transform	Use for a Transformation CTE. Record TLC data on both `InputProducts` and `OutputProducts`. Assign the appropriate output TLC and source.
Aggregation / Disaggregation	These are not named FDA CTEs by themselves. Preserve the TLC unless the underlying operation also qualifies as a transformation or another CTE.
Observe	Can record supporting observations, but is not a named FDA CTE by itself.
Decommission	Is not a named FDA CTE by itself. Retain any records required for the preceding covered activities.

Do not create a new TLC for an ordinary shipping or receiving event. FDA generally limits TLC assignment to initial packing, first land-based receiving, and transformation, with a special rule for certain food received from an exempt entity.

API endpoint

POST https://connect.wholechain.com/Integration/Events

Sandbox:

POST https://connect-sandbox.wholechain.com/Integration/Events

Send these request headers:

X-API-KEY: YOUR_API_KEY
Content-Type: application/json
accept: */*

TLC fields

Add the following fields to the applicable product item in ProductInstances, InputProducts, or OutputProducts.

Field	Type	Required when used	Description
`TraceabilityLotCode`	string	Yes	The code that identifies the traceability lot.
`TlcSource`	object	Yes	The source where the TLC was assigned. Use either an `Identifier` source or a `MasterData` source.

`TlcSource`

TlcSource must be sent as an object. It is not a string.

The object supports two structures depending on how the TLC source is identified.

Option 1: Identifier source

Use an identifier when the TLC source is represented by an external identifier or reference.

{
  "TraceabilityLotCode": "TLC-2026-000184",
  "TlcSource": {
    "Type": "Identifier",
    "Reference": "FDA Food Facility Registration Number",
    "Identifier": "11111111111"
  }
}

Field	Type	Required	Description
`Type`	string	Yes	Must be `Identifier`.
`Reference`	string	Yes	The identifier or reference scheme, such as an FDA Food Facility Registration Number.
`Identifier`	string	Yes	The identifier or reference value.

Option 2: Master data source

Use MasterData when supplying the TLC source location directly.

{
  "TraceabilityLotCode": "TLC-2026-000184",
  "TlcSource": {
    "Type": "MasterData",
    "LocationName": "North Processing Facility",
    "CompanyName": "Example Foods, Inc.",
    "Phone": "+1-555-010-0142",
    "Line1": "100 Harbor Road",
    "Line2": "Building 2",
    "City": "Boston",
    "State": "MA",
    "PostalCode": "02110",
    "Country": "US",
    "GeoCoordinates": {
      "Latitude": 42.3601,
      "Longitude": -71.0589
    }
  }
}

Field	Type	Required	Description
`Type`	string	Yes	Must be `MasterData`.
`LocationName`	string	Yes	Name of the location where the TLC was assigned.
`CompanyName`	string	Yes	Company associated with the TLC source.
`Phone`	string	Yes	Contact phone number.
`Line1`	string	Yes	Primary street-address line.
`Line2`	string	No	Secondary address line.
`City`	string	No	City.
`State`	string	No	State, province, or comparable region.
`PostalCode`	string	No	Postal code.
`Country`	string	Yes	Country.
`GeoCoordinates`	object	No	Geographic coordinates for the location.
`GeoCoordinates.Latitude`	number	No	Latitude.
`GeoCoordinates.Longitude`	number	No	Longitude.

Receive example: preserve the upstream TLC

The TLC and its source sit inside the product instance. Event-level fields remain at the event root.

{
  "Events": [
    {
      "$type": "receive",
      "ShipFromLocation": {
        "Id": "supplier_location_001"
      },
      "ShipToLocation": {
        "Id": "receiving_location_001"
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "VENDOR-LOT-123",
          "Product": {
            "Id": "raw_goods_000"
          },
          "TraceabilityLotCode": "TLC-2026-000184",
          "TlcSource": {
            "Type": "Identifier",
            "Reference": "FDA Food Facility Registration Number",
            "Identifier": "11111111111"
          }
        }
      ],
      "Container": {},
      "Id": "receive-0004",
      "PurchaseOrder": "PO-1990091",
      "InvoiceNumber": "INV-12314154",
      "EventTime": "2026-09-28T16:00:00",
      "EventTimeZone": "+00:00"
    }
  ]
}

Transform example: link input and output lots

A transformation links every input TLC to the resulting output lot. The TLC fields belong to each item in InputProducts and OutputProducts.

{
  "Events": [
    {
      "$type": "transform",
      "Location": {
        "Id": "processing_000"
      },
      "InputProducts": [
        {
          "Quantity": 180.75,
          "LotSerial": "INPUT-LOT-123",
          "Product": {
            "Id": "raw_goods_000"
          },
          "TraceabilityLotCode": "TLC-IN-000184",
          "TlcSource": {
            "Type": "Identifier",
            "Reference": "FDA Food Facility Registration Number",
            "Identifier": "11111111111"
          }
        }
      ],
      "OutputProducts": [
        {
          "Quantity": 180.0,
          "LotSerial": "OUTPUT-LOT-456",
          "Product": {
            "Id": "finished_goods_000"
          },
          "TraceabilityLotCode": "TLC-OUT-000185",
          "TlcSource": {
            "Type": "MasterData",
            "LocationName": "North Processing Facility",
            "CompanyName": "Example Foods, Inc.",
            "Phone": "+1-555-010-0142",
            "Line1": "100 Harbor Road",
            "City": "Boston",
            "State": "MA",
            "PostalCode": "02110",
            "Country": "US"
          }
        }
      ],
      "Id": "transform-0002",
      "EventTime": "2026-09-28T15:00:00",
      "EventTimeZone": "+00:00"
    }
  ]
}

Link the required KDEs

Wholechain fields can provide much of the event record, but confirm the required KDEs for the CTE you perform.

FDA record concept	Wholechain field or approach
Traceability lot code	`TraceabilityLotCode`
TLC source location or reference	`TlcSource`
Product identifier and description	`Product.Id` and, when creating master data, `Product.Details`
Quantity and unit of measure	Product-item `Quantity` plus the product's unit-of-measure master data
Event date and time	`EventTime` and `EventTimeZone`
Shipping / receiving locations	`ShipFromLocation` and `ShipToLocation`
Processing location	`Location`
Reference documents	`PurchaseOrder`, `InvoiceNumber`, or a clearly defined `CustomProperties` entry for another document type and number
Activity classification	`$type`

If a required KDE has no dedicated field, use a stable custom-property contract or another linked record system. Your traceability plan must explain the format and location of all required records.

Operational compliance checklist

Preserve the TLC through shipping and ordinary receiving.
Assign or change a TLC only when the applicable FDA rule permits or requires it.
Include TlcSource whenever you send a TraceabilityLotCode.
Link all CTE records and KDEs to the correct traceability lot.
Keep identifiers stable across Wholechain, your ERP, and reference documents.
Keep required records generally for two years, subject to the rule's exceptions.
Be able to retrieve records within 24 hours of an FDA request.
Unless exempt, be prepared to provide an electronic sortable spreadsheet when FDA requests one in the circumstances defined by the rule.
Keep the traceability plan current and retain superseded plans for the required period.
Test trace-back and trace-forward retrieval before an incident occurs.

Was this page helpful?

FSMA Compliance

Request Preview

Response

Responses

Introduction

Required Account Settings

Before you integrate

Map Wholechain events to FDA activities

API endpoint

TLC fields

TlcSource

Option 1: Identifier source

Option 2: Master data source

Receive example: preserve the upstream TLC

Transform example: link input and output lots

Link the required KDEs

Operational compliance checklist

Related FDA resources

`TlcSource`