EPC Events

EPC events collection stores comprehensive supply chain event records following EPCIS (Electronic Product Code Information Services) standards, capturing detailed traceability information for supply chain objects as they undergo business processes in various locations.

The epc_events Object

EPC events collection contains detailed supply chain event data including business steps, dispositions, locations, timing, and relationships between objects, supporting comprehensive traceability and compliance requirements. Each row in this table is associated to a single EPC identifier, making searches and aggregations on the basis of EPC objects easy and fast. If the original event references multiple EPCs, there will be multiple rows in this table tied to that single Event ID.

Field Name	Type	Description
id	string	Primary key. Unique identifier for the EPC event record (UUID format).
event_id	string	Unique EPCIS event identifier, typically a hash-based identifier following EPCIS standards.
event_type	string	Type of EPCIS event (e.g., "ObjectEvent", "AggregationEvent", "TransformationEvent", "AssociationEvent").
action	string	Action performed in the event (e.g., "ADD", "OBSERVE", "DELETE").
biz_step	string	Business step being performed (e.g., "commissioning", "receiving", "shipping", "selling").
disposition	string	Current disposition of the object (e.g., "active", "in_transit", "recalled", "retail_sold").
record_time	datetime	Timestamp when the event was recorded in the database.
event_time	datetime	Timestamp when the event actually occurred.
event_time_zone_offset	string	The local timezone where the event actually occured (e.g., "+00:00", "+01:00").
biz_location_id_raw	string	Raw business location identifier as received from the source event.
biz_location_join_key	object	Business location where the event occurred (M2O reference to location).
read_point_id_raw	string	Raw read point identifier as received from the source event.
read_point_join_key	object	Specific read point where the event was captured (M2O reference to location).
epc_id_raw	string	Raw EPC identifier as received from the source event.
epc_type	string	Type of EPC identifier (e.g., GS1 keys like "gtin", "sscc", "grai", "giai" or non-GS1 keys like "obj" and "class").
epc_rel_type	string	Relationship type of the EPC in the event (e.g., "epcList", "childEPCs", "inputEPCList").
epc_join_key	string	Unique EPC identifier of the object involved in the event (reference key format).
quantity	number	Quantity of objects involved in the event (for class level identifiers such as batch/lot).
uom	string	Unit of measurement for quantity values.
product_join_key	object	Product identifier associated with the EPC (M2O reference to product).
lot_number	string	Lot or batch number of the product.
serial	string	Serial number of the individual object.
sscc	string	Full SSCC identifier of the object, if it is a logistics unit.
grai	string	GRAI identifier of the object if it is a returnable asset
giai	string	GIAI identifier of the object if it is a independent asset
parent_id_raw	string	Raw parent identifier as received from the source event.
parent_join_key	string	Parent object identifier for aggregation/association events.
ilmd	object	Instance-Level Master Data in JSON format containing additional object attributes.
ilmd_lot_number	string	The CBV lotNumber attribute in the ILMD block, if present
ilmd_item_expiration_date	date	The CBV itemExpirationDate attribute in the ILMD block, if present
ilmd_best_before_date	date	The CBV bestBeforeDate attribute in the ILMD block, if present
ilmd_sell_by_date	date	The CBV sellByDate attribute in the ILMD block, if present
lgtin_join_key	object	Lot-level GTIN identifier (M2O reference to lot).
persistent_disposition_set	object	Persistent disposition values added by this event, in JSON format.
persistent_disposition_unset	object	Persistent disposition values removed by this event, in JSON format.
biz_transaction_list	object	Business transaction references in JSON format (e.g., purchase orders, invoices).
biz_transaction_po_id	string	The ID of the purchase order specified in the Biz Transaction List, if present.
biz_transaction_desadv_id	string	The ID of the Despatch Advice / Advance Ship Notice specified in the Biz Transaction List, if present.
source_location_id_raw	string	Raw source location identifier as received from the source event.
source_location_join_key	object	Source location for shipping/receiving events (M2O reference to location).
source_owning_party_id_raw	string	Raw source owning party identifier as received from the source event.
source_owning_party_join_key	string	Normalized source owning party identifier (reference key format).
source_possessing_party_id_raw	string	Raw source possessing party identifier as received from the source event.
source_possessing_party_join_key	string	Normalized source possessing party identifier (reference key format).
destination_location_id_raw	string	Raw destination location identifier as received from the source event.
destination_location_join_key	object	Destination location for shipping/receiving events (M2O reference to location).
destination_owning_party_id_raw	string	Raw destination owning party identifier as received from the source event.
destination_owning_party_join_key	string	Normalized destination owning party identifier (reference key format).
destination_possessing_party_id_raw	string	Raw destination possessing party identifier as received from the source event.
destination_possessing_party_join_key	string	Normalized destination possessing party identifier (reference key format).
transformation_id	string	A key that ties together all rows in a given Transformation event
inferred	boolean	Flag indicating if this event was inferred (derived) rather than directly captured.
parent_event_id	string	Event ID of the parent event, for events that are corrections or extensions of another event.
has_error	boolean	Flag indicating if the event has been declared as erroneous/invalid.
error_reason	string	The reason the event has been declared as erroneous/invalid.
error_declaration_time	datetime	The timestamp when this event was declared erroneous
corrective_event_ids	object	JSON array of event IDs that correct or supersede this event.

