Endpoint URL

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

Sandbox URL

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

Method:

POST

Introduction

A Commission event represents a product coming into existence in its documented supply chain. It typically occurs at the farthest upstream point of the traceability journey - either the point of harvest, or the first time that a product is being documented as itself.

How it works:

A Wholechain user can initiate a Commission event directly from the product’s current inventory page or via the Wholechain API, with the flexibility to incorporate custom data as needed.
The record of the commissioned product is stored in the Wholechain database and written to the blockchain, establishing the origin point of the product within the supply chain.

Practical Examples

A shipment of apples is decommissioned after a portion of the crates is found to be damaged during transit and is deemed unfit for sale.
A product is purchased by a customer at a retail store.

Use Case

This API is typically used when a new product is commissioned (i.e., registered) in the supply chain system, capturing its initial creation and linking it to the appropriate metadata. The commissioning event is crucial for traceability because it defines the entry of the product into the supply chain system with all required certifications and compliance standards.

Authentication

The API uses an API key (X-API-KEY) to authenticate requests. Each user has a unique API key that controls access to event details tied to their company. To understand where this can be found, please visit the Authentication page.

Two API Payload Options for the Commission Event

When using the Commission Event API, there are two distinct payload options available, depending on your needs:

1. Reference Existing Products, Trade Partners, and Locations

This payload is designed for users who already have their products, trade partners, and locations pre-configured within their Wholechain account.
It references these existing entities using their unique IDs.
Click here for the Reference Payload

2. Create Products, Locations, and Trade Partners On-the-Go

This payload is designed for users who want to dynamically create new products, trade partners, or locations directly through the API without pre-configuring them in Wholechain.
The API intelligently processes the payload to identify and create new entities if the provided IDs do not already exist in your account.
Click here for the On-the-Go Payload

Request Headers:

Header	Description	Example Value
`X-API-KEY`	Your API key	`08a3b47b-fc51-4eed-ae7e-a96fe4f49c64`
`Content-Type`	Content type of the request	`application/json`
`accept`	Response content type	`/`

Request Body Parameters:

This document outlines the database schema for storing JSON event data. Each table corresponds to a distinct data object in the JSON structure.

Location Object

Column Name	Data Type	Description	Identifier	Required
`Location ID`	STRING	Unique identifier for the location.	Primary	Yes

Product Instance Object

Column Name	Data Type	Description	Identifier	Required
`Quantity`	DECIMAL	Quantity of the product in the instance.	Not Primary	Yes
`LotSerial`	STRING	Lot or serial number of the product instance.	Not Primary	Yes
`Product ID`	STRING	Unique identifier for the product.	Primary	Yes
`TlcSource`	OBJECT	Information about the traceability source, including location details.	Not Primary	No

Event Object

Column Name	Data Type	Description	Identifier	Required
`Id`	STRING	Unique identifier for the event.	Not Primary	Yes
`PurchaseOrder`	STRING	Purchase order associated with the event.	Not Primary	Yes
`InvoiceNumber`	STRING	Invoice number linked to the event.	Not Primary	Yes
`BizStep`	STRING	Business step defining the event type. Learn more	Not Primary	Yes
`Disposition`	STRING	Status or condition of the item at the event time. Learn more	Not Primary	Yes
`EventTime`	DATETIME	Timestamp of when the event occurred.	Not Primary	Yes
`EventTimeZone`	STRING	Timezone of the event timestamp.	Not Primary	Yes

Custom Properties Object

Column Name	Data Type	Description	Identifier	Required
`Name`	STRING	The name of the custom property.	Not Primary	No
`Namespace`	STRING	The namespace associated with the property.	Not Primary	No
`Value`	STRING	The value assigned to the custom property.	Not Primary	No
`PropertyLocation`	STRING	Location where the property is applied, such as ILMD.	Not Primary	No

Certification List Object

Column Name	Data Type	Description	Identifier	Required
`Type`	STRING	The type of certification (e.g., harvest CoC).	Not Primary	No
`Standard`	STRING	The certification standard being referenced.	Not Primary	No
`Agency`	STRING	The agency issuing the certification.	Not Primary	No
`Value`	STRING	The value of the certification (e.g., Yes/No).	Not Primary	No
`Identification`	STRING	Identifier for the certification, if applicable.	Not Primary	No

Example Requests

PythonC#Curl

import requests

