Create an EventCreate an Aggregation event

Create an Aggregation Event

Create an Aggregation 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": "aggregation",
      "Location": {
        "Id": "warehouse_001",
        "Details": {
          "TradePartner": {
            "Id": "my_company",
            "Name": "My Company",
            "ConnectionType": "SELF",
            "Duns": "987654321"
          },
          "Name": "Main Warehouse",
          "Gln": "9506000140446",
          "Extension": "WarehouseExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Warehouse Contact",
            "Phone": "+1234567891",
            "Email": "warehouse@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "456 Warehouse Road",
            "AddressLine2": "Building 2",
            "PostalCode": "8002",
            "GeoCoordinates": {
              "Latitude": -33.925,
              "Longitude": 18.425
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001",
          "Product": {
            "Id": "product_001",
            "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"
                }
              ]
            }
          }
        },
        {
          "Quantity": 100,
          "LotSerial": "lot_002",
          "Product": {
            "Id": "product_002",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Sample Product 2",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "Gtin": "12345678912343",
              "Plu": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Container": {
        "Id": "container_001",
        "Type": "LogisticId"
      },
      "Id": "aggregation_001",
      "PurchaseOrder": "PO-12345",
      "InvoiceNumber": "INV-12345",
      "EventTime": "2024-03-30T14: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": "aggregation_001",
      "type": "Aggregation",
      "status": "Created",
      "eventDate": "2024-03-30T14: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": [
        {
          "id": "container_001",
          "status": "Created"
        }
      ],
      "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


An Aggregation event represents multiple individual product lots being physically grouped together into a logistical unit, such as a pallet or shipping container.


The individual products remain identifiable within the aggregation and can later be separated again through a Disaggregation event.


For example:


    

  • 50 cartons of strawberries are loaded onto a pallet.
    • 

  • 100 cases of bottled olive oil are loaded into a shipping container.
    • 



The purpose of this endpoint is to create an Aggregation event in Wholechain.


Multiple product lots being grouped into a pallet or shipping container
Multiple product lots being grouped into a pallet or shipping container




Creating an Aggregation Event


To create an Aggregation event, submit an event payload containing:


    

  • The event information
    • 

  • The Location where the aggregation takes place
    • 

  • The Product Instances being aggregated
    • 

  • The Container or logistical unit into which the products are being aggregated
    • 



The Products and Location referenced in the Aggregation event must 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 Aggregation 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 Aggregation event must identify the Location where the products are being aggregated.


Column NameData TypeDescriptionRequired
Location.IdSTRINGUnique identifier for the Location where the aggregation takes place.Yes


The Location.Id must reference an existing Location in your Wholechain master data.


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





Product Instance Object


The ProductInstances array identifies the individual lots being grouped into the aggregation.


At least one Product Instance must be included.


Column NameData TypeDescriptionRequired
QuantityDECIMALQuantity of the Product Instance being aggregated.Yes
LotSerialSTRINGLot or serial number of the Product Instance.Yes
ProductOBJECTProduct associated with the Product Instance.Yes
Product.IdSTRINGUnique identifier for the Product.Yes


The Product.Id must reference an existing Product in your Wholechain master data.


"ProductInstances": [
  {
    "Quantity": 190.75,
    "LotSerial": "1990091",
    "Product": {
      "Id": "1234"
    }
  }
]



Duplicate Lot Numbers


Duplicate lot numbers should not be included as separate Product Instances within the same Aggregation event.


If the same Product and lot needs to be included more than once, combine the quantities and send the total quantity as one Product Instance.


For example, instead of:


"ProductInstances": [
  {
    "Quantity": 100,
    "LotSerial": "LOT-001",
    "Product": {
      "Id": "product_123"
    }
  },
  {
    "Quantity": 50,
    "LotSerial": "LOT-001",
    "Product": {
      "Id": "product_123"
    }
  }
]



Send:


"ProductInstances": [
  {
    "Quantity": 150,
    "LotSerial": "LOT-001",
    "Product": {
      "Id": "product_123"
    }
  }
]





Container Object


The Container object identifies the logistical unit into which the Product Instances are being aggregated.


Column NameData TypeDescriptionRequired
Container.IdSTRINGUnique identifier for the Container or logistical unit.Yes
Container.TypeSTRINGType of Container identifier. Supported values are LogisticId or SSCC.Yes


Example:


"Container": {
  "Id": "123456",
  "Type": "LogisticId"
}



The Container becomes the logistical grouping for the Product Instances included in the Aggregation event.


The individual Products and lots remain associated with the aggregation and can later be separated through a Disaggregation event.




Example Aggregation Event Payload


The example below shows an Aggregation event containing multiple Product Instances grouped into one Container.


{
  "Events": [
    {
      "$type": "aggregation",
      "Location": {
        "Id": "4567"
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "1990091",
          "Product": {
            "Id": "product_123"
          }
        },
        {
          "Quantity": 100,
          "LotSerial": "LOT-002",
          "Product": {
            "Id": "product_456"
          }
        }
      ],
      "Container": {
        "Id": "123456",
        "Type": "LogisticId"
      },
      "Id": "0023",
      "PurchaseOrder": "1990091",
      "InvoiceNumber": "12314154",
      "EventTime": "2024-03-30T14:00:00",
      "EventTimeZone": "-05:00"
    }
  ]
}



Refer to the Required column in the tables above to determine which fields must be supplied.




How Wholechain Processes the Payload


When an Aggregation event is submitted, Wholechain uses the information in the payload to:


    

  1. Identify the Location where the aggregation takes place.
    2. 

  2. Identify each Product and lot included in ProductInstances.
    3. 

  3. Record the quantity of each Product Instance being aggregated.
    4. 

  4. Identify the Container or logistical unit.
    5. 

  5. Group the Product Instances into that Container.
    6. 

  6. Create the Aggregation event.
    7. 



The underlying Product Instances retain their individual identities within the aggregation.


The aggregation can later be reversed using a Disaggregation event.




Custom Properties and Certifications


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


These fields are not included in the standard Aggregation event example above.


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



Was this page helpful?