> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# EPCIS 2.0 Events

> Capture and query supply chain visibility events per ISO/IEC 19987:2024.

Closient implements [EPCIS 2.0](https://www.gs1.org/standards/epcis) (Electronic Product Code Information Services) per ISO/IEC 19987:2024 for capturing and querying supply chain visibility events. Events answer the four dimensions of supply chain visibility: **What**, **When**, **Where**, and **Why**.

## Event Types

| Event Type              | Use Case                                             | Action Required         |
| ----------------------- | ---------------------------------------------------- | ----------------------- |
| **ObjectEvent**         | Observing, inspecting, or acting on specific objects | ADD, OBSERVE, or DELETE |
| **AggregationEvent**    | Packing/unpacking objects into containers            | ADD, OBSERVE, or DELETE |
| **TransactionEvent**    | Associating objects with business transactions       | ADD, OBSERVE, or DELETE |
| **TransformationEvent** | Input objects transformed into output objects        | No action field         |
| **AssociationEvent**    | Associating objects with other objects               | ADD, OBSERVE, or DELETE |

## Event Structure

Every event has four dimensions:

### What (Identifiers)

* **epcList** — list of individual EPC/GTIN URIs involved
* **quantityList** — class-level quantities (GTIN without serial, plus quantity and UOM)
* **parentID** — container identifier for aggregation events
* **inputEPCList / outputEPCList** — for transformation events

### When (Time)

* **eventTime** — when the event occurred (ISO 8601)
* **eventTimeZoneOffset** — timezone offset (e.g., `+05:30`)
* **recordTime** — when the system captured the event (set automatically)

### Where (Location)

* **readPoint** — GS1 Digital Link URI of the scan location
* **bizLocation** — GS1 Digital Link URI of the business location

### Why (Business Context)

* **bizStep** — business step from CBV 2.0 vocabulary (40+ values)
* **disposition** — object state after the event (20+ values)

## Capturing Events

```bash theme={null}
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://www.closient.com/epcis/api/2.0/capture \
  -d '{
    "type": "ObjectEvent",
    "eventTime": "2026-04-01T12:00:00Z",
    "eventTimeZoneOffset": "+00:00",
    "action": "OBSERVE",
    "epcList": ["urn:epc:id:sgtin:0012345.078905.1"],
    "bizStep": "urn:epcglobal:cbv:bizstep:inspecting",
    "disposition": "urn:epcglobal:cbv:disp:in_progress",
    "readPoint": {"id": "urn:epc:id:sgln:0012345.00001.0"},
    "bizLocation": {"id": "urn:epc:id:sgln:0012345.00001.0"}
  }'
```

Events are deduplicated by SHA-256 hash. Submitting the same event twice returns the existing event without creating a duplicate.

## Business Step Vocabulary (CBV 2.0)

Common business steps:

| bizStep           | Description                      |
| ----------------- | -------------------------------- |
| `accepting`       | Accepting goods into custody     |
| `arriving`        | Goods arriving at a location     |
| `commissioning`   | Assigning identity to an object  |
| `decommissioning` | Removing identity from an object |
| `departing`       | Goods leaving a location         |
| `inspecting`      | Quality inspection               |
| `packing`         | Packing items into containers    |
| `receiving`       | Receiving goods from a supplier  |
| `shipping`        | Shipping goods to a destination  |
| `storing`         | Placing into storage             |
| `unpacking`       | Removing items from containers   |

## Disposition Vocabulary

Common dispositions:

| disposition  | Description                     |
| ------------ | ------------------------------- |
| `active`     | Object is active and in use     |
| `available`  | Available for use or sale       |
| `damaged`    | Object is damaged               |
| `expired`    | Past expiry date                |
| `in_transit` | Currently being transported     |
| `recalled`   | Subject to recall               |
| `reserved`   | Reserved for a specific purpose |

## Persistent Dispositions

EPCIS 2.0 introduces persistent dispositions — dispositions that remain in effect across events:

* **persistent\_disposition\_set** — dispositions to add to the object's persistent state
* **persistent\_disposition\_unset** — dispositions to remove

This enables tracking long-lived states like certifications or regulatory holds that span multiple events.

## Instance/Lot Master Data (ILMD)

The `ilmd` field carries master data that is defined at the instance or lot level at the time of creation:

```json theme={null}
{
  "ilmd": {
    "bestBeforeDate": "2027-01-15",
    "countryOfOrigin": "US",
    "lotNumber": "LOT2026Q1"
  }
}
```

## Querying Events

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://www.closient.com/epcis/api/2.0/events?GE_eventTime=2026-01-01T00:00:00Z&eventType=ObjectEvent"
```

See the [EPCIS API reference](/api-reference/epcis) for the full query interface including filtering by EPC, business step, disposition, location, and time range.