url = 'https://connect.wholechain.com/Integration/Events'
headers = {
    'accept': '*/*',
    'X-API-KEY': '0193d105-03f6-7829-8de1-d55c166a35f6',
    'Content-Type': 'application/json'
}
data = {
    "Events": [
    {
    "$type": "commission",
    "Location": {
        "Id": "4567"
    },
    "ProductInstances": [
        {
        "Quantity": 190.75,
        "LotSerial": "123",
        "Product": {
            "Id": "raw_goods_000",
            "Details": {
                "Name": "RawGoods",
                "SimpleUnitOfMeasurement": "Lbs",
                "SharingPolicy": "Restricted",
                "ProductIdentifierType": "Lot"
            }
        },
        "TlcSource": {
            "Name": "TLC_123",
            "City": "City Name",
            "State": "State Name",
            "Country": "Country Name",
            "AddressLine1": "123 Main St",
            "AddressLine2": "Apt 4B",
            "PostalCode": "12345",
            "GeoCoordinates": {
                "Latitude": 12.345678,
                "Longitude": 98.765432
            }
        }
        }
    ],
    "Id": "0002",
    "PurchaseOrder": "1990091",
    "InvoiceNumber": "12314154",
    "BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
    "Disposition": "urn:epcglobal:cbv:disp:active",
    "EventTime": "2024-03-30T13:00:00+00:00",
    "EventTimeZone": "-05:00",
    "CustomProperties": [
        {
        "Name": "expiry_date",
        "Namespace": "",
        "Value": "2024-03-30",
        "PropertyLocation": "ILMD"
        }
    ],
    "CertificationList": [
        {
        "Type": "urn:gdst:certType:harvestCoC",
        "Standard": "MSC Chain of Custody",
        "Agency": "MSC",
        "Value": "NO",
        "Identification": "NA"
        }
    ]
    }
]
}

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

print(response.status_code)
print(response.json())

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://connect.wholechain.com/Integration/Events";
        var apiKey = "0193d105-03f6-7829-8de1-d55c166a35f6";

        var data = new
        {
            Events = new[]
            {
                new
                {
                    $type = "commission",
                    Location = new
                    {
                        Id = "4567"
                    },
                    ProductInstances = new[]
                    {
                        new
                        {
                            Quantity = 190.75,
                            LotSerial = "123",
                            Product = new
                            {
                                Id = "raw_goods_000",
                                Details = new
                                {
                                    Name = "RawGoods",
                                    SimpleUnitOfMeasurement = "Lbs",
                                    SharingPolicy = "Restricted",
                                    ProductIdentifierType = "Lot"
                                }
                            },
                            TlcSource = new
                            {
                                Name = "TLC_123",
                                City = "City Name",
                                State = "State Name",
                                Country = "Country Name",
                                AddressLine1 = "123 Main St",
                                AddressLine2 = "Apt 4B",
                                PostalCode = "12345",
                                GeoCoordinates = new
                                {
                                    Latitude = 12.345678,
                                    Longitude = 98.765432
                                }
                            }
                        }
                    },
                    Id = "0002",
                    PurchaseOrder = "1990091",
                    InvoiceNumber = "12314154",
                    BizStep = "urn:epcglobal:cbv:bizstep:commissioning",
                    Disposition = "urn:epcglobal:cbv:disp:active",
                    EventTime = "2024-03-30T13:00:00+00:00",
                    EventTimeZone = "-05:00",
                    CustomProperties = new[]
                    {
                        new
                        {
                            Name = "expiry_date",
                            Namespace = "",
                            Value = "2024-03-30",
                            PropertyLocation = "ILMD"
                        }
                    },
                    CertificationList = new[]
                    {
                        new
                        {
                            Type = "urn:gdst:certType:harvestCoC",
                            Standard = "MSC Chain of Custody",
                            Agency = "MSC",
                            Value = "NO",
                            Identification = "NA"
                        }
                    }
                }
            }
        };

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("accept", "*/*");
            client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);

            var json = JsonConvert.SerializeObject(data);
            var content = new StringContent(json, Encoding.UTF8, "application/json");

            var response = await client.PostAsync(url, content);

            Console.WriteLine($"Status Code: {response.StatusCode}");
            var responseContent = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseContent);
        }
    }
}

curl -X POST https://connect.wholechain.com/Integration/Events \
-H "accept: */*" \
-H "X-API-KEY: 0193d105-03f6-7829-8de1-d55c166a35f6" \
-H "Content-Type: application/json" \
-d '{
"Events": [
    {
    "$type": "commission",
    "Location": {
        "Id": "4567"
    },
    "ProductInstances": [
        {
        "Quantity": 190.75,
        "LotSerial": "123",
        "Product": {
            "Id": "raw_goods_000",
            "Details": {
                "Name": "RawGoods",
                "SimpleUnitOfMeasurement": "Lbs",
                "SharingPolicy": "Restricted",
                "ProductIdentifierType": "Lot"
            }
        },
        "TlcSource": {
            "Name": "TLC_123",
            "City": "City Name",
            "State": "State Name",
            "Country": "Country Name",
            "AddressLine1": "123 Main St",
            "AddressLine2": "Apt 4B",
            "PostalCode": "12345",
            "GeoCoordinates": {
                "Latitude": 12.345678,
                "Longitude": 98.765432
            }
        }
        }
    ],
    "Id": "0002",
    "PurchaseOrder": "1990091",
    "InvoiceNumber": "12314154",
    "BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
    "Disposition": "urn:epcglobal:cbv:disp:active",
    "EventTime": "2024-03-30T13:00:00+00:00",
    "EventTimeZone": "-05:00",
    "CustomProperties": [
        {
        "Name": "expiry_date",
        "Namespace": "",
        "Value": "2024-03-30",
        "PropertyLocation": "ILMD"
        }
    ],
    "CertificationList": [
        {
        "Type": "urn:gdst:certType:harvestCoC",
        "Standard": "MSC Chain of Custody",
        "Agency": "MSC",
        "Value": "NO",
        "Identification": "NA"
        }
    ]
    }
]
}'

