Decommission
Endpoint URL
https://connect.wholechain.com/Integration/Events
Sandbox URL
https://connect-sandbox.wholechain.com/Integration/Events
Method:
POST
Introduction
A Decommission event represents the removal of a product from its documented supply chain. It typically occurs when a product is no longer active in the supply chain journey — either because it has been consumed, discarded, expired, or otherwise taken out of circulation.
How it works:
- A Wholechain user can initiate a Decommission 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 decommissioned product is stored in the Wholechain database and written to the blockchain, establishing a clear point at which the product exits the supply chain.
Practical Examples
- Expired Lot Removal: A warehouse decommissions a lot of apples that have surpassed their expiration date, documenting the reason for removal and final quantities discarded.
- Seafood Loss Event: A distributor decommissions a portion of fish inventory that was spoiled during transport, recording the lot, condition, and loss details.
- Crop Rejection: A processor decommissions a shipment of wheat that failed quality testing, capturing the field ID, inspection results, and decommission reason.
Use Case
This API is typically used when an existing product is decommissioned (i.e., removed) from the supply chain system, ensuring transparency and accurate lifecycle tracking. The decommission event is crucial for traceability because it defines the exit of the product from the supply chain system, supporting compliance, loss reporting, and audit requirements.
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.
There is only one API Payload Option for the Decommission Event
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.
Request Headers for existing master data:
| 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 |
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 | No |
InvoiceNumber |
STRING | Invoice number linked to the event. | Not Primary | No |
BizStep |
STRING | Business step defining the event type. Learn more | Not Primary | No |
Disposition |
STRING | Status or condition of the item at the event time. Learn more | Not Primary | No |
EventTime |
DATETIME | Timestamp of when the event occurred. | Not Primary | Yes |
EventTimeZone |
STRING | Timezone of the event timestamp. | Not Primary | Yes |
Minimum Payload Examples
ℹ️ Note: The minimum data payload contains required fields.
⚠️ Warning: All fields in the minimum data payload must be provided, or the request will fail.
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": "decommission",
"Location": {
"Id": "4567"
},
"ProductInstances": [
{
"Quantity": 190.75,
"LotSerial": "123",
"Product": {
"Id": "raw_goods_000"
}
}
],
"Id": "0002",
"EventTime": "2024-03-30T13:00:00+00:00",
"EventTimeZone": "-05:00"
}
]
}
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 = "decommission",
Location = new { Id = "4567" },
ProductInstances = new[]
{
new
{
Quantity = 190.75,
LotSerial = "123",
Product = new { Id = "raw_goods_000" }
}
},
Id = "0002",
EventTime = "2024-03-30T13:00:00+00:00",
EventTimeZone = "-05:00"
}
}
};
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": "decommission",
"Location": { "Id": "4567" },
"ProductInstances": [
{
"Quantity": 190.75,
"LotSerial": "123",
"Product": { "Id": "raw_goods_000" }
}
],
"Id": "0002",
"EventTime": "2024-03-30T13:00:00+00:00",
"EventTimeZone": "-05:00"
}
]
}'
Additional Fields
In addition to the minimum required data payloads, you may include a range of optional fields, shown in the full payload example below. Refernce to them is made in the tables above where required = "No".
We also support several specialized objects:
- Custom Properties Object – Allows you to attach custom properties to a specific event. See the reference table below for details.
- Certificate Object – Enables you to include certification details related to an event. See the reference table below.
- TLC Object (for FSMA compliance) – Used only when changing the vendor lot code upon receiving a product. In that case, include the vendor lot in the TLC object and also record the TLC lot code.
All of these fields are optional, but they provide flexibility to capture additional, event-specific information when needed.
Custom Properties Object
| Column Name | Data Type | Description | Identifier | Required |
|---|---|---|---|---|
Name |
STRING | The name of the custom property. | Not Primary | Yes |
Namespace |
STRING | The namespace associated with the property. | Not Primary | No |
Value |
STRING | The value assigned to the custom property. | Not Primary | Yes |
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 |
Important Information About TLC Source
TLC Source offers two ways to identify a location in your data:
-
Using a TLC Source Reference: Provide a reference, such as a GLN number, to identify a location.
-
Using TLC Location Details: Provide the full location address information (e.g., country, street address, city, etc.) to specify the location.
Below are two example payload formats, each demonstrating one of these options, along with tables for reference.
TLC Object (Using Reference Details)
| Field Name | Data Type | Description | Primary Key | Required |
|---|---|---|---|---|
TlcSource |
OBJECT | Source information for the traceability lot code (TLC). | Not Primary | Yes |
Type |
STRING | Default to "Identifier" | Primary | Yes |
Reference |
STRING | What is the identifier (eg, DUNS, GLN, MSC Etc) | Primary | Yes |
Identifier |
STRING | Actual value of the identification | Primary | Yes |
TLC Object (Using Location Details)
| Field Name | Data Type | Description | Primary Key | Required |
|---|---|---|---|---|
TlcSource |
OBJECT | Source information for the traceability lot code (TLC). | Not Primary | Yes |
TlcSource.LocationName |
STRING | Name of the TLC location. | Not Primary | Yes |
TlcSource.CompanyName |
STRING | Name of the company associated with the TLC. | Not Primary | Yes |
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 | Yes |
TlcSource.Line1 |
STRING | Primary address line of the source. | Not Primary | Yes |
TlcSource.Line2 |
STRING | Secondary address line of the source. | Not Primary | No |
TlcSource.PostalCode |
STRING | Postal code of the source. | Not Primary | No |
TlcSource.Phone |
STRING | Contact phone number for the source. | Not Primary | Yes |
TlcSource.Type |
STRING | Type of TLC source (e.g., MasterData). | Not Primary | Yes |
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 All Fields Included
{
"Events": [
{
"$type": "decommission",
"Location": {
"Id": "4567"
},
"ProductInstances": [
{
"Quantity": 190.75,
"LotSerial": "1990091",
"Product": {
"Id": "prod_000"
},
"TraceabilityLotCode": "1234567989",
"TlcSource": {
"Type": "Identifier",
"Reference": "Eg: BAP",
"Identifier": "BAP01283"
}
}
],
"Id": "0082932",
"PurchaseOrder": "1990091",
"InvoiceNumber": "12314154",
"BizStep": "urn:epcglobal:cbv:bizstep:decommissioning",
"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": ""
}
],
"CertificationList": [
{
"Type": "urn:gdst:certType:harvestCoC",
"Standard": "MSC Chain of Custody",
"Agency": "MSC",
"Value": "NO",
"Identification": "NA"
}
]
}
]
}
{
"Events": [
{
"$type": "commission",
"Location": {
"Id": "4567"
},
"ProductInstances": [
{
"Quantity": 190.75,
"LotSerial": "1990091",
"Product": {
"Id": "prod_000"
},
"TraceabilityLotCode": "1234567989",
"TlcSource": {
"LocationName": "Test TLC Location",
"CompanyName": "Test TLC Company",
"City": "Test City",
"Country": "Test Country",
"Line1": "Address Line 1",
"Line2": "Address Line 2",
"PostalCode": "987654",
"Phone": "+55951254875",
"Type": "MasterData",
"GeoCoordinates": {
"Latitude": 12.345678,
"Longitude": 98.765432
}
}
}
],
"Id": "0082932",
"PurchaseOrder": "1990091",
"InvoiceNumber": "12314154",
"BizStep": "urn:epcglobal:cbv:bizstep:decommissioning",
"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": ""
}
],
"CertificationList": [
{
"Type": "urn:gdst:certType:harvestCoC",
"Standard": "MSC Chain of Custody",
"Agency": "MSC",
"Value": "NO",
"Identification": "NA"
}
]
}
]
}