📘

Enterprise Feature

📘

Beta

EPCIS 2.0 currently being developed by the EPCIS and CBV 2.0 MSWG. The standard has not been ratified yet, hence consider everything you see here tentative and subject to change.

Our EPCIS API implements part of the GS1 EPCIS 2.0 REST API and allows developers to submit and retrieve EPCIS events as defined in version 2.0 of the standard.

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 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.

📘

Current version

The latest implemented version of the REST bindings is published here.

📘

SDK : epcis2.js

Here, you can find the open-source SDK epcis2.js for the EPCIS 2.0 standard. This will allow you a simpler implementation of EPCISDocuments and everything related to the standard

🚧

API Limits

Currently the following limits exist on this API:

  • For /epcis/capture the maximum payload size is 50MB.
  • For /epcis/events the maximum payload size is 6MB.

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


EPCISDocument Data Model

The EPCISDocument is defined as part of the GS1 EPCIS 2.0 standard. The full schema as well as many of different examples can be found in the GS1 GitHub repository. Some examples are also shown below as part of the API operations examples.

At a high level, EPCISDocument contains a common set of root-level fields that simply detail the format and time of the API operation. Depending on the operation type (single event or multiple events included) the epcisBody property varies slightly, using event or eventList as appropriate. Some complete examples are shown in the section below.

Event Structure

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

Event Field

Aspect

Description

type

What

The event type.

eventTime

When

The time the event occurred.

eventTimeZoneOffset

When

The timezone offset from UTC of the event time.

eventID

What

Globally unique ID of the event, used for deduplication and event retrieval. UUID recommended.

action

Why

The type of action involved, generally one of ADD, OBSERVE or DELETE

bizStep

Why

The business step involved, defined in the CBV.

disposition

What

The current disposition or state of the items involved, defined in the CBV.

readPoint

Where

The location within the business location where the event occurred, such as a scanner.

bizLocation

Where

The business location where the event occurred, such as a factory.

bizTransactionList

Why

A list of business-related transactions affecting the items, such as a purchase order or Bill of Lading.

sourceList

What

A list of elements providing context on the event origin.

destinationList

What

A list of elements providing context on the event destination.

errorDeclaration

When

It indicates that this event serves to assert that the assertions made by a prior event are in error.

certificationInfo

What

The URL at which certification details can be found.

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


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:

Additionally, 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 e.g., "custom:key":"value".


ObjectEvent

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

Field Name

Description

type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo

As above.

epcList

List of EPCs for unique items.

quantityList

List of objects describing the quantity of a class of item.

ilmd

ILMD introduced in the event.

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "event": {
      "type": "ObjectEvent",
      "action": "OBSERVE",
      "bizStep": "shipping",
      "disposition": "in_transit",
      "epcList": [
        "urn:epc:id:sgtin:0614141.107346.2017",
        "urn:epc:id:sgtin:0614141.107346.2018"
      ],
      "eventTime": "2005-04-03T20:33:31.116-06:00",
      "eventTimeZoneOffset": "-06:00",
      "readPoint": {
        "id": "urn:epc:id:sgln:0614141.07346.1234"
      },
      "bizTransactionList": [
        {
          "type": "po",
          "bizTransaction": "http://transaction.acme.com/po/12345678"
        }
      ],
      "example:myField": "Example of a vendor/user extension"
    }
  }
}
const epcisDocument = new EPCISDocument();
const objectEvent = new ObjectEvent();