Creating Locations, Trade Partners, and Products On-the-Go

In many cases, users may need the ability to dynamically create new locations, trade partners, or products directly within the API instead of pre-configuring them within the Wholechain platform. This is particularly useful when dealing with constantly changing locations, new trade partners, or orders that cannot feasibly be manually added to both an ERP system and Wholechain.

To address this need, we’ve introduced the "Details" object within specific sections of the API payload. This allows the API to intelligently handle new or existing entities, ensuring a seamless and flexible experience.

How It Works

Details Section

The "Details" section is used to provide additional metadata for locations, trade partners, or products. The behavior of the API depends on whether the IDs in the payload already exist in your Wholechain account. Here’s how the process works:

1. ID Matching Logic:

If the ID in the payload already exists in your Wholechain account, the API will skip over the "Details" section and use the pre-existing information from your Wholechain system.
If the ID is new (i.e., it does not exist in your Wholechain account), the API will use the information in the "Details" section to create a new location, trade partner, or product.

2. Mix-and-Match Capabilities:

You can mix new and existing entities within the same API request. For example:
- Use a new location ID with details for creation.
- Reference an existing trade partner ID without additional details.
- Reference an existing product ID while creating a new location or trade partner.

3. Required Fields for New Entities:

When creating a new entity (location, trade partner, or product), provide an ID that does not currently exist in your Wholechain account. Include additional metadata in the "Details" section (e.g., name, address, GLN, and other relevant fields).

ProductInstances

If the Product.Id exists in your Wholechain account:
The API skips the product details and references the existing product information.
If the Product.Id is new:
The API creates a new product based on the details provided in the payload.

Key Considerations

Ensure that IDs for new entities (locations, trade partners, products) are unique and do not conflict with existing IDs in your Wholechain account.
The "Details" section provides flexibility to dynamically create new entities while still allowing references to existing ones.
If a field is skipped (e.g., "Details" for an existing ID), no changes will be made to the existing entity in Wholechain.

Location Details Object

Column Name	Data Type	Description	Identifier	Required
`TradePartner`	OBJECT	Details of the trade partner associated with the location.	Not Primary	Yes if creating new
`TradePartner.Id`	STRING	Unique identifier for the trade partner.	Primary	Yes if creating new
`TradePartner.Name`	STRING	Name of the trade partner.	Not Primary	Yes if creating new
`TradePartner.ConnectionType`	STRING	Type of connection (e.g., SELF).	Not Primary	Yes if creating new
`TradePartner.Duns`	STRING	DUNS (Data Universal Numbering System) number of the partner.	Not Primary	Yes if creating new
`Name`	STRING	Name of the location.	Not Primary	Yes if creating new
`Gln`	STRING	Global Location Number of the location.	Not Primary	No
`Extension`	STRING	Additional location information.	Not Primary	No
`CaptainsName`	STRING	Name of the captain (if applicable).	Not Primary	No
`DunsPlus4`	STRING	Four additional digits to refine the DUNS number for specific location	Not Primary	No
`ContactInformation`	OBJECT	Contact information for the location.	Not Primary	Yes if creating new
`ContactInformation.Name`	STRING	Name of the contact person at the location.	Not Primary	Yes if creating new
`ContactInformation.Phone`	STRING	Phone number of the contact person.	Not Primary	Yes if creating new
`ContactInformation.Email`	STRING	Email address of the contact person.	Not Primary	Yes if creating new
`Address`	OBJECT	Address details of the location.	Not Primary	Yes if creating new
`Address.City`	STRING	City where the location is situated.	Not Primary	Yes if creating new
`Address.State`	STRING	State where the location is situated.	Not Primary	Yes if creating new
`Address.Country`	STRING	Country of the location.	Not Primary	Yes if creating new
`Address.AddressLine1`	STRING	Primary address line of the location.	Not Primary	Yes if creating new
`Address.AddressLine2`	STRING	Secondary address line of the location.	Not Primary	No
`Address.PostalCode`	STRING	Postal code of the location.	Not Primary	Yes if creating new
`Address.GeoCoordinates`	OBJECT	Geographical coordinates of the location.	Not Primary	No
`GeoCoordinates.Latitude`	DECIMAL	Latitude of the location.	Not Primary	No
`GeoCoordinates.Longitude`	DECIMAL	Longitude of the location.	Not Primary	No

