ActivateAuthenticateAmplify
API Reference
DashboardSupportDeveloper Blog

EPCIS 2.0 API

📘

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

Jump To ↓

EPCISDocument Data Model
Event structure
Event types
Core Business Vocabulary types
User Vocabulary
Read a single event
Submit a single event
Submit a capture

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.

Event FieldAspectDescription
typeWhatThe event type.
eventTimeWhenThe time the event occurred.
eventTimeZoneOffsetWhenThe time zone offset from UTC of the event time.
eventIDWhatGlobally unique ID of the event, used for deduplication and event retrieval. EPCIS2.0 specifies a hashing algorithm to construct a worldwide-unique ID for an event.
actionWhyThe type of action involved, usually one of ADD, OBSERVE or DELETE
bizStepWhyThe business step involved, defined in the CBV.
dispositionWhatThe current disposition or state of the items involved, defined in the CBV.
readPointWhereThe location within the business location where the event occurred, such as a scanner.
bizLocationWhereThe business location where the event occurred, such as a factory.
bizTransactionListWhyA list of business-related transactions affecting the items, such as a purchase order or Bill of Lading.
sourceListWhatA list of elements providing context on the event origin.
destinationListWhatA list of elements providing context on the event destination.
errorDeclarationWhenIt shows that this event asserts that the assertions made by a prior event are in error.
certificationInfoWhatThe URL at which certification details can be found.
sensorElementListHowThis is a new dimension which supports adding IoT sensor data to any event type.

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:

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.

Field NameDescription
type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo
sensorElementList		As above.
epcListList of EPCs for unique items - note that EPCIS 2.0 supports both 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)
quantityListList of objects describing the quantity of a class of item.
ilmdInstance/Lot Master Data (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.0",
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "eventList": [
      {
        "type": "ObjectEvent",
        "action": "OBSERVE",
        "bizStep": "shipping",
        "disposition": "in_transit",
        "epcList": [
          "https://dlnkd.tn.gg/01/9780345418913/21/123456",
          "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"
          }
        ],
        "sensorElementList": [
          {
            "sensorMetadata": {
              "time": "2019-04-02T14:05:00.000+01:00",
              "deviceID": "urn:epc:id:giai:4000001.111",
              "deviceMetadata":"https://dlnkd.tn.gg/8004/4000001111",
              "rawData": "https://example.org/8004/401234599999"
            },
            "sensorReport": [
              {
                "type": "Temperature",
                "value": 26.0,
                "uom": "CEL"
              },
              {
                "type": "AbsoluteHumidity",
                "value": 12.1,
                "uom": "A93"
              },
              {
                "type": "Speed",
                "value": 160.0,
                "uom": "KMH"
              },
              {
                "type": "Illuminance",
                "value": 800.0,
                "uom": "LUX"
              }
            ]
          }
         ],
        "example:myField": "Example of a vendor/user extension"
      }
    ]
  }
}

const epcisDocument = new EPCISDocument();
const objectEvent = new ObjectEvent();

objectEvent
	.addEPC('https://dlnkd.tn.gg/01/9780345418913/21/123456')
	.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',
   }))
  .addSensorElement(
    new SensorElement()
    .setSensorMetadata(
      new SensorMetadata()
        .setTime("2019-04-02T14:05:00.000+01:00")
        .setDeviceID("urn:epc:id:giai:4000001.111")
        .setDeviceMetadata("https://dlnkd.tn.gg/8004/4000001111")
        .setRawData("https://example.org/8004/401234599999")
      )
    .addSensorReport(
      new SensorReportElement()
        .setType(cbv.sensorMeasurementTypes.temperature)
        .setValue(26.0)
        .setUom('CEL')
    )
    .addSensorReport(
      new SensorReportElement()
        .setType(cbv.sensorMeasurementTypes.absolute_humidity)
        .setValue(12.1)
        .setUom('A93')
    )
    .addSensorReportList([
      new SensorReportElement()
        .setType(cbv.sensorMeasurementTypes.speed)
        .setValue(160.0)
        .setUom('KMH'),
      new SensorReportElement()
        .setType(cbv.sensorMeasurementTypes.illuminance)
        .setValue(800.0)
        .setUom('LUX')
      ]
    )
  )
	.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, such as packing into a case or pallet.

