AggregationEvent
Purpose: Bundles (aggregates) smaller units into a larger unit, or breaks down (disaggregates) larger units into smaller units.
Example: Pre-shipment, where boxes are loaded onto a pallet for delivery.
Key elements:
parentID: Must be an SSCC (Serial Shipping Container Code). Required for ADD and DELETE, optional for OBSERVE.childEPCsorchildQuantityList: Must list class-level Logistic Unit Global Trade Item Number (LGTIN) or instance-level Serialized Global Trade Item Number (SGTIN) items. At least one of these elements is required for ADD and OBSERVE. For DELETE, omitting both children means "disaggregate all children" from the parent.action:- ADD — children are aggregated to the parent (packing).
- OBSERVE — an existing aggregation is observed (a pallet passes a reader intact, for example).
- DELETE — children are removed from the parent (unpacking). To unpack everything from a parent, send the
DELETEaction with theparentIDand nochildEPCsorchildQuantityList.
- Hierarchies can be nested: a case aggregated to a pallet; a pallet aggregated to a container — each level is its own AggregationEvent.
JSON payload fields
The following table describes EPCIS 2.0 JSON document payload fields applicable to AggregationEvents.
| Name | Type | Description | Required or optional | Example |
|---|---|---|---|---|
| type | String | The event type discriminator AggregationEvent. | Required | AggregationEvent |
| eventTime | DateTime (ISO 8601) | The date and time at which the event occurred. | Required | 2026-06-12T08:30:00.000Z |
| eventTimeZoneOffset | String | The local time zone offset where the event occurred, format ±HH:MM. | Required | -06:00 |
| eventID | URI | A globally unique identifier for the event. Strongly recommended, and required if the event may later be referenced by an errorDeclaration.Typically an ni-hash URI or UUID URN. | Optional (strongly recommended) | ni:///sha-256;df7bb3c352fef7c93c582...?ver=CBV2.0 or urn:uuid:7e6e36d2-… |
| parentID | URI | Identifier of the parent object (usually SSCC or GRAI). | Required for ADD and DELETE, optional for OBSERVE | urn:epc:id:sscc:4012345.0111222333 |
| childEPCs | Array of URIs | Instance-level children being aggregated or disaggregated. | Conditionally required: must include this element if childQuantityList is absent. | ["urn:epc:id:sgtin:4012345.011122.25"] |
| childQuantityList | Array of QuantityElement | Class-level children. | Conditionally required: must include this element if childEPCs is absent. | [{"epcClass": "urn:epc:class:lgtin:4012345.012345.LOTA", "quantity": 50}] |
| action | Enum | ADD (pack), OBSERVE, DELETE (unpack). | Required | ADD |
| certificationInfo | URI or Array of URIs | Reference to certification information relevant to the event. | Optional | https://accreditation.example/cert/123 |
| bizStep | URI or CBV string | The business step taking place (CBV vocabulary or user vocabulary). In JSON, CBV values may be expressed as bare strings, such as shipping. | Optional | packing |
| disposition | URI or CBV string | The business condition of the objects after the event. | Optional | in_progress |
| readPoint | Object | The specific location at which the event was observed, such as a dock door. | Optional | { "id": "urn:epc:id:sgln:4012345.00011.987" } |
| bizLocation | Object | The location where the objects are assumed to be after the event. | Optional | { "id": "urn:epc:id:sgln:4012345.00011.0" } |
| bizTransactionList | Array of bizTransaction objects | Business transactions associated with the event. Each entry has type (such as po, inv, desadv) and bizTransaction (the transaction identifier). | Optional (Required in TransactionEvent) | [{ "type": "po", "bizTransaction": "urn:epcglobal:cbv:bt:0614141073467:PO1234" }] |
| sourceList | Array of source objects | Identifies the originating party or location of a transfer. Each entry has type (such as owning_party, possessing_party, location) and a source URI. | Optional | [{ "type": "owning_party", "source": "urn:epc:id:pgln:4012345.00001" }] |
| destinationList | Array of destination objects | Identifies the receiving party or location of a transfer. Each entry has type (such as owning_party, possessing_party, location) and a destination URI. | Optional | [{ "type": "owning_party", "destination": "urn:epc:id:pgln:0614141.00001" }] |
| sensorElementList | Array of SensorElement | Sensor metadata and readings captured with the event (temperature, humidity, GPS, and so on). | Optional | Refer to the ObjectEvent page. |
| errorDeclaration | Object | Declares that a previously captured event (with the same eventID) was erroneous. | Optional | Refer to the Error declaration page. |
JSON payload examples
The following sections provide two EPCIS 2.0 aggregation event JSON documents.
Annotated payload
This example provides an annotated JSON payload. Remove the comments in this JSON file before sending data to the blockchain.
{ // Event type discriminator "type": "AggregationEvent", // Unique event identifier "eventID": "urn:uuid:9f0e4c1a-43e2-4b8e-8f0e-2b7d9f33a001", // When the cases were packed onto the pallet "eventTime": "2026-06-12T11:00:00.000Z", "eventTimeZoneOffset": "+01:00", // The parent logistic unit: the pallet's SSCC "parentID": "urn:epc:id:sscc:4012345.0111222333", // Instance-level children: serialized cases placed on the pallet "childEPCs": [ "urn:epc:id:sgtin:4012345.011122.25", // case #25 "urn:epc:id:sgtin:4012345.011122.26", // case #26 "urn:epc:id:sgtin:4012345.011122.27" // case #27 ], // Class-level children: 50 kg of lot-managed bulk product also on the pallet "childQuantityList": [ { // Lot-level class identifier (LGTIN) "epcClass": "urn:epc:class:lgtin:4012345.012345.LOT2026A", // Amount of the class-level child "quantity": 50, // Unit of measure (KGM = kilograms) "uom": "KGM" } ], // ADD: children are being aggregated TO the parent (packing) "action": "ADD", // CBV business step: packing "bizStep": "packing", // Disposition after packing: container is closed and ready "disposition": "container_closed", // Packing station where the aggregation was performed "readPoint": { "id": "urn:epc:id:sgln:4012345.00005.pack-2" }, // Warehouse where the pallet now resides "bizLocation": { "id": "urn:epc:id:sgln:4012345.00006.0" } }Ready to use
The following JSON file is ready to use. Define your own values for each tag, then send the data to the blockchain.
{ "type": "AggregationEvent", "eventTime": "2025-08-01T09:01:00.000-03:00", "recordTime": "2025-08-20T17:47:09.000-03:00", "eventTimeZoneOffset": "+07:30", "eventID": "urn:uuid:00000000-0000-0000-0000-000000000003", "parentID": "urn:gdst:example.com:lpn:obj:blueoceanprocessors.CONT-EXAMPLE-001", "childEPCs": [], "action": "ADD", "bizStep": "assembling", "disposition": "in_progress", "bizLocation": { "id": "urn:gdst:example.com:location:loc:blueoceanprocessors.blueoceanprocessors" }, "bizTransactionList": [{ "type": "po", "bizTransaction": "PO-EXAMPLE-0002" }], "childQuantityList": [ { "epcClass": "urn:gdst:example.com:product:lot:class:acmeseafood.exshrimp532ozvb31-40rawpndtloffstpp.LOT-2025-A002", "quantity": 1878.0, "uom": "LBR" }, { "epcClass": "urn:gdst:example.com:product:lot:class:acmeseafood.exshrimp532ozvb31-40rawpndtloffstpp.LOT-2025-A001", "quantity": 1622.0, "uom": "LBR" } ], "ilmd": { "gdst:broodstockSource": "Farmed", "gdst:aquacultureMethod": "semi-intensive", "cbvmda:certificationList": { "certification": [ { "gdst:certificationType": "urn:gdst:certType:harvestCoC", "certificationAgency": "Global Seafood Alliance", "certificationStandard": "BAP (Processor)", "certificationValue": "4", "certificationIdentification": "CERT-PROC-001" }, { "gdst:certificationType": "urn:gdst:certType:harvestCoC", "certificationAgency": "Global Seafood Alliance", "certificationStandard": "BAP (Hatchery)", "certificationValue": "4", "certificationIdentification": "CERT-HATCH-001" }, { "gdst:certificationType": "urn:gdst:certType:harvestCoC", "certificationAgency": "Global Seafood Alliance", "certificationStandard": "BAP (Farm)", "certificationValue": "4", "certificationIdentification": "CERT-FARM-002" }, { "gdst:certificationType": "urn:gdst:certType:harvestCoC", "certificationAgency": "Global Seafood Alliance", "certificationStandard": "BAP (Feed Mill)", "certificationValue": "4", "certificationIdentification": "CERT-FEED-001" } ] } }, "cbvmda:informationProvider": "urn:gdst:example.com:party:blueoceanprocessors.0" }Updated about 3 hours ago
Did this page help you?