Create a Transform Event

Create a Transform Event. The request example includes all fields documented for this event, including optional fields.

curl -X POST "https://connect.wholechain.com/Integration/Events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Events": [
    {
      "$type": "transform",
      "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
            }
          }
        }
      },
      "InputProducts": [
        {
          "Quantity": 180.75,
          "LotSerial": "input_lot_001",
          "Product": {
            "Id": "raw_goods_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"
                }
              ]
            }
          }
        }
      ],
      "OutputProducts": [
        {
          "Quantity": 175.5,
          "LotSerial": "output_lot_001",
          "Product": {
            "Id": "finished_goods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Finished Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "transform_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T19: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": "transform",
      "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
            }
          }
        }
      },
      "InputProducts": [
        {
          "Quantity": 180.75,
          "LotSerial": "input_lot_001",
          "Product": {
            "Id": "raw_goods_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"
                }
              ]
            }
          }
        }
      ],
      "OutputProducts": [
        {
          "Quantity": 175.5,
          "LotSerial": "output_lot_001",
          "Product": {
            "Id": "finished_goods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Finished Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "transform_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T19: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": "transform",
      "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
            }
          }
        }
      },
      "InputProducts": [
        {
          "Quantity": 180.75,
          "LotSerial": "input_lot_001",
          "Product": {
            "Id": "raw_goods_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"
                }
              ]
            }
          }
        }
      ],
      "OutputProducts": [
        {
          "Quantity": 175.5,
          "LotSerial": "output_lot_001",
          "Product": {
            "Id": "finished_goods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Finished Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "transform_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T19: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": "transform",
      "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
            }
          }
        }
      },
      "InputProducts": [
        {
          "Quantity": 180.75,
          "LotSerial": "input_lot_001",
          "Product": {
            "Id": "raw_goods_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"
                }
              ]
            }
          }
        }
      ],
      "OutputProducts": [
        {
          "Quantity": 175.5,
          "LotSerial": "output_lot_001",
          "Product": {
            "Id": "finished_goods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Finished Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "transform_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T19: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": "transform",
      "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
            }
          }
        }
      },
      "InputProducts": [
        {
          "Quantity": 180.75,
          "LotSerial": "input_lot_001",
          "Product": {
            "Id": "raw_goods_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"
                }
              ]
            }
          }
        }
      ],
      "OutputProducts": [
        {
          "Quantity": 175.5,
          "LotSerial": "output_lot_001",
          "Product": {
            "Id": "finished_goods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Finished Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "transform_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T19: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": "01a0d877-7871-79a5-a8c8-a2f45673633d",
      "externalEventId": "transform_001",
      "type": "Transform",
      "status": "Created",
      "eventDate": "2024-03-30T19:00:00+00:00",
      "productInstances": [
        {
          "quantity": 190.75,
          "lotSerial": "lot_001",
          "status": "Created",
          "id": "01a0d877-7871-7426-b365-3a587ad4f893",
          "name": "Raw Goods",
          "urn": "urn:gdst:wholechain.com:product:lot:class:raindropsolutions.rawgoods-1.lot_001"
        }
      ],
      "containers": [],
      "directShipFallback": null,
      "externalShipmentFailure": null
    }
  ],
  "locations": [
    {
      "id": "01a0d877-76de-7e96-ac8c-962a914952bf",
      "status": "Created"
    }
  ],
  "products": [
    {
      "id": "01a0d877-7719-720e-8fd8-224e3fec0602",
      "status": "Created"
    }
  ],
  "errors": [],
  "validations": []
}

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

header

X-API-KEYstring

Required

API key used to authenticate the request.

Eventsarray

Required

Required. events.

Request Preview

Response

Response will appear here after sending the request

Responses

messagestring

Optional. message.

resultarray

Optional. result.

locationsarray

Optional. locations.

productsarray

Optional. products.

errorsobject[]

Optional. errors.

validationsobject[]

Optional. validations.

Introduction

A Transform event records when one or more input lots are irreversibly changed into one or more new output lots.

Examples include:

processing raw material into a finished product
cutting or portioning a product
combining multiple lots into a new production lot
packaging a product into a new traceable product
transforming one input lot into multiple output lots
combining multiple input lots into one output lot

The output product receives its own lot or serial number and becomes a new traceable product instance.

A Transform event identifies:

where the transformation occurred using Location
which lots were consumed using InputProducts
which new lots were created using OutputProducts
how much input and output product was involved using Quantity
when the transformation occurred using EventTime
the unique identifier of the Transform event using Id

Request Headers

Header	Description	Example Value
`X-API-KEY`	Your API key.	`YOUR_API_KEY_HERE`
`Content-Type`	Content type of the request.	`application/json`
`accept`	Response content type.	`/`

Request Body

Event Object