---

List EPC Events

List existing EPC events.

REST

GET /items/epc_events

GraphQL

query {
  epc_events {
    id
    event_id
    event_type
    action
    biz_step
    disposition
    event_time
    event_time_zone_offset
    epc_join_key
    epc_type
    product_join_key
    quantity
    uom
    lot_number
    serial
    biz_location_join_key
    read_point_join_key
    record_time
  }
}

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit EPC events objects. If no items are available, data will be an empty array.

---

Retrieve an EPC Event

Retrieve a specific EPC event by ID.

REST

GET /items/epc_events/:id

GraphQL

query {
  epc_events_by_id(id: "epc_event_id") {
    id
    event_id
    event_type
    action
    biz_step
    disposition
    record_time
    event_time
    event_time_zone_offset
    biz_location_join_key
    read_point_join_key
    epc_join_key
    epc_type
    product_join_key
    quantity
    uom
    lot_number
    serial
    parent_join_key
    ilmd
    biz_transaction_list
    source_location_join_key
    destination_location_join_key
    has_error
    error_reason
  }
}

Returns

Returns an EPC events object if a valid primary key was provided.

---

Sample Data

Example EPC Event lookup response

{
    "data": {
        "id": "f37639f3-4cd0-11f0-bf42-1e14173c8de9",
        "event_id": "ni:///sha-256;2d1ad8f3d0ca93d18190a67448237e80b8cb20e2d0ae108591de6731b875ddb9?ver=CBV2.0",
        "event_type": "ObjectEvent",
        "action": "ADD",
        "biz_step": "commissioning",
        "disposition": "active",
        "record_time": "2025-06-19T05:47:56.999Z",
        "event_time": "2024-03-01T14:01:00.000Z",
        "event_time_zone_offset": "+01:00",
        "transformation_id": null,
        "biz_location_id_raw": "https://mybrand.tvai.me/414/7777666100056/254/UA",
        "biz_location_join_key": "/414/7777666100056/254/UA",
        "read_point_id_raw": "https://mybrand.tvai.me/414/7777666100056/254/UA",
        "read_point_join_key": "/414/7777666100056/254/UA",
        "epc_id_raw": "https://mybrand.tvai.me/01/77777666100062/21/CH1001",
        "epc_type": "sgtin",
        "epc_rel_type": "epcList",
        "epc_join_key": "/01/77777666100062/21/CH1001",
        "quantity": null,
        "uom": null,
        "product_join_key": "/01/77777666100062",
        "lot_number": null,
        "serial": "CH1001",
        "sscc": null,
        "grai": null,
        "giai": null,
        "parent_id_raw": null,
        "parent_join_key": null,
        "ilmd": {
            "cbvmda:itemExpirationDate": "2024-12-01",
            "cbvmda:lotNumber": "CC501"
        },
        "ilmd_lot_number": "CC501",
        "ilmd_item_expiration_date": "2024-12-01",
        "ilmd_best_before_date": null,
        "ilmd_sell_by_date": null,
        "lgtin_join_key": "/01/77777666100062/10/CC501",
        "persistent_disposition_set": null,
        "persistent_disposition_unset": null,
        "biz_transaction_list": null,
        "biz_transaction_po_id": null,
        "biz_transaction_desadv_id": null,
        "source_location_id_raw": null,
        "source_location_join_key": null,
        "source_owning_party_id_raw": null,
        "source_owning_party_join_key": null,
        "source_possessing_party_id_raw": null,
        "source_possessing_party_join_key": null,
        "destination_location_id_raw": null,
        "destination_location_join_key": null,
        "destination_owning_party_id_raw": null,
        "destination_owning_party_join_key": null,
        "destination_possessing_party_id_raw": null,
        "destination_possessing_party_join_key": null,
        "has_error": false,
        "error_reason": null,
        "error_declaration_time": null,
        "corrective_event_ids": null
    }
}