Skip to main content

Upstream API FAQ

The questions that come up most often when building against the v3 Upstream API. For the endpoint reference itself, see Upstream.

Polling and the since parameter​

How do I use since?​

Pass it as a query parameter on the GET request:

GET /v3/upstream?since=2026-06-06T14:30:00Z

Several date formats are accepted, but ISO 8601 with an explicit timezone is the recommended form. It removes any ambiguity about how a bare date is interpreted.

since and cursor work together rather than as alternatives. Page through with both until next_cursor comes back null, then store the highest metadata.last_updated you saw as the starting point for the next run.

Why did a tradeflow come back that had not changed?​

A tradeflow can be touched by data that is not reflected in the message you receive. The clearest example is data arriving for the container's next journey: something changed on the record, so the timestamp moves, but the content of the message for your shipment is the same.

This is confusing rather than harmful, and these cases are filtered out where they can be identified.

I am receiving duplicate messages where only last_updated differs​

Same root cause as above. If you are deduplicating on your side, compare the payload rather than the timestamp.

Active and deactivated tradeflows​

Do you send is_active: false?​

Yes.

The default behaviour without the active parameter is to return active tradeflows plus recently deactivated ones, within a 7 day window. After that window they drop off entirely.

With active=true set explicitly, only strictly active tradeflows are returned.

Mind the 7 day window

If your polling interval is longer than the deactivation window, you can miss the deactivation entirely. A tradeflow deactivated the day after your last poll will simply be absent from the next one, with no is_active: false message ever observed.

For an ERP replication that needs to mirror deactivations, poll inside the window.

Vessel and voyage​

Where is the vessel in the payload?​

In the shipment element, in two places:

shipment.current_vessel - the current vessel with its identifiers:

{
  "current_vessel": {
    "name": "MAERSK SOPHIE",
    "imo": "9721234",
    "mmsi": "219028000"
  }
}

shipment.shipment_legs - the per-leg detail, which is where you look when a journey has more than one vessel.

Cargo opening and cut-offs​

Where do I find yard opening and closing times?​

They are separate fields with separate origins. The carrier's own gate-open time (EFC) appears in cutoffs[] and can differ from cargo_opening:

FieldContainsSource
cargo_openingYard openingTerminal data
cutoffs[]Yard closing, VGM, documentation, shipping instructions, dangerous goods, LCL delivery, customs, out of gauge, earliest full-container delivery (EFC), empty container pickup (ECP)The carrier

Cut-offs are populated on the export leg at the port of loading. Coverage depends on the carrier and the port publishing them.

Ingestion​

Why has the feed gone quiet for one tradeflow?​

The v3 feed does not pause for data anomalies: every change to a tradeflow is delivered, and data_quality.anomalies is an indicative count you can use to filter on your side. If a tradeflow has gone quiet, nothing about it has changed since your last poll. See anomaly classification.

Sending data in​

customer_name created a party I did not expect​

Send the customer once, spelled the same way everywhere. Identical names resolve to the same organisation, but if customer_name and a partner entry spell the company differently (for example ACME and ACME NV), they become two separate parties.

Check that customer_name holds the company and not the contact person. A contact name in that field creates an entity named after the individual.

An order was accepted but did not appear​

A 202 response means the message was accepted for processing, not that the tradeflow exists yet. Processing is asynchronous and normally quick.

If it does not appear at all, confirm that tradeflow_reference was set on the request. Support can check the inbound logs for your reference and confirm whether the call arrived.

Errors​

What do the authentication errors mean?​

StatusMeaning
400The token is not in the {env}_{organisation-slug}_{random} format.
401The Authorization header is missing or malformed, or the token is not recognised.
403The token has been revoked, or it is used on the wrong host (prod_… on api.dockflow.com, uat_… on uat.dockflow.com).

See Authorization.