ProductInstance Details Object

Column Name	Data Type	Description	Identifier	Required
`Quantity`	DECIMAL	Quantity of the product instance.	Not Primary	Yes if creating new
`LotSerial`	STRING	Lot or serial number of the product instance.	Not Primary	Yes if creating new
`Product`	OBJECT	Details of the product being received.	Not Primary	Yes if creating new
`Product.Id`	STRING	Unique identifier for the product.	Primary	Yes if creating new
`Product.Details`	OBJECT	Additional product metadata.	Not Primary	Yes if creating new
`Product.Details.Name`	STRING	Name of the product.	Not Primary	Yes if creating new
`Product.Details.SimpleUnitOfMeasurement`	STRING	Unit of measurement (e.g., Lbs).	Not Primary	Yes if creating new
`Product.Details.SharingPolicy`	STRING	Sharing policy for the product (e.g., Restricted).	Not Primary	Yes if creating new
`Product.Details.ProductIdentifierType`	STRING	Type of product identifier (e.g., Lot).	Not Primary	Yes if creating new
`TlcSource`	OBJECT	Source information for the traceability lot code (TLC).	Not Primary	No
`TlcSource.Name`	STRING	Name of the source.	Not Primary	No
`TlcSource.City`	STRING	City of the source.	Not Primary	No
`TlcSource.State`	STRING	State of the source.	Not Primary	No
`TlcSource.Country`	STRING	Country of the source.	Not Primary	No
`TlcSource.AddressLine1`	STRING	Primary address line of the source.	Not Primary	No
`TlcSource.AddressLine2`	STRING	Secondary address line of the source.	Not Primary	No
`TlcSource.PostalCode`	STRING	Postal code of the source.	Not Primary	No
`TlcSource.GeoCoordinates`	OBJECT	Geographical coordinates of the source.	Not Primary	No
`GeoCoordinates.Latitude`	DECIMAL	Latitude of the source.	Not Primary	No
`GeoCoordinates.Longitude`	DECIMAL	Longitude of the source.	Not Primary	No

Example Payload

Json

data = {
    "Events": [
    {
    "$type": "commission",
    "Location": {
        "Id": "4567",
        "Details": {
        "TradePartner": {
            "Id": "TpId123",
            "Name": "Me",
            "ConnectionType": "SELF",
            "Duns": "123456789"
        },
        "Name": "Processing",
        "Gln": "9506000140445",
        "Extension": "SomeExtension",
        "DunsPlus4": "1234",
        "ContactInformation": {
            "Name": "Contact Name",
            "Phone": "+1234567890",
            "Email": "contact@example.com"
        },
        "Address": {
            "City": "City Name",
            "State": "State Name",
            "Country": "Country Name",
            "AddressLine1": "123 Main St",
            "AddressLine2": "Apt 4B",
            "PostalCode": "12345",
            "GeoCoordinates": {
            "Latitude": 12.345678,
            "Longitude": 98.765432
            }
        }
        }
    },
    "ProductInstances": [
        {
        "Quantity": 190.75,
        "LotSerial": "123",
        "Product": {
            "Id": "raw_goods_000",
            "Details": {
                "Name": "RawGoods",
                "SimpleUnitOfMeasurement": "Lbs",
                "SharingPolicy": "Restricted",
                "ProductIdentifierType": "Lot"
            }
        },
        "TlcSource": {
            "Name": "TLC_123",
            "City": "City Name",
            "State": "State Name",
            "Country": "Country Name",
            "AddressLine1": "123 Main St",
            "AddressLine2": "Apt 4B",
            "PostalCode": "12345",
            "GeoCoordinates": {
                "Latitude": 12.345678,
                "Longitude": 98.765432
            }
        }
        }
    ],
    "Id": "0002",
    "PurchaseOrder": "1990091",
    "InvoiceNumber": "12314154",
    "BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
    "Disposition": "urn:epcglobal:cbv:disp:active",
    "EventTime": "2024-03-30T13:00:00+00:00",
    "EventTimeZone": "-05:00",
    "CustomProperties": [
        {
        "Name": "expiry_date",
        "Namespace": "",
        "Value": "2024-03-30",
        "PropertyLocation": "ILMD"
        }
    ],
    "CertificationList": [
        {
        "Type": "urn:gdst:certType:harvestCoC",
        "Standard": "MSC Chain of Custody",
        "Agency": "MSC",
        "Value": "NO",
        "Identification": "NA"
        }
    ]
    }
]
}