EPC State

EPC state collection maintains the current state for individual Electronic Product Codes (EPCs), providing a real-time view of object status, location, and key lifecycle milestones.

The epc_state Object

EPC state collection provides a consolidated view of each EPC's current status, tracking location history, disposition changes, and important lifecycle events such as commissioning, selling, and recall status.

Field Name	Type	Description
epc_join_key	string	Primary key. EPC identifier in join key format (e.g., "/01/67238900000001/21/xyz").
record_time	datetime	Timestamp when the state record was last updated.
epc_type	string	Type of EPC identifier (e.g., "gtin", "sscc", "grai", "giai").
product_join_key	object	Product identifier associated with this 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
lgtin_join_key	object	Lot-level GTIN identifier (M2O reference to lot).
item_expiration_date	date	Expiration date of the item.
sell_by_date	date	Sell-by date of the item.
best_before_date	date	Best-before date of the item.
last_seen_biz_location_join_key	object	Business location where the EPC was last observed (M2O reference to location).
last_seen_time	datetime	Timestamp when the EPC was last observed.
expected_biz_location_join_key	object	Expected current business location of the EPC (M2O reference to location).
current_disposition	string	Current disposition status (e.g., "active", "in_transit", "retail_sold", "recalled").
last_biz_step	string	Last business step performed on this EPC (e.g., "commissioning", "receiving", "shipping").
commission_location_join_key	object	Location where the EPC was commissioned (M2O reference to location).
commission_time	datetime	Timestamp when the EPC was commissioned.
commission_event_id	string	Event ID of the commissioning event.
selling_location_join_key	object	Location where the EPC was sold (M2O reference to location).
selling_time	datetime	Timestamp when the EPC was sold.
selling_event_id	string	Event ID of the selling event.
recall_time	datetime	Timestamp when the EPC was recalled (if applicable).
recall_event_id	string	Event ID of the recall event (if applicable).
parent_join_key	object	Current parent object identifier (M2O reference to epc_state).
top_parent_join_key	string	Top-level parent object identifier in the hierarchy.
children	array of objects	Child EPC objects aggregated under this EPC (O2M relation).

---

List EPC States

List existing EPC states.

REST

GET /items/epc_state

GraphQL

query {
  epc_state {
    epc_join_key
    epc_type
    product_join_key
    current_disposition
    last_biz_step
    last_seen_time
    last_seen_biz_location_join_key
    expected_biz_location_join_key
    lot_number
    serial
    item_expiration_date
    sell_by_date
    best_before_date
    record_time
  }
}

Query Parameters

Supports all global query parameters.

Returns

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

---

Retrieve an EPC State

Retrieve a specific EPC state by EPC join key. Please note that EPC join keys often have slashes in them (e.g. /01/09312345552016/21/WWC501, so be sure to URL encode identifiers before using this API in REST mode, e.g. %2F01%2F09312345552016%2F21%2FWWC501)

REST

GET /items/epc_state/:epc_join_key

GraphQL

query {
  epc_state_by_id(id: "epc_join_key") {
    epc_join_key
    record_time
    epc_type
    product_join_key
    lot_number
    serial
    item_expiration_date
    sell_by_date
    best_before_date
    last_seen_biz_location_join_key
    last_seen_time
    expected_biz_location_join_key
    current_disposition
    last_biz_step
    commission_location_join_key
    commission_time
    commission_event_id
    selling_location_join_key
    selling_time
    selling_event_id
    recall_time
    recall_event_id
    parent_join_key
    top_parent_join_key
  }
}

Returns

Returns an EPC state object if a valid EPC join key was provided.

---

Sample Data

Example EPC State response for an SGTIN

{
    "data": {
        "epc_join_key": "/01/09312345552016/21/WWC501",
        "record_time": "2025-06-19T05:48:07.471Z",
        "epc_type": "sgtin",
        "product_join_key": "/01/09312345552016",
        "lot_number": null,
        "serial": "WWC501",
        "sscc": null,
        "grai": null,
        "giai": null,
        "lgtin_join_key": null,
        "item_expiration_date": null,
        "sell_by_date": null,
        "best_before_date": null,
        "last_seen_biz_location_join_key": "/414/9312345000029",
        "last_seen_time": "2024-10-08T13:13:00.000Z",
        "expected_biz_location_join_key": "/414/9312345000029",
        "current_disposition": "sellable_accessible",
        "last_biz_step": "receiving",
        "commission_location_join_key": null,
        "commission_time": null,
        "commission_event_id": null,
        "selling_location_join_key": null,
        "selling_time": null,
        "selling_event_id": null,
        "recall_time": null,
        "recall_event_id": null,
        "parent_join_key": "/00/493123451000000017",
        "top_parent_join_key": "/00/493123451000000017",
        "children": [
            "/01/09312345551927/21/WWB101",
            "/01/09312345551927/21/WWB102",
            "/01/09312345551927/21/WWB103",
            "/01/09312345551927/21/WWB104",
            "/01/09312345551927/21/WWB105",
            "/01/09312345551927/21/WWB106"
        ]
    }
}