Skip to content

How to Request EPCIS Shipment Data from a Wholechain User

This guide explains how retailers, distributors, or importers who do not use Wholechain can request and receive EPCIS 2.0-compliant shipment and event data directly from a Wholechain supplier. Wholechain’s data exchange follows the GS1 EPCIS 2.0 global standard and the Global Dialogue on Seafood Traceability (GDST) framework, ensuring full interoperability across different traceability systems.

Provide your Wholechain supplier with the Digital Link URL your EPCIS system uses to receive incoming event data. This URL will be the endpoint where Wholechain sends standardized EPCIS events such as shipping, receiving, and transformation.

Example: https://example.com/api/v1/epcis/events

Your endpoint must: - Support GS1 EPCIS 2.0 in JSON-LD or XML format
- Be secured via HTTPS
- Be capable of processing EPCIS event types (ObjectEvent, AggregationEvent, TransformationEvent, TransactionEvent)

2. Provide an API Key or Access Token

Wholechain uses secure API-based authentication when sending EPCIS data externally.
Provide your supplier with an API key or bearer token that authorizes their system to transmit data to your endpoint.

Example: api-key-RETAILER-92HSKJDF93

This ensures that all EPCIS events received from Wholechain are verified and traceable.

3. Supplier Configuration in Wholechain

Your supplier will complete the configuration from their Wholechain account.
They will:

  1. Open the Networks tab.
  2. Click Actions → Add Company/Location.
  3. Enter your company information (name, GLN, or other identifiers).
  4. Toggle “This company uses another traceability system.”
  5. Paste in your Digital Link URL.
  6. Enter your API Key.
  7. Click Save to finalize the connection.

Once saved, the Wholechain system recognizes your company as an external EPCIS-compliant traceability partner.

4. Receiving EPCIS Data

When a shipment is created or updated in Wholechain, the supplier’s system will automatically generate and send EPCIS event payloads to your endpoint.

You will receive standardized GS1 EPCIS 2.0 event types such as: - ObjectEvent — product shipping or receiving
- AggregationEvent — grouping or ungrouping of items or cases
- TransformationEvent — processing or conversion of inputs to outputs
- TransactionEvent — linking EPCIS events to business transactions (e.g., purchase orders)

Each event payload includes the GS1 Core Business Vocabulary fields: - eventTime
- bizStep (e.g., shipping, receiving, transforming)
- epcList (product identifiers such as GTIN or lot code)
- readPoint and bizLocation
- disposition (state, e.g., active, in transit)
- certifications or traceability references (if applicable)

5. Validate and Confirm Integration

After setup:

  • Confirm that your endpoint successfully receives data from Wholechain.
  • Verify authentication using the provided API key.
  • Validate payloads against the GS1 EPCIS 2.0 schema.
  • Confirm the data flows correctly into your EPCIS dashboard, traceability platform, or internal systems.
  • Notify your supplier once successful ingestion is verified.

6. Example Workflow

Scenario:
A seafood retailer uses an internal EPCIS system and wants to receive shipment traceability from a Wholechain supplier.

  1. The retailer provides:
  2. Digital Link URL: https://trace.retailer.com/api/v1/epcis/events

  3. API Key: api-key-SEAFOOD-123XYZ

  4. The supplier configures this connection inside Wholechain.

  5. When the supplier ships yellowfin tuna, Wholechain sends the following EPCIS ObjectEvent to the retailer’s system: 

    {
"type": "ObjectEvent",
"eventTime": "2025-10-20T14:32:00Z",
"bizStep": "shipping",
"disposition": "in_transit",
"epcList": ["urn:epc:id:sgtin:0614141.107346.2017"],
"readPoint": { "id": "urn:epc:id:sgln:0614141.07346.1234" },
"bizLocation": { "id": "urn:epc:id:sgln:0614141.07346.9999" }
}

  6. The retailer’s EPCIS system automatically logs the shipment, maintaining a continuous traceability chain from supplier to buyer.

7. GDST Alignment

Wholechain’s EPCIS data structure is fully GDST-aligned, ensuring that seafood-specific Key Data Elements (KDEs) and Critical Tracking Events (CTEs) are transmitted accurately. This includes: • Species identification • Harvest method and vessel information • Processing and transformation events • Certifications (e.g., GSA, MSC, BAP) • Shipment and receiving events

By following both GS1 EPCIS 2.0 and GDST specifications, Wholechain ensures seamless interoperability and verifiable seafood traceability between systems.

⸻

Summary

To request EPCIS shipment data from a Wholechain user: 1. Provide your EPCIS endpoint (Digital Link URL) 2. Share a valid API key for secure transmission 3. Allow your supplier to configure your endpoint in Wholechain 4. Begin receiving standardized, GDST-compliant EPCIS event data automatically

This setup enables transparent, standardized traceability between Wholechain and your system — ensuring compliance, visibility, and data integrity across the global seafood supply chain.