objectEvent
    .addEPC('urn:epc:id:sgtin:0614141.107346.2017')
    .addEPC('urn:epc:id:sgtin:0614141.107346.2018')
    .setAction(cbv.actionTypes.observe)
    .setBizStep(cbv.bizSteps.shipping)
    .setDisposition(cbv.dispositions.in_transit)
    .setEventTime('2005-04-03T20:33:31.116-06:00')
    .setEventTimeZoneOffset('-06:00')
    .setReadPoint( new ReadPoint( { 'id' : 'urn:epc:id:sgln:0614141.07346.1234' } ))
    .addBizTransaction( new BizTransactionElement({
        type: 'po',
        bizTransaction: 'http://transaction.acme.com/po/12345678',
   }))
    .addExtension("example:myField, "Example of a vendor/user extension");

epcisDocument
    .setContext([
        "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
        {
        "example": "http://ns.example.com/epcis/"
        }
    ])
    .setCreationDate('2005-07-11T11:30:47.0Z')
    .addEvent(objectEvent);

AggregationEvent

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

Field Name

Description

type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo

As above.

parentID

URI of the parent item of the aggregation.

childEpcs

List of EPCs for unique child items.

childQuantityList

List of quantities of class-level child items.

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "event": {
      "type": "AggregationEvent",
      "eventTime": "2013-06-08T14:58:56.591Z",
      "eventTimeZoneOffset": "+02:00",
      "parentID": "urn:epc:id:sscc:0614141.1234567890",
      "childEPCs": [
        "urn:epc:id:sgtin:0614141.107346.2017",
        "urn:epc:id:sgtin:0614141.107346.2018"
      ],
      "action": "OBSERVE",
      "bizStep": "receiving",
      "disposition": "in_progress",
      "readPoint": {
        "id": "urn:epc:id:sgln:0614141.00777.0"
      },
      "bizLocation": {
        "id": "urn:epc:id:sgln:0614141.00888.0"
      },
      "childQuantityList": [
        {
          "epcClass": "urn:epc:idpat:sgtin:4012345.098765.*",
          "quantity": 10
        },
        {
          "epcClass": "urn:epc:class:lgtin:4012345.012345.998877",
          "quantity": 200.5,
          "uom": "KGM"
        }
      ],
      "example:myField": "Example of a vendor/user extension"
    }
  }
}
const epcisDocument = new EPCISDocument();
const aggregationEvent = new AggregationEvent();

aggregationEvent
  .setEventTime('2013-06-08T14:58:56.591Z')
  .setEventTimeZoneOffset('-06:00')
  .setParentId('urn:epc:id:sscc:0614141.1234567890')
  .addChildEPC('urn:epc:id:sgtin:0614141.107346.2017')
  .addChildEPC('urn:epc:id:sgtin:0614141.107346.2018')
  .setAction(cbv.actionTypes.observe)
  .setBizStep(cbv.bizSteps.receiving)
  .setDisposition(cbv.dispositions.in_progress)
  .setBizLocation( new BizLocation().setId("urn:epc:id:sgln:0614141.00888.0") )
  .setReadPoint( new ReadPoint().setId('urn:epc:id:sgln:0614141.07346.1234') )
  .addBizTransaction( new BizTransactionElement({
    type: 'po',
    bizTransaction: 'http://transaction.acme.com/po/12345678',
    }))
  .addChildQuantity( new QuantityElement({
    "epcClass": "urn:epc:idpat:sgtin:4012345.098765.*",
    "quantity": 10
    }))
  .addChildQuantity( new QuantityElement({
    "epcClass": "urn:epc:class:lgtin:4012345.012345.998877",
    "quantity": 200.5,
    "uom": "KGM"
  }))
  .addExtension("example:myField, "Example of a vendor/user extension");

epcisDocument
    .setContext([
        "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
        {
            "example": "http://ns.example.com/epcis/"
        }
    ])
    .setCreationDate('2005-07-11T11:30:47.0Z')
    .addEvent(aggregationEvent);

TransformationEvent

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

Field Name

Description

type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo

As above.

inputEPCList

Instance-level input EPCs.

inputQuantityList

Input class-level quantities.

outputEPCList

Instance-level output EPCs.

outputQuantityList

Output class-level quantities.

transformationID

ID allowing combination with other transformation events.

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2013-06-04T14:59:02.099+02:00",
  "epcisBody": {
    "event": {
      "type": "TransformationEvent",
      "eventTime": "2013-10-31T14:58:56.591Z",
      "eventTimeZoneOffset": "+02:00",
      "inputEPCList": [
        "urn:epc:id:sgtin:4012345.011122.25",
        "urn:epc:id:sgtin:4000001.065432.99886655"
      ],
      "inputQuantityList": [
        {
          "epcClass": "urn:epc:class:lgtin:4012345.011111.4444",
          "quantity": 10,
          "uom": "KGM"
        },
        {
          "epcClass": "urn:epc:class:lgtin:0614141.077777.987",
          "quantity": 30
        },
        {
          "epcClass": "urn:epc:idpat:sgtin:4012345.066666.*",
          "quantity": 220
        }
      ],
      "outputEPCList": [
        "urn:epc:id:sgtin:4012345.077889.25",
        "urn:epc:id:sgtin:4012345.077889.26",
        "urn:epc:id:sgtin:4012345.077889.27",
        "urn:epc:id:sgtin:4012345.077889.28"
      ],
      "bizStep": "commissioning",
      "disposition": "in_progress",
      "readPoint": {
        "id": "urn:epc:id:sgln:4012345.00001.0"
      },
      "ilmd": {
        "example:bestBeforeDate": "2014-12-10",
        "example:batch": "XYZ"
      },
      "example:myField": "Example of a vendor/user extension"
    }
  }
}
const epcisDocument = new EPCISDocument();
const transformationEvent = new TransformationEvent();

