Enterprise Feature
This feature is available only to customers with an enterprise Platform subscription. Contact us to discuss enabling it on your account.

EPCIS is the GS1 standard for information formatting and exchange in supply chain contexts. Along with the Core Business Vocabulary standard, it contains objects and data types to describe a wide variety of business-related activities, states, and business steps for goods in a supply chain.

The Product Cloud EPCIS 2.0 API implements features of the GS1 EPCIS 2.0 standard. It allows developers to submit and retrieve EPCIS events as defined in version 2.0 of the standard.

The aim of the standard is to make communicating this information as straightforward and standardized as possible to encourage information sharing to benefit all supply chain parties, as well as end consumers who wish to know more transparent information about the production and origins of their purchases. EVRYTHNG & Digimarc were active participants in the working group, leading the REST API specification of the standard.

SDK : epcis2.js
epcis2.js, is our open-source SDK for building EPCIS clients. It eases the interactions with EPCIS repositories and APIs, like the one provided by the EVRYTHNG Product Cloud.

API Status Beta `/epcis/capture` `/epcis/events` `/epcis/events/:eventID`

EPCISDocument Data Model

An EPCISDocument contains one or several supply chain events and is defined in the GS1 EPCIS 2.0 standard. The full schema of an EPCISDocument or EPCISQueryDocument and many examples can be found here.

Event Structure

All event types share many similar fields, each concerned with one of the what, where, why, when, and how dimensions describing aspects of the event itself.

Other fields exist that are specific to an event type, and are fully defined in the EPCIS 2.0 Standard document.

Note that unlike in previous versions of the standard, EPCIS 2.0 now supports EPC identifiers both in the EPC URN format (for example, `urn:epc:id:sgln:0012345.11111.400`) and the GS1 Digital Link format (for example, `https://dlnkd.tn.gg/01/9780345418913/21/123456`)

Event Types

The standard includes five main event types, detailed here with examples. Extensions can also be added to many fields, using colon-separated namespaces for the key names.

The event types defined are:

ObjectEvent
AggregationEvent
TransformationEvent
AssociationEvent
TransactionEvent

A custom event type called ExtendedEvent is available. This type of event can have as many fields as needed. These custom fields must be declared as extensions, for example, "custom:key":"value".

ObjectEvent

An event that happened to a physical item, such as shipping or receiving.

AggregationEvent

An event that involved the aggregation or disaggregation of multiple items, such as packing into a case or pallet.

TransformationEvent

An event where input items or quantities of a class of item are irreversibly transformed into a new output item or class of item.

AssociationEvent

An event linking identifiers to items or places.

TransactionEvent

An event linking objects to one or more business-related events, such as linking to an invoice.

Core Business Vocabulary Types

The Core Business Vocabulary (CBV) defines values for some of these common fields to provide a unified data format for types of events, dispositions, and business steps shared by many types of industries.

Business Steps

Format: $BIZSTEP

All the business steps are defined in the CBV Standard and describe stages that can objects or identifiers can be in during their course through the supply chain.

