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:

FieldContainsSource
cargo_openingYard openingTerminal data
cutoffs[]Yard closing, VGM, shipping instructions, dangerous goods, customs, out of gaugeThe 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 and pauses​

Why has the feed stopped for one tradeflow?​

Check whether the tradeflow carries a data anomaly. When one is detected, outbound messages for that tradeflow are paused rather than sent, and the tradeflow is flagged.

The pause is deliberate: it stops a tradeflow that is known to be inconsistent from propagating into your system. A typical trigger is containers on the file that the carrier does not associate with the booking.

Resolve the anomaly and the feed resumes. See anomaly classification.

Sending data in​

customer_name created a party I did not expect​

Send the customer once. If you pass the customer in customer_name and again as a partner with a role, you create a second party from the same company, and it appears as a separate entity.

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​

I am getting 403 responses intermittently​

Send the timestamps of the failures. Intermittent 403s on an otherwise working token are investigated from the request logs rather than from the token itself.

I am getting 504 on the upstream endpoint​

Timeouts on upstream have been traced to load peaks when large numbers of vessel schedule changes land at once. If you see them clustered in a window rather than spread out, include the window when reporting.