Field	Type	Description	Required
`$type`	STRING	Defines the event type. For a Transform event, use `transform`.	Yes
`Location`	OBJECT	Location where the transformation took place.	Yes
`InputProducts`	ARRAY	Product lots consumed by the transformation.	Yes
`OutputProducts`	ARRAY	New product lots created by the transformation.	Yes
`Id`	STRING	Unique identifier for the Transform event.	Yes
`PurchaseOrder`	STRING	Purchase order associated with the event.	No
`InvoiceNumber`	STRING	Invoice number associated with the event.	No
`EventTime`	DATETIME	Local date and time when the event occurred, without a UTC offset, for example `2024-03-30T13:00:00`. The time zone is taken from `EventTimeZone`. Any offset included in this value is ignored.	Yes
`EventTimeZone`	STRING	Optional. Time zone of the event as a UTC offset in ±HH:MM format, for example `-05:00`. If omitted, the account's default time zone (selected when the account was created) is used.	No

Location

Location identifies where the transformation took place.

"Location": {
  "Id": "processing_000",
  "Details": {
    "TradePartner": {
      "Id": "processor_001",
      "Name": "Processor Name",
      "ConnectionType": "SELF",
      "Duns": "123456789"
    },
    "Name": "Processing Facility",
    "Gln": "9506000140445",
    "Extension": "SomeExtension",
    "ContactInformation": {
      "Name": "Contact Name",
      "Phone": "+1234567890",
      "Email": "contact@example.com"
    },
    "Address": {
      "City": "City Name",
      "State": "State Name",
      "Country": "Country Name",
      "AddressLine1": "123 Processing Street",
      "AddressLine2": "Building 2",
      "PostalCode": "12345",
      "GeoCoordinates": {
        "Latitude": 12.345678,
        "Longitude": 98.765432
      }
    }
  }
}

Location Fields

Field	Type	Description	Required
`Id`	STRING	Unique identifier for the location.	Yes
`Details`	OBJECT	Details associated with the location.	Required only if the location does not already exist
`Details.TradePartner`	OBJECT	Trade partner associated with the location.	Yes
`Details.TradePartner.Id`	STRING	Unique identifier for the trade partner.	Yes
`Details.TradePartner.Name`	STRING	Name of the trade partner.	Yes
`Details.TradePartner.ConnectionType`	STRING	Relationship type, e.g. `SELF`, `SUPPLIER`, `BUYER`, or `OTHER`.	Yes
`Details.TradePartner.Duns`	STRING	DUNS number of the trade partner.	No
`Details.Name`	STRING	Name of the location.	Yes
`Details.Gln`	STRING	Global Location Number.	No
`Details.Extension`	STRING	Additional location information.	No
`Details.ContactInformation`	OBJECT	Contact information associated with the location.	No
`Details.ContactInformation.Name`	STRING	Contact person's name.	No
`Details.ContactInformation.Phone`	STRING	Contact phone number.	No
`Details.ContactInformation.Email`	STRING	Contact email address.	No
`Details.Address`	OBJECT	Address of the location.	Yes
`Details.Address.City`	STRING	City.	No
`Details.Address.State`	STRING	State or province.	No
`Details.Address.Country`	STRING	Country.	Yes
`Details.Address.AddressLine1`	STRING	Primary address line.	Yes
`Details.Address.AddressLine2`	STRING	Secondary address line.	No
`Details.Address.PostalCode`	STRING	Postal code.	No
`Details.Address.GeoCoordinates`	OBJECT	Geographic coordinates.	No
`Details.Address.GeoCoordinates.Latitude`	DECIMAL	Latitude.	No
`Details.Address.GeoCoordinates.Longitude`	DECIMAL	Longitude.	No

Input Products

InputProducts identifies the product lots consumed during the transformation.

"InputProducts": [
  {
    "Quantity": 180.75,
    "LotSerial": "INPUT-LOT-001",
    "Product": {
      "Id": "raw_goods_001"
    }
  }
]

Multiple input products can be included in the same Transform event.

Duplicate lot numbers should not be submitted separately within the same event. If the same lot is used more than once, combine the quantities into a single entry.

Output Products

OutputProducts identifies the new product lots created by the transformation.

Each output product should include the full product details structure so that the output product can be created on-the-go if it does not already exist.

"OutputProducts": [
  {
    "Quantity": 175.5,
    "LotSerial": "OUTPUT-LOT-001",
    "Product": {
      "Id": "product_id",
      "Details": {
        "ProductIdentifierType": "Lot",
        "Name": "Sample Product",
        "SimpleUnitOfMeasurement": "Kgm",
        "SharingPolicy": "Open",
        "UnitDescriptor": "Cases",
        "UnitQuantity": 10.5,
        "Gtin": "12345678912343",
        "Plu": "4001",
        "MasterData": [
          {
            "name": "Gear Type",
            "namespace": "custom",
            "value": "GEAR TYPE_VALUE"
          }
        ]
      }
    }
  }
]

The output product becomes a new traceable product instance with its own LotSerial.

A Transform event can contain:

one input → one output
one input → multiple outputs
multiple inputs → one output
multiple inputs → multiple outputs

Output Product Fields

Field	Type	Description	Required
`Quantity`	DECIMAL	Quantity of the output lot created.	Yes
`LotSerial`	STRING	New lot or serial number for the output.	Yes
`Product`	OBJECT	Product associated with the output lot.	Yes
`Product.Id`	STRING	Unique identifier for the output product.	Yes
`Product.Details`	OBJECT	Product master data for the output product.	Required only if the product does not already exist
`Product.Details.ProductIdentifierType`	STRING	Identifier type for the output product, e.g. `Lot`.	Yes
`Product.Details.Name`	STRING	Name of the output product.	Yes
`Product.Details.SimpleUnitOfMeasurement`	STRING	Unit in which the output product is measured.	Yes
`Product.Details.SharingPolicy`	STRING	Sharing policy, e.g. `Open` or `Restricted`.	Yes
`Product.Details.UnitDescriptor`	STRING	Commercial or packaging unit: `Cases`, `Units`, `Totes` or `Pallets`.	No
`Product.Details.UnitQuantity`	DECIMAL	Quantity contained within the commercial or packaging unit.	No
`Product.Details.Gtin`	STRING	Global Trade Item Number.	No
`Product.Details.Plu`	STRING	Price Lookup Code.	No
`Product.Details.MasterData`	ARRAY	Custom data stored against the output product.	No

Example Transform a Lot Payload — All Fields

The example below shows the standard Transform payload, including all supported location, input, output product, and event fields covered in this documentation.

{
  "Events": [
    {
      "$type": "transform",
      "Location": {
        "Id": "processing_000",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "City Name",
            "State": "State Name",
            "Country": "Country Name",
            "AddressLine1": "123 Processing Street",
            "AddressLine2": "Building 2",
            "PostalCode": "12345",
            "GeoCoordinates": {
              "Latitude": 12.345678,
              "Longitude": 98.765432
            }
          }
        }
      },
      "InputProducts": [
        {
          "Quantity": 180.75,
          "LotSerial": "INPUT-LOT-001",
          "Product": {
            "Id": "raw_goods_001"
          }
        }
      ],
      "OutputProducts": [
        {
          "Quantity": 175.5,
          "LotSerial": "OUTPUT-LOT-001",
          "Product": {
            "Id": "product_id",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Sample Product",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "transform_0001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2026-09-24T10:00:00",
      "EventTimeZone": "+00:00"
    }
  ]
}

Multiple Input and Output Lots

More than one input or output can be submitted in the same Transform event.

Each output should use the same full product structure.

"OutputProducts": [
  {
    "Quantity": 90,
    "LotSerial": "OUTPUT-LOT-001",
    "Product": {
      "Id": "finished_goods_001",
      "Details": {
        "ProductIdentifierType": "Lot",
        "Name": "Finished Product A",
        "SimpleUnitOfMeasurement": "Kgm",
        "SharingPolicy": "Open",
        "UnitDescriptor": "Cases",
        "UnitQuantity": 10.5,
        "Gtin": "12345678912343",
        "Plu": "4001",
        "MasterData": [
          {
            "name": "Gear Type",
            "namespace": "custom",
            "value": "GEAR TYPE_VALUE"
          }
        ]
      }
    }
  },
  {
    "Quantity": 85,
    "LotSerial": "OUTPUT-LOT-002",
    "Product": {
      "Id": "finished_goods_002",
      "Details": {
        "ProductIdentifierType": "Lot",
        "Name": "Finished Product B",
        "SimpleUnitOfMeasurement": "Kgm",
        "SharingPolicy": "Open",
        "UnitDescriptor": "Cases",
        "UnitQuantity": 10.5,
        "Gtin": "12345678912344",
        "Plu": "4002",
        "MasterData": [
          {
            "name": "Gear Type",
            "namespace": "custom",
            "value": "GEAR TYPE_VALUE"
          }
        ]
      }
    }
  }
]

Certifications and Custom Event Data

Certifications and custom event-level data can also be added to a Transform event but are documented separately.

→ See: ****Certifications

For information on attaching certifications to a Transform event, see the dedicated Certifications documentation.

→ See: ****Custom Event Data

For information on adding custom event fields using CustomProperties, see the dedicated Custom Event Data documentation.

These are separate from Product.Details.MasterData, which stores custom information against the product rather than the individual Transform event.

How Entity Creation Works

Locations, trade partners, and products are supplied directly within the standard Transform payload.

The API uses the supplied IDs to determine whether the entity already exists:

If the ID does not exist, Wholechain creates the entity using the supplied Details.
If the ID already exists, Wholechain uses the existing entity associated with that ID.
The same standard payload can therefore be used with both new and existing entities.

If an ID already exists, the API skips the supplied Details and uses the existing information stored in Wholechain.

Important Notes

Use $type: "transform" for a Transform event.
Location identifies where the transformation took place.
InputProducts identifies the lots consumed during the transformation.
OutputProducts identifies the new lots created by the transformation.
Input products can be referenced using their existing product IDs.
Output products should include the full Product.Details structure.
Each output lot should have its own new LotSerial.
A Transform can contain one or multiple input and output lots.
Product custom data is included using Product.Details.MasterData.
Gtin, Plu, UnitQuantity, UnitDescriptor, and MasterData should be omitted when they do not apply.
Certifications and custom event data are documented separately.

Was this page helpful?