Field NameDescription
type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo
sensorElementList		As above.
parentIDURI of the parent item of the aggregation.
childEpcsList of EPCs for unique child items.
childQuantityListList 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.0",
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "eventList": [
      {
        "type": "AggregationEvent",
        "eventTime": "2013-06-08T14:58:56.591Z",
        "eventTimeZoneOffset": "+02:00",
        "parentID": "urn:epc:id:sscc:0614141.1234567890",
        "childEPCs": [
          "https://dlnkd.tn.gg/01/9780345418913/21/123456",
          "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 a new output item or class of item.

Field NameDescription
type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo
sensorElementList		As above.
inputEPCListInstance-level input EPCs.
inputQuantityListInput class-level quantities.
outputEPCListInstance-level output EPCs.
outputQuantityListOutput class-level quantities.
transformationIDID 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.0",
  "creationDate": "2013-06-04T14:59:02.099+02:00",
  "epcisBody": {
    "eventList": [
      {
        "type": "TransformationEvent",
        "eventTime": "2013-10-31T14:58:56.591Z",
        "eventTimeZoneOffset": "+02:00",
        "inputEPCList": [
          "https://dlnkd.tn.gg/01/9780345418913/21/123458",
          "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('https://dlnkd.tn.gg/01/9780345418913/21/123458')
  .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 NameDescription
type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo
sensorElementList		As above.
parentIDURI of the parent item to this association.
childEPCsList of unique EPCs for child items.
childQuantityListQuantities of child 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.0",
  "creationDate": "2019-11-01T14:00:00.000+01:00",
  "epcisBody": {
    "eventList": [
      {
        "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 NameDescription
type
eventTime
eventTimeZoneOffset
eventID
action
bizStep
disposition
readPoint
bizLocation
bizTransactionList
sourceList
destinationList
errorDeclaration
certificationInfo
sensorElementList		As above.
parentIDThe identifier of the parent item.
epcListList of unique child EPCs for transaction items.
quantityListList 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.0",
  "creationDate": "2019-11-01T14:00:00.000+01:00",
  "epcisBody": {
    "eventList": [
      {
        "type": "TransactionEvent",
        "action": "OBSERVE",
        "eventTime": "2019-08-19T01:09:32+02:00",
        "eventTimeZoneOffset": "+02:00",
        "epcList": [
          "https://dlnkd.tn.gg/00/954102280521987889"
        ],
        "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('https://dlnkd.tn.gg/00/954102280521987889')
  .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 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.

GET /epcis/events/:eventID
Authorization: $OPERATOR_API_KEY

curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.io/v2/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.0",
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "eventList": [
    	{
        "type": "ObjectEvent",
        "eventID": "test:docs:1",
        "action": "ADD",
        "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: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"
          }
        ]
      }
    ]
  }
}

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

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.io/v2/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.0",
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "eventList": [
      {
        "type": "ObjectEvent",
        "eventID": "test:docs:1",
        "action": "ADD",
        "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: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"
          }
        ]
      }
    ]
  }
}'

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.0",
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "eventList": [
        {
        "type": "ObjectEvent",
        "eventID": "test:docs:1",
        "action": "ADD",
        "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: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/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.0",
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "eventList": [
      {
        "type": "ObjectEvent",
        "eventID": "test:docs:1",
        "action": "ADD",
        "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: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 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:

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.io/v2/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.0",
  "creationDate": "2005-07-11T11:30:47.0Z",
  "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.0",
  creationDate: '2005-07-11T11:30:47.0Z',
  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