transformationEvent
  .setEventTime('2013-10-31T14:58:56.591Z')
  .setEventTimeZoneOffset('+02:00')
  .addInputEPC('urn:epc:id:sgtin:4012345.011122.25')
  .addInputEPC('urn:epc:id:sgtin:4000001.065432.99886655')
  .addInputQuantity( new QuantityElement({
    "epcClass": "urn:epc:class:lgtin:4012345.011111.4444",
    "quantity": 10,
    "uom": "KGM"
    }))
  .addInputQuantity( new QuantityElement({
    "epcClass": "urn:epc:class:lgtin:0614141.077777.987",
    "quantity": 30
    }))
  .addInputQuantity( new QuantityElement({
    "epcClass": "urn:epc:idpat:sgtin:4012345.066666.*",
    "quantity": 220
  }))
  .addOutputEPCList([
    "urn:epc:id:sgtin:4012345.077889.25",
    "urn:epc:id:sgtin:4012345.077889.26",
    "urn:epc:id:sgtin:4012345.077889.27",
    "urn:epc:id:sgtin:4012345.077889.28"
  ])
  .setBizStep(cbv.bizSteps.commissioning)
  .setDisposition(cbv.dispositions.in_progress)
  .setReadPoint( new ReadPoint().setId('urn:epc:id:sgln:0614141.07346.1234') )
  .setIlmd( new Ilmd({
    "example:bestBeforeDate": "2014-12-10",
    "example:batch": "XYZ"
  }))
  .addExtension("example:myField", "Example of a vendor/user extension")
    

epcisDocument
  .setContext([
  "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
  {
    "example": "http://ns.example.com/epcis/"
  }
    ])
  .setCreationDate('2013-06-04T14:59:02.099+02:00')
  .addEvent(transformationEvent);

AssociationEvent

An event linking identifiers to items or places.

Field Name

Description

type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo

As before.

parentID

URI of the parent item to this association.

childEPCs

List of unique EPCs for child items.

childQuantityList

Quantities child class-level child items.

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2019-11-01T14:00:00.000+01:00",
  "epcisBody": {
    "event": {
      "type": "AssociationEvent",
      "eventTime": "2019-11-01T14:00:00.000+01:00",
      "eventTimeZoneOffset": "+01:00",
      "parentID": "urn:epc:id:grai:4012345.55555.987",
      "childEPCs": [
        "urn:epc:id:giai:4000001.12345"
      ],
      "action": "ADD",
      "bizStep": "assembling",
      "readPoint": {
        "id": "urn:epc:id:sgln:4012345.00001.0"
      }
    }
  }
}
const epcisDocument = new EPCISDocument();
const associationEvent = new AssociationEvent();