accepting - Denotes a specific activity within a business process where an object changes possession or ownership or both.
arriving - Denotes a specific activity within a business process where an object arrives at a location.
assembling - Denotes an activity within a business process whereby one or more objects are combined to create a new finished product.
collecting - Denotes a specific activity within a business process where an object is picked up and collected for future disposal, recycling, or re-use.
commissioning - Instance-level identifier has been created and encoded in a tag, or a class-level identifier is associated with instance-level identifiers for the first time.
consigning - Indicates the overall process of staging_outbound, loading, departing, and accepting. It can be used when more granular process step information is unknown or inaccessible.
creating_class_instance - Denotes a step in a business process where an instance or increased quantity of a class-level identifier is produced.
cycle_counting - Process of counting objects within a location to get an accurate inventory for business needs other than accounting purposes (for example, replenishment and allocation).
decommissioning - Instance-level identifier is disassociated from an object. The object can be recommissioned but with a new identifier.
departing - Denotes a specific activity within a business process where an object leaves a location on its way to a destination.
destroying - Process of terminating an object. For an instance-level identifier, the object won't be the subject of follow-up events.
disassembling - Denotes a specific activity within a business process where an object is broken down into separate, uniquely identified component parts.
dispensing - Denotes a specific activity within a business process where a product is made available in full or part to a consumer.
encoding - Process of writing an instance-level identifier (typically an EPC) to a barcode or RFID tag, where the identifier isn't yet associated with an object at this step. Encoding must only be used in a TransactionEvent.
entering_exiting - Denotes a specific activity at the Entrance/Exit door of a facility where customers are leaving with purchased product or entering with product to be returned.
holding - Denotes a specific activity within a business process where an object is separated for further review. inspecting Process of reviewing objects to address potential physical or documentation defects.
installing - Denotes a specific activity within a business process where an object is put into a composite object (not merely a container).
killing - Process of terminating an RFID tag previously associated with an object. The object and its instance-level identifier can continue to exist and be the subject of follow-up events (through a barcode, manual data entry, replacement tag, and so on).
loading - Denotes a specific activity within a business process where an object is loaded into a shipping conveyance.
packing - Items are packed into a larger container, such as aggregation.
picking - Loose items are picked to fill a supplier order.
receiving - Items are being received at a new location and are part of the receiver’s inventory.
removing - Denotes a specific activity within a business process where an object is taken out of a composite object. Opposite of installing.
repacking - Items are unpacked and repacked with a different packaging configuration, such as with another item type, or co-packing.
repairing - Denotes a specific activity within a business process where a malfunctioning product is repaired (typically by a post-sales service), without replacing it with a new one.
replacing - Denotes a specific activity within a business process where an object is substituted or exchanged for another object.
reserving - Process in which a set of instance-level identifiers, not yet commissioned, are provided for use by another party.
retail_selling - When an item is sold and ownership is transferred to the customer
sampling - Denotes a testing activity within a business process where one or more portions of an object are examined for quality testing, quality inspection, or customs clearance purposes
sensor_reporting - Denotes a specific activity within a business process where sensor data, pertaining to the physical properties and condition of an object or location, is returned.
shipping - Represents staging, loading, and departing when more granular steps aren't required or known.
staging_outbound - Denotes a specific activity within a business process in which an object moves from a facility to an area where it awaits transport.
stock_taking - Process of counting objects within a location following established rules or standards or both for accounting purposes.
stocking - Denotes a specific activity within a business process at a location to make an object available to the customer or for order fulfilment within a distribution center (DC).
storing - Denotes a specific activity within a business process where an object is moved into and out of storage within a location.
transporting - Process of moving an object from one location to another using a vehicle (for example, a ship, train, truck, or aircraft).
unloading - Denotes a specific activity within a business process where an object is unloaded from a shipping conveyance.
unpacking - Items are removed from a larger container and disaggregated into smaller units.
void_shipping - Denotes a process of declaring that one or more objects in a prior outbound process.

Dispositions

Format: $DISPOSITION

Defined in the CBV Standard, describes the different states an object or identifier can have at various points in the supply chain.

active - A new commissioned object has been introduced to the supply chain.
available - Object has been returned to service or to the supply chain
completeness_inferred - A downstream recipient infers that the contents of a shipment below the outer packing layer are complete, as indicated in EPCIS packing and shipping events provided by the upstream supplier.
completeness_verified - A downstream recipient verifies that the contents of a shipment below the outer packing layer are complete. This verification requires unpacking and scanning the barcodes or EPC/RFID tags of the contents.
conformant - Outcome of a successful, passed inspection in the inspecting or repairing step.
container_closed Object has been loaded onto a container, the doors have been closed, and the shipment has been sealed.
container_open A container’s doors have been opened or a seal of a shipment has been broken.
damaged - An object has been damaged or reduced in value.
destroyed - An object has been rendered unusable.
dispensed - A full quantity of product is distributed to a consumer.
disposed - Object has been returned for disposal.
encoded - An instance-level identifier has been encoded to a tag.
expired - An object is past its expiration date.
in_progress - Default state of an object in the supply chain.
in_transit - Object being shipped between two trading partners.
inactive - Decommissioned object that can be reintroduced to the supply chain.
mismatch_class - Class-level identifiers don't correspond to the identifiers that were expected.
mismatch_instance - Instance-level identifiers don't correspond to the identifiers
mismatch_quantity - Quantity doesn't correspond to the expected quantity.
needs_replacement - Component(s) or other asset(s) must be replaced to ensure fulfilment of functional requirements.
non_conformant - Outcome of an unsuccessful/failed inspection in an inspecting or repairing step. Opposite of available.
non_sellable_other - Object can't be sold to a customer.
partially_dispensed - A portion of a product is distributed to a customer, while additional product is retained for later distribution.
recalled - An item has been recalled.
reserved - Instance-level identifier has been allocated for a third party.
retail_sold - Product has been purchased by a customer.
returned - Object has been sent or brought back for various reasons. It might or might not be sellable.
sellable_accessible - An item can be sold in a store to a customer.
sellable_not_accessible - Product can be sold as is, but customers can't access product for purchase.
stolen - An object has been taken without permission or right.
unavailable - Object has been removed from service or from the supply chain (for example, pending repair).
unknown - An object’s condition isn't known.

Business Transaction Types

Format: $TYPE

Defined in the CBV Standard as the values for bizTransactionList in a given EPCIS event, concerning the “why” from a business transaction context.

bol - Bill of Lading. A document issued by a carrier to a shipper, listing and acknowledging receipt of goods for transport and specifying terms of delivery
cert - Certificate. A document confirming certain characteristics of an object (for example, product), person, or organization, typically issued by a third party.
desadv - Dispatch Advice. A document or message by means of which the seller or consignor informs the consignee about the dispatch of goods. Also called an “Advanced Shipment Notice,” but the value desadv is always used regardless of local nomenclature.
inv - Invoice. A document or message claiming payment for goods or services supplied under conditions agreed by the seller and buyer.
pedigree - Pedigree. A record that traces the ownership or custody and transactions of a product as it moves among various trading partners.
po - Purchase Order. A document/message that specifies details for goods and services ordered under conditions agreed by the seller and buyer.
poc - Purchase Order Confirmation. A document that provides confirmation from an external supplier to the request of a purchaser to deliver a specified quantity of material, or perform a specified service, at a specified price within a specified time. (Sometimes internally called a “Sales Order”.)
prodorder - Production Order. An organization-internal document or message issued by a producer that starts a manufacturing process of goods.
recadv - Receiving Advice. A document or message that provides the receiver of the shipment the capability to inform the shipper of actual goods received, compared to what was advised as being sent.
rma - Return Merchandise Authorization. A document issued by the seller that authorizes a buyer to return merchandise for credit determination.
testprd - Test Procedure. A document that provides a formal specification of a sequence of instructions to verify one or several criteria.
testres - Test Result. A document that includes the outcome of a given test procedure.
upevt - Upstream EPCIS Event. Event ID URI(s) of event(s) provided by an upstream supplier, such as packing and shipping events (for example, as the basis for the inferred completeness of inbound aggregations).

Source and Destination types

Format: $TYPE

The CBV Standard also contains definitions for source and destination types, such as owner or location for an object, which can be used for some EPCIS event types where the source or destination of the identifier or object must be included.

owning_party - The party who owns the object at the source or destination.
possessing_party - The party with physical possession of the object at the included location.
location - The source or destination denotes the physical location of the object after the event and must be consistent with the Read Point.

User Vocabulary

A User Vocabulary represents a set of Vocabulary Elements whose definition and meaning are under the control of a single organization or consortium.

Vocabulary Element Types

Format: urn:epcglobal:epcis:vtype:$VTYPE

The EPCIS 2.0 standard summarizes the vocabulary types:

ReadPointID
BusinessLocationID
BusinessStepID
DispositionID
BusinessTransaction
BusinessTransactionTypeID
EPCClass
SourceDestTypeID
SourceDestID
LocationID
PartyID
ErrorReasonID
SensorPropertyTypeID
MicroorganismID
ChemicalSubstanceID
ResourceID

Read a Single Event

To get a single EPCIS event, send a GET request to the /epcis/events endpoint with the event ID in the path.

const eventID = 'test:docs:1';

evrythng.api({
  url: `/epcis/events/${eventID}`,
  apiKey: operatorApiKey,
})
  .then(console.log);

Submit a Single Event (Sync)

To submit a new EPCIS event, send a POST request to the /epcis/events endpoint with the EPCISDocument in the body that includes the event ID. The EPCIS event is synchronously created and immediately available.

Events without an eventID specified have one assigned after processing is complete using the EPCIS Event ID Hash algorithm, which tries to produce the same eventID for the same event data. If an eventID is specified in the payload, the responsibility for duplicate events is assumed by the caller. An example generated eventID is shown below:

ni:///sha-256;24addc428d50127420f743c40e7da102bfa6c06a797a4b7cdf61ee8cb7058808?ver=CBV2.0

Capturing Multiple Events (Async)

You can submit a capture document containing multiple events. After the capture has been validated and accepted, the individual events contained within are submitted asynchronously.

To capture multiple EPCIS events, send a POST request to the /epcis/capture endpoint with the EPCISDocument in the body. Include the eventList in the epcisBody property of the payload, containing all the events that form part of the capture: