Create an EventCreate a Commission event

Create a Commission Event

Create a Commission 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": "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",
          "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"
                }
              ]
            }
          }
        }
      ],
      "Id": "commission_001",
      "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"
        }
      ]
    }
  ]
}'

{
  "message": "Events processed successfully",
  "result": [
    {
      "id": "01a0d877-7871-79a5-a8c8-a2f45673633d",
      "externalEventId": "commission_001",
      "type": "Commission",
      "status": "Created",
      "eventDate": "2024-03-30T13: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 Commission event represents a product coming into existence in its documented supply chain.


This typically occurs at the furthest upstream point of the traceability journey — either at the point of harvest or the first time a product is being documented as itself.


The purpose of this endpoint is to create a Commission event in Wholechain.




Creating a Commission Event


To create a Commission event, submit an event payload containing:


    

  • The event information
    • 

  • The Location where the product is being commissioned
    • 

  • The Lot Number being commissioned
    • 

  • The Product associated with that Product Instance
    • 



Some fields are always required, while others are only required when the referenced Location or Product does not already exist in your Wholechain master data.


Use the Required column in the tables below to determine which fields must be provided.




Request Body Parameters


Event Object


Column NameData TypeDescriptionRequired
IdSTRINGUnique identifier for the Commission event.Yes
PurchaseOrderSTRINGPurchase order associated with the event.No
InvoiceNumberSTRINGInvoice number associated with the event.No
EventTimeDATETIMELocal 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
EventTimeZoneSTRINGOptional. 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 Object


Every Commission event must identify the Location where the product is being commissioned.


Column NameData TypeDescriptionRequired
Location.IdSTRINGUnique identifier for the Location.Yes
Location.DetailsOBJECTInformation used to identify or create the Location.Yes if Location does not exist


Location Master Data


The Location.Id tells Wholechain which Location the Commission event occurred at.


If that Location already exists in your Wholechain master data, the Id is sufficient.


"Location": {
  "Id": "4567"
}



If the supplied Location.Id does not already exist in your Wholechain master data, the Details object must be included.


Wholechain will use the information in Details to create the Location before processing the Commission event.


"Location": {
  "Id": "4567",
  "Details": {
    "TradePartner": {
      "Id": "TpId123",
      "Name": "Me",
      "ConnectionType": "SELF"
    },
    "Name": "Processing",
    "Address": {
      "Country": "South Africa",
      "AddressLine1": "75 Bay Beach Avenue",
      "PostalCode": "8001"
    }
  }
}



This ensures the Location required by the Commission event exists before the event is processed.




Location Details Object


Trade Partner


A Location must belong to a Trade Partner.


Column NameData TypeDescriptionRequired
TradePartnerOBJECTTrade Partner associated with the Location.Yes
TradePartner.IdSTRINGUnique identifier for the Trade Partner.Yes
TradePartner.NameSTRINGName of the Trade Partner.Yes
TradePartner.ConnectionTypeSTRINGType of relationship, such as SELF, SUPPLIER, BUYER, or OTHER.Yes
TradePartner.DunsSTRINGDUNS number associated with the Trade Partner.No


If the Trade Partner referenced in the Location already exists, its existing identifier can be used.


If it does not exist, Wholechain will create the Trade Partner using the information supplied before creating the Location.




Location Information


Column NameData TypeDescriptionRequired
NameSTRINGName of the Location.Yes
GlnSTRINGGlobal Location Number of the Location.No
ExtensionSTRINGAdditional Location information.No
CaptainsNameSTRINGName of the captain, where applicable. Only if the location is a vessel.No
DunsPlus4STRINGFour additional digits used to identify a specific Location associated with a DUNS number.No




Contact Information Object


Contact information can optionally be supplied when creating the Location.


Column NameData TypeDescriptionRequired
ContactInformationOBJECTContact information associated with the Location.No
ContactInformation.NameSTRINGName of the contact person.No
ContactInformation.PhoneSTRINGPhone number of the contact person.No
ContactInformation.EmailSTRINGEmail address of the contact person.No




Address Object


The Address object contains the physical address associated with the Location.


Column NameData TypeDescriptionRequired
AddressOBJECTAddress information for the Location.Yes
Address.CitySTRINGCity where the Location is situated.No
Address.StateSTRINGState or region where the Location is situated.No
Address.CountrySTRINGCountry of the Location.Yes
Address.AddressLine1STRINGPrimary address line of the Location.Yes
Address.AddressLine2STRINGSecondary address line of the Location.No
Address.PostalCodeSTRINGPostal code of the Location.No
Address.GeoCoordinatesOBJECTGeographical coordinates of the Location.No
Address.GeoCoordinates.LatitudeDECIMALLatitude of the Location.Yes, if address information was not provided
Address.GeoCoordinates.LongitudeDECIMALLongitude of the Location.Yes, if address information was not provided




Product Instance Object


The ProductInstances array identifies the lot and quantity being commissioned.


At least one Product Instance must be included in the Commission event.


Column NameData TypeDescriptionRequired
QuantityDECIMALQuantity of the product being commissioned.Yes
LotSerialSTRINGLot or serial number associated with the Product Instance.Yes
ProductOBJECTProduct associated with the Product Instance.Yes
Product.IdSTRINGUnique identifier for the Product.Yes
Product.DetailsOBJECTInformation used to create the Product if it does not already exist.Required only if the product does not already exist




Product Master Data


Every Product Instance must reference a Product.


The Product.Id tells Wholechain which Product is being commissioned.


If the Product already exists in your Wholechain master data, the Product can be referenced using its existing Id.


"Product": {
  "Id": "raw_goods_000"
}



If the supplied Product.Id does not already exist in Wholechain, the Details object must be included.


Wholechain will create the Product using the information supplied before processing the Commission event.


"Product": {
  "Id": "raw_goods_000",
  "Details": {
    "Name": "RawGoods",
    "SimpleUnitOfMeasurement": "Lbs",
    "UnitQuantity": 16,
    "UnitDescriptor": "Cases",
    "SharingPolicy": "Restricted",
    "ProductIdentifierType": "Lot"
  }
}



This ensures the Product referenced by the Commission event exists before the event is processed.




Product Details Object


The following fields are used when the Product does not already exist in Wholechain.


Column NameData TypeDescriptionRequired
Product.Details.NameSTRINGName of the Product.Yes
Product.Details.SimpleUnitOfMeasurementSTRINGUnit of measurement for the Product, for example Lbs.Yes
Product.Details.UnitQuantityDECIMALQuantity associated with a defined unit, for example 16 for a 16 lb case.No
Product.Details.UnitDescriptorSTRINGDescription of the defined unit: one of Cases, Units, Totes, Pallets.No
Product.Details.SharingPolicySTRINGSharing policy for the Product, for example Restricted or Open.Yes
Product.Details.ProductIdentifierTypeSTRINGType of Product identifier, for example Lot.Yes




Example Commission Event Payload


The example below shows a complete Commission event.


It includes Location and Product Details to demonstrate a scenario where the Location and Product do not yet exist in Wholechain.


If those master data records already exist, the corresponding Details objects can be omitted.


{
  "Events": [
    {
      "$type": "commission",
      "Location": {
        "Id": "4567",
        "Details": {
          "TradePartner": {
            "Id": "TpId123",
            "Name": "Me",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing",
          "Gln": "9506000140445",
          "Extension": "Additional Location Information",
          "CaptainsName": "Captain Name",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Contact Name",
            "Phone": "+1234567890",
            "Email": "contact@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "75 Bay Beach Avenue",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "1990091",
          "Product": {
            "Id": "prod_000",
            "Details": {
              "Name": "RawGoods",
              "SimpleUnitOfMeasurement": "Lbs",
              "UnitQuantity": 16,
              "UnitDescriptor": "Cases",
              "SharingPolicy": "Restricted",
              "ProductIdentifierType": "Lot"
            }
          }
        }
      ],
      "Id": "0082932",
      "PurchaseOrder": "1990091",
      "InvoiceNumber": "12314154",
      "EventTime": "2024-03-30T13:00:00",
      "EventTimeZone": "-05:00"
    }
  ]
}





How Wholechain Processes the Payload


When the Commission event is submitted, Wholechain uses the information in the payload in the following order:


    

  1. Identify the Location using Location.Id.
    2. 

  2. If the Location does not exist, create it using Location.Details.
    3. 

  3. If the associated Trade Partner does not exist, create it using the supplied Trade Partner information.
    4. 

  4. Identify the Product using Product.Id.
    5. 

  5. If the Product does not exist, create it using Product.Details.
    6. 

  6. Once the required Location, Trade Partner, and Product master data exists, process the Commission event.
    7. 



If the event then fails validation, the master data created in steps 2–5 is not rolled back.


The Details fields therefore ensure that all master data required by the Commission event exists before Wholechain attempts to create the event.




Custom Properties and Certifications


A Commission event can also contain Custom Properties and Certifications when additional traceability information needs to be recorded.


The full example above includes CustomProperties and CertificationList; see the pages below for details.


For information about how to include them in your payload, see:





FSMA 204 Compliance


Additional event-specific fields may be required for certain traceability scenarios.


The TLC object is used for FSMA-related traceability scenarios where a vendor lot code changes and the relevant TLC information needs to be recorded.


For more information about TLC Source and other supported additional fields, see:


FSMA 204
Was this page helpful?