associationEvent
  .setEventTime('2019-11-01T14:00:00.000+01:00')
  .setEventTimeZoneOffset('+01:00')
  .setParentId('urn:epc:id:grai:4012345.55555.987')
  .addChildEPC('urn:epc:id:giai:4000001.12345')
  .setAction(cbv.actionTypes.add)
  .setBizStep(cbv.bizSteps.assembling)
  .setDisposition(cbv.dispositions.in_progress)
  .setReadPoint( new ReadPoint().setId('urn:epc:id:sgln:4012345.00001.0') ) 

epcisDocument
  .setContext([
  "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
  {
    "example": "http://ns.example.com/epcis/"
  }
    ])
  .setCreationDate('2019-11-01T14:00:00.000+01:00')
  .addEvent(associationEvent);

TransactionEvent

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

Field Name

Description

type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo

As above.

parentID

The identifier of the parent item.

epcList

List of unique child EPCs for transaction items.

quantityList

List of quantity elements for class-level items.

{
  "@context": [
   "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2019-11-01T14:00:00.000+01:00",
  "epcisBody": {
    "event": {
      "type": "TransactionEvent",
      "action": "OBSERVE",
      "eventTime": "2019-08-19T01:09:32+02:00",
      "eventTimeZoneOffset": "+02:00",
      "epcList": [
        "urn:epc:id:sscc:95410228.0521987889"
      ],
      "bizStep": "shipping",
      "disposition": "in_transit",
      "bizTransactionList": [
        {
          "type": "desadv",
          "bizTransaction": "http://transaction.acme.com/desadv/12345678"
        },
        {
          "type": "po",
          "bizTransaction": "http://transaction.acme.com/po/18247893"
        },
        {
          "type": "bol",
          "bizTransaction": "http://transaction.acme.com/bol/389"
        }
      ],
      "readPoint": {
        "id": "urn:epc:id:sgln:0614141.07346.1234"
      },
      "sourceList": [
        {
          "type": "location",
          "source": "urn:epc:id:pgln:2983477.12344"
        }
      ],
      "destinationList": [
        {
          "type": "owning_party",
          "destination": "urn:epc:id:pgln:2983477.23849"
        },
        {
          "type": "location",
          "destination": "urn:epc:id:pgln:2983477.34324"
        }
      ]
    }
  }
}
const epcisDocument = new EPCISDocument();
const transactionEvent = new TransactionEvent();

transactionEvent
  .setAction(cbv.actionTypes.observe)
  .setEventTime('2019-08-19T01:09:32+02:00')
  .setEventTimeZoneOffset('+02:00')
  .addEPC('urn:epc:id:sscc:95410228.0521987889')
  .setBizStep(cbv.bizSteps.shipping)
  .setDisposition(cbv.dispositions.in_transit)
  .addBizTransactionList([
  new BizTransactionElement ({
    "type": "desadv",
    "bizTransaction": "http://transaction.acme.com/desadv/12345678"
  }),
  new BizTransactionElement ({
    "type": "po",
    "bizTransaction": "http://transaction.acme.com/po/18247893"
  }),
  new BizTransactionElement ({
    "type": "bol",
    "bizTransaction": "http://transaction.acme.com/bol/389"
    })
    ])
  .setReadPoint( new ReadPoint().setId('urn:epc:id:sgln:0614141.07346.1234') ) 
  .addSource( new SourceElement({
  "type": "location",
  "source": "urn:epc:id:pgln:2983477.12344"
    }) )
  .addDestination( new DestinationElement({
  "type": "owning_party",
  "destination": "urn:epc:id:pgln:2983477.23849"
    }) )
  .addDestination( new DestinationElement({
  "type": "location",
  "destination": "urn:epc:id:pgln:2983477.34324"
    }) )
    
epcisDocument
  .setContext([
  "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
  {
    "example": "http://ns.example.com/epcis/"
  }
    ])
  .setCreationDate('2019-11-01T14:00:00.000+01:00')
  .addEvent(transactionEvent);

Core Business Vocabulary types

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

Business steps

Format: $BIZSTEP

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

  • accepting - Denotes a specific activity within a business process where an object changes possession and/or ownership.
  • 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
  • collecting - Denotes a specific activity within a business process where an object is picked up and collected for future disposal, recycling or re-used.
  • 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 may 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 in order to obtain an accurate inventory for business needs other than accounting purposes (e.g., replenishment and allocation).
  • decommissioning - Instance-level identifier is disassociated from an object. The object may 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 should not be the subject of subsequent 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 is not yet associated with an object at this step in the process. Encoding SHOULD only be used in a TransactionEvent.
  • entering_exiting - Denotes a specific activity at the Entrance/Exit door of a facility where customers are either leaving with purchased product or entering with product to be returned to the facility.
  • holding - Denotes a specific activity within a business process where an object is segregated 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 may continue to exist and be the subject of subsequent events (via a barcode, manual data entry, replacement tag, etc.).
  • loading - Denotes a specific activity within a business process where an object is loaded into shipping conveyance. other A business step not identified by any of the values listed in the CBV.
  • 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 by 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 are not 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 will await transport pick-up.
  • stock_taking - Process of counting objects within a location following established rules and/or standards to serve as a basis for accounting purposes.
  • stocking - Denotes a specific activity within a business process within a location to make an object available to the customer o for order fulfilment within a 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 (e.g., a ship, a train, a lorry, an 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, by means of 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 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 may be reintroduced to the supply chain.
  • mismatch_class - Class-level identifiers do not correspond to the identifiers that were expected.
  • mismatch_instance - Instance-level identifiers do not correspond to the identifiers
  • mismatch_quantity - Quantity do not correspond to the quantity that was expected.that were expected.
  • 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.
  • non_conformant - Outcome of an unsuccessful/failed inspection in an inspecting or repairing step. (non_conformant is the opposite of available).
  • non_sellable_other - Object cannot be sold to a customer.
  • partially_dispensed - A portion of a product is distributed to a customer, while additional product is retained for subsequent distribution.
  • recalled - An item has been recalled.
  • reserved - Instance-level` - 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 may or may 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 customer cannot 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 (e.g., pending repair).
  • unknown - An object’s condition is not known.

Business transaction types

Format: $TYPE

Defined in the CBV Standard 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 (e.g. product), person, or organisation, typically issued by a third party.
  • desadv - Despatch Advice. A document/message by means of which the seller or consignor informs the consignee about the despatch of goods. Also called an “Advanced Shipment Notice,” but the value desadv is always used regardless of local nomenclature.
  • inv - Invoice. A document/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 referred to as a “Sales Order”.)
  • prodorder - Production Order. An organisation-internal document or message issued by a producer that initiates a manufacturing process of goods.
  • recadv - Receiving Advice. A document/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 Authorisation. A document issued by the seller that authorises a buyer to return merchandise for credit determination.
  • testprd - Test Procedure. A document that provides a formal specification of a sequence of instructions for the purpose of verifying one or several criteria.
  • testres - Test Result. A document that includes the outcome of the execution 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 (e.g., as the basis for the inferred completeness of inbound aggregations).

Source and Destination types

Format: $TYPE

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

  • owning_party - The party who will own the object at the source or destination.
  • possessing_party - The party with physical possession of the object at the included location.
  • location - The source/destination denotes the physical location of the object after the event, and should 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.
The possible values are the following:

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

Submit a single event

Submit a new EPCIS event, which is synchronously created and immediately available to read.

Events without eventID specified will have one assigned after processing is complete using the EPCIS Event ID Hash algorithm, which attempts 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

Make a request to the API to submit a single EPCIS event, including the event in the epcisBody property of the payload:

POST /epcis/events
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

EPCISDocument
curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.com/epcis/events \
  -d '{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "event": {
      "type": "ObjectEvent",
      "eventID": "test:docs:1",
      "action": "ADD",
      "bizStep": "shipping",
      "disposition": "received",
      "epcList": [
        "urn:epc:id:sgtin:0614141.107346.2017",
        "urn:epc:id:sgtin:0614141.107346.2018"
      ],
      "eventTime": "2005-04-03T20:33:32.116-06:00",
      "eventTimeZoneOffset": "-06:00",
      "readPoint": {
        "id": "urn:epc:id:sgln:0614141.07346.1236"
      },
      "bizTransactionList": [
        {
          "type": "urn:epcglobal:cbv:btt:po",
          "bizTransaction": "http://transaction.acme.com/po/123456782"
        }
      ]
    }
  }
}'
const payload = {
  '@context': [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      example: 'http://ns.example.com/epcis/'
    }
  ],
  type: 'EPCISDocument',
  schemaVersion: 2,
  creationDate: '2005-07-11T11:30:47.0Z',
  epcisBody: {
    event: {
      type: 'ObjectEvent',
      eventID: 'test:docs:1',
      action: 'ADD',
      bizStep: 'shipping',
      disposition: 'received',
      epcList: [
        'urn:epc:id:sgtin:0614141.107346.2017',
        'urn:epc:id:sgtin:0614141.107346.2018'
      ],
      eventTime: '2005-04-03T20:33:32.116-06:00',
      eventTimeZoneOffset: '-06:00',
      readPoint: {
        id: 'urn:epc:id:sgln:0614141.07346.1236'
      },
      bizTransactionList: [
        {
          type: 'po',
          bizTransaction: 'http://transaction.acme.com/po/123456782'
        }
      ]
    }
  }
};

evrythng.api({
  url: '/epcis/eventTypes/all/events',
  method: 'post',
  apiKey: operatorApiKey,
  data: payload,
})
  .then(console.log);
HTTP/1.1 201 Created
Content-Type: application/json

{
  "@context": [
   "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "event": {
      "type": "ObjectEvent",
      "eventID": "ni:///sha-256;24addc428d50127420f743c40e7da102bfa6c06a797a4b7cdf61ee8cb7058808?ver=CBV2.0",
      "action": "ADD",
      "bizStep": "shipping",
      "disposition": "received",
      "epcList": [
        "urn:epc:id:sgtin:0614141.107346.2017",
        "urn:epc:id:sgtin:0614141.107346.2018"
      ],
      "eventTime": "2005-04-03T20:33:32.116-06:00",
      "eventTimeZoneOffset": "-06:00",
      "readPoint": {
        "id": "urn:epc:id:sgln:0614141.07346.1236"
      },
      "bizTransactionList": [
        {
          "type": "po",
          "bizTransaction": "http://transaction.acme.com/po/123456782"
        }
      ]
    }
  }
}

Read a single event

Read a single EPCIS event by ID.

GET /epcis/events/:eventID
Authorization: $OPERATOR_API_KEY
curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.com/epcis/events/test:docs:1
const eventID = 'test:docs:1';

evrythng.api({
  url: `/epcis/events/${eventID}`,
  apiKey: operatorApiKey,
})
  .then(console.log);
HTTP/1.1 200 OK
Content-Type: application/json

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "event": {
      "type": "ObjectEvent",
      "eventID": "test:docs:1",
      "action": "ADD",
      "bizStep": "shipping",
      "disposition": "received",
      "epcList": [
        "urn:epc:id:sgtin:0614141.107346.2017",
        "urn:epc:id:sgtin:0614141.107346.2018"
      ],
      "eventTime": "2005-04-03T20:33:32.116-06:00",
      "eventTimeZoneOffset": "-06:00",
      "readPoint": {
        "id": "urn:epc:id:sgln:0614141.07346.1236"
      },
      "bizTransactionList": [
        {
          "type": "po",
          "bizTransaction": "http://transaction.acme.com/po/123456782"
        }
      ]
    }
  }
}

Capturing events

Submit a new capture document containing multiple events. Once the capture has been validated and accepted, the events contained within will be submitted individually asynchronously.

Make a request to the API to submit a single EPCIS event, including the eventList in the epcisBody property of the payload containing all the events that form part of the capture:

POST /epcis/capture
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

EPCISDocument
curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.com/epcis/capture \
  -d '{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": 2,
  "creationDate": "2005-07-11T11:30:47.0Z",
  "format": "application/ld+json",
  "epcisBody": {
    "eventList": [
      {
        "type": "ObjectEvent",
        "eventID": "test:10",
        "action": "OBSERVE",
        "bizStep": "shipping",
        "disposition": "in_transit",
        "epcList": [
          "urn:epc:id:sgtin:0614141.107346.2017",
          "urn:epc:id:sgtin:0614141.107346.2018"
        ],
        "eventTime": "2005-04-03T20:33:31.116-06:00",
        "eventTimeZoneOffset": "-06:00",
        "readPoint": {
          "id": "urn:epc:id:sgln:0614141.07346.1234"
        },
        "bizTransactionList": [
          {
            "type": "po",
            "bizTransaction": "http://transaction.acme.com/po/12345678"
          }
        ]
      }
    ]
  }
}'
const payload = {
  '@context': [
    'https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld',
    {
      example: 'http://ns.example.com/epcis/'
    }
  ],
  type: 'EPCISDocument',
  schemaVersion: 2,
  creationDate: '2005-07-11T11:30:47.0Z',
  format: 'application/ld+json',
  epcisBody: {
    eventList: [
      {
        type: 'ObjectEvent',
        eventID: 'test:10',
        action: 'OBSERVE',
        bizStep: 'shipping',
        disposition: 'in_transit',
        epcList: [
          'urn:epc:id:sgtin:0614141.107346.2017',
          'urn:epc:id:sgtin:0614141.107346.2018'
        ],
        eventTime: '2005-04-03T20:33:31.116-06:00',
        eventTimeZoneOffset: '-06:00',
        readPoint: {
          id: 'urn:epc:id:sgln:0614141.07346.1234'
        },
        bizTransactionList: [
          {
            type: 'po',
            bizTransaction: 'http://transaction.acme.com/po/12345678'
          }
        ]
      }
    ]
  }
};

evrythng.api({
  url: '/epcis/capture',
  method: 'post',
  apiKey: operatorApiKey,
  data: payload,
})
  .then(console.log);
const {
  ObjectEvent,
  cbv,
  setup,
  EPCISDocument,
  capture,
  BizTransactionElement,
} = require('epcis2.js');

// you can override the global parameter with the setup function
setup({
  apiUrl: 'https://api.evrythng.io/v2/epcis/',
  EPCISDocumentContext: 'https://ref.gs1.org/standards/epcis/2.0/epcis-context.jsonld',
  EPCISDocumentSchemaVersion: '2.0',
  headers: {
    'content-type': 'application/json',
    authorization: 'MY_API_KEY',
  },
});

const sendACaptureRequestExample = async () => {
  const objectEvent = new ObjectEvent();
  const epcisDocument = new EPCISDocument();
  const bizTransaction = new BizTransactionElement({
    type: 'po',
    bizTransaction: 'http://transaction.acme.com/po/12345678',
  });

  objectEvent
    .setEventTime('2005-04-03T20:33:31.116-06:00')
    .addEPC('urn:epc:id:sgtin:0614141.107346.2020')
    .addEPC('urn:epc:id:sgtin:0614141.107346.2021')
    .setAction(cbv.actionTypes.observe)
    .setEventID('ni:///sha-256;87b5f18a69993f0052046d4687dfacdf48f?ver=CBV2.0')
    .setBizStep(cbv.bizSteps.shipping)
    .setDisposition(cbv.dispositions.in_transit)
    .setReadPoint('urn:epc:id:sgln:0614141.07346.1234')
    .addBizTransaction(bizTransaction);

  epcisDocument.setCreationDate('2005-07-11T11:30:47+00:00').addEvent(objectEvent);

  const res = await capture(epcisDocument);
  const text = await res.text();
  console.log(`Request status: ${res.status}`);
  console.log(`Request response: ${text}`);
};

sendACaptureRequestExample();
HTTP/1.1 202 Accepted
Content-Type: application/json