Skip to content

Aggregate

Endpoint URL

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

Sandbox URL

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

Method:

POST

What is an Aggregate Event?

An Aggregate event documents when multiple discrete products are physically grouped together, typically for the purposes of shipping or storing. The individual items being aggregated are usually identified by the pallet, container, or another logistical unit in which they’re grouped. Aggregation always includes the intention to disaggregate the items again later downstream toward consumption.


How It Works

  • A Wholechain user selects multiple product items and creates an aggregation, grouping them together while retaining their individual properties.
  • Users have the option to assign the aggregation to a logistical unit or an SSCC for shipping.
  • The aggregated product can then be transferred, sent, or simply stored as an aggregation.
  • At any point, a user can reverse an aggregation in their current inventory by disaggregating the items back into their original form.
  • All aggregations are reversible.

Local image


Examples

  1. 50 cartons of strawberries are aggregated and loaded onto a pallet for shipment. Later, they are disaggregated back into the original 50 cartons of strawberries.

  2. 100 cases of bottled olive oil are aggregated and loaded into a shipping container for export. The individual cases will later be disaggregated back into the original 100 cases at the destination warehouse.


We only offer one API Payload Options for the Aggregate 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

Container Object

Column Name Data Type Description Identifier Required
Id STRING Unique identifier for the container. Not Primary Yes
Type STRING Type of the container (LogisticId OR SSCC). Not Primary Yes

Event Object

Column Name Data Type Description Identifier Required
Id STRING Unique identifier for the event. Not Primary Yes
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": "aggregation",
            "Location": {
                "Id": "4567"
            },
            "ProductInstances": [
                {
                    "Quantity": 190.75,
                    "LotSerial": "1990091",
                    "Product": {
                        "Id": "1234"
                    }
                }
            ],
            "Container": {
                "Id": "123456",
                "Type": "LogisticId"
            },
            "Id": "0023",
            "EventTime": "2024-03-30T14: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.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://connect.wholechain.com/Integration/Events";

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new MediaTypeWithQualityHeaderValue("*/*"));
            client.DefaultRequestHeaders.Add("X-API-KEY", "0193d105-03f6-7829-8de1-d55c166a35f6");

            var json = @"
            {
                ""Events"": [
                    {
                        ""$type"": ""aggregation"",
                        ""Location"": {
                            ""Id"": ""4567""
                        },
                        ""ProductInstances"": [
                            {
                                ""Quantity"": 190.75,
                                ""LotSerial"": ""1990091"",
                                ""Product"": {
                                    ""Id"": ""1234""
                                }
                            }
                        ],
                        ""Container"": {
                            ""Id"": ""123456"",
                            ""Type"": ""LogisticId""
                        },
                        ""Id"": ""0023"",
                        ""EventTime"": ""2024-03-30T14:00:00+00:00"",
                        ""EventTimeZone"": ""-05:00""
                    }
                ]
            }";

            var content = new StringContent(json, Encoding.UTF8, "application/json");
            var response = await client.PostAsync(url, content);

            Console.WriteLine((int)response.StatusCode);
            string responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseBody);
        }
    }
}
    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": "aggregation",
        "Location": {
        "Id": "4567"
        },
        "ProductInstances": [
        {
            "Quantity": 190.75,
            "LotSerial": "1990091",
            "Product": {
            "Id": "1234"
            }
        }
        ],
        "Container": {
        "Id": "123456",
        "Type": "LogisticId"
        },
        "Id": "0023",
        "EventTime": "2024-03-30T14: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

    data = {
    "Events": [
        {
            "$type": "aggregation",
            "Location": {
                "Id": "location_id",
            },
            "ProductInstances": [
                {
                    "Quantity": 190.75,
                    "LotSerial": "1990091",
                    "Product": {
                        "Id": "product_id",
                    },
                    "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
                        }
                    }
                },
                {
                    "Quantity": 190.75,
                    "LotSerial": "123",
                    "Product": {
                        "Id": "raw_goods_000",
                    },
                    "TraceabilityLotCode": "9876543210",
                    "TlcSource": {
                        "Type": "Identifier",
                        "Reference": "Eg: ASC",
                        "Identifier": "ASC00192"
                    }
                }
            ],
            "Id": "0023",
            "PurchaseOrder": "1990091",
            "InvoiceNumber": "12314154",
            "BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
            "Disposition": "urn:epcglobal:cbv:disp:active",
            "EventTime": "2024-03-30T14: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"
                }
            ],
            "Container": {
                "Id": "123456",
                "Type": "LogisticId"
            }
        }
    ]
}
    data = {
    "Events": [
        {
            "$type": "aggregation",
            "Location": {
                "Id": "location_id",
            },
            "ProductInstances": [
                {
                    "Quantity": 190.75,
                    "LotSerial": "1990091",
                    "Product": {
                        "Id": "product_id",
                    },
                    "TraceabilityLotCode": "1234567989",
                    "TlcSource": {
                        "Type": "Identifier",
                        "Reference": "Eg: BAP",
                        "Identifier": "BAP01283"
                    }
                },
                {
                    "Quantity": 190.75,
                    "LotSerial": "123",
                    "Product": {
                        "Id": "raw_goods_000",
                        "Details": {
                            "Name": "RawGoods",
                            "SimpleUnitOfMeasurement": "Lbs",
                            "SharingPolicy": "Restricted",
                            "ProductIdentifierType": "Lot"
                        }
                    },
                    "TraceabilityLotCode": "9876543210",
                    "TlcSource": {
                        "Type": "Identifier",
                        "Reference": "Eg: ASC",
                        "Identifier": "ASC00192"
                    }
                }
            ],
            "Id": "0023",
            "PurchaseOrder": "1990091",
            "InvoiceNumber": "12314154",
            "BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
            "Disposition": "urn:epcglobal:cbv:disp:active",
            "EventTime": "2024-03-30T14: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"
                }
            ],
            "Container": {
                "Id": "123456",
                "Type": "LogisticId"
            }
        }
    ]
}