Trades

Trades are commercial operations focusing on the cargo. As such, they are the items carrying the commercial information, such as the charterers. Because the trades are cargo-centered, they can involve more than one vessel if ship-to-ships are involved.

Each trade is defined by a load (origin) and a discharge (destination), vessels involved and the players - sellers, charterers, buyers. It comes with a quantity and a list of products : the cargo.

Trade IDs

Every trade is provided through the API with a unique ID, based on the pair Origin-Destination. It means that the ID is spanned over as many lines as there are products exchanged.

On the snapshot above, we have one trade from Juaymah to Chevron El Segundo Refinery, with a cargo loaded by Pascagoula Voyager and eventually discharged by Polaris Voyager in the US. The cargo was composed of Arab Xlt. and Arab Light. Thus, there are two lines for this trade via the trades endpoint.

Trade ID is based on the Origin and the rank of the discharge in the discharge vessel's voyage. Yet, we wanted to provide an ID that was unique to the line, and independent from the product.

Shipments

The Shipment is to be seen as a single-product trade, which ID is not related to the product. It has been built to allow users understand the evolution of data over time as shown in the image below.

Since the details can evolve across the life the cargo, the new ID is coming with a Parent ID to follow lineage of the data. These lineage rules are:

Shipment ID rules

The Shipment ID is unique and cannot be reused. It will be stable across the life of the cargo.

The Shipment ID will not change if any of the following attributes change:

Buyer/Seller/ Charterer
Product details: Family/ Group/ Product/ Grade
Load date
Destination: Location, dates
Quantity
STS is occurring, moving the cargo from one vessel to another

If the load location differs from fixed one, or vessel is changed:

Original ID should show cancellation (It can’t be found anymore in Trades endpoint in the Shipment ID column)
New Unique Shipment ID should be created

New IDs can be generated if the cargo is

split into co-loads of different products (i.e. Crude/co is split into Arab Lt. and Arab M.)
if a partial discharge occurs.

In these situations one of the multiple shipments will retain the original ID.

An audit trail is available to easily identify the historical parent-child relationship through the Parent ID.

New ID, same endpoint

To keep it simple, the shipment ID has been added to the /v1/Trades endpoint. Both ID coexist there, the introduction of the shipment ID doesn't mean that the existing trade ID will be removed.