Trace API overview

The Transparent Supply Trace API allows authorized users to retrieve information about their organization's supply chain products, locations, events and transactions. End-to-end product traceability means that authorized users can easily find and trace the path of their organization's product instances along the supply chain.

Trace endpoints

The Trace API provides two endpoints: basic trace and consumer trace. Basic trace is included by default; Consumer trace is a value add-on that must be selected by your organization.

Basic trace

The basic trace endpoint takes a product instance as input, as a single product lot, pallet, or serial number. The basic trace results include event and transaction information for both the input product other connected product instances. These connections occur, for example, when the input product is combined or packed with other products.

The JSON identifiers returned by a basic trace call include:

  • Product identification
  • Input product instance (identifier)
  • Output product instances (identifiers)
  • Supply chain events

Basic trace returns only JSON identifiers for these assets. For additional trace results, the application should make additional calls to return details such as product descriptions or location facility details.

The returned JSON is a tree structure rooted at the input lots/pallets, with other product lots/pallets related to the initial inputs as nested children. Each node in the tree structure is connected to other product lots/pallets through related events, such as transformations or aggregations.

When traversing the JSON structure, the direction of the supply chain can be inferred by the nature of the EPCs:

  • Output lot/pallet is a downstream relation through transformations
  • Input lot/pallet is an upstream relation through transformations
  • Child lot/pallet is an upstream relation in an aggregation, and a downstream relation in a disaggregation
  • Parent lot/pallet is a downstream relation in an aggregation, and an upstream relation in a disaggregation

Each node in the JSON tree structure also describes the events for the product lot/pallet, such as:

  • Transformation changes an input product into a new product
  • Aggregation or disaggregation packs or unpacks separable products
  • Observation records the product location along the supply chain
  • Commission originates the product instance on the supply chain
  • Decommission removes the product instance from the supply chain

Outbound swagger API denotes service endpoints that return output ranging from basic data (product or facility descriptions) to connected elements such as those contained in trace results.

Consumer trace

The consumer trace endpoint also takes a product instance as input - a single product lot, pallet, or serial number. It returns the same basic trace JSON identifiers plus additional contextual information for enhanced consumability.

In addition to the basic trace JSON identifiers, consumer trace also returns:

  • Product details - identifier and owning organization
  • Facility details - identifier and owning organization
  • Attachment details - payloads attached to events, products and facilities
  • Business transaction details - purchase order, despatch advice and receive advice information
Note: Due to its scope and detailed results, the consumer trace endpoint can be both resource intensive and return a high volume of data. Be sure to consider those variables when using the consumer trace endpoint, in particular for any automated calls.

To limit the data returned by consumer trace, set one or more of the following parameters to false with the API call (the default values are true):

include_events
include_products
include_lots_and_serials
include_locations
include_trace
include_payloads

Note: Events and payloads tend to return the largest volume of data.