Cargoplot APICargoplot API
API docs
OpenAPI spec

Changing a shipment

A shipment can be read in full, and two of its fields can be written:

  • the cargo-ready date, the day your supplier has the cargo ready for collection;
  • your client references, your own order or purchase-order numbers.

Send the fields that change, and only those:

PATCH
/v1/shipment/C2AE-XEE1
curl -X PATCH 'https://api.cargoplot.com/v1/shipment/C2AE-XEE1' \
  -H 'X-Cargoplot-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d '{ "cargo_ready_date": "2026-11-09", "client_references": ["S05749"] }'

{shipment} takes the Cargoplot reference or the numeric id, as the reads do. The answer is 200 with the whole shipment, exactly as GET /v1/shipment/{shipment} renders it.

Each field has its own lock, described below. A body that carries both is refused whole when either is refused, so nothing changes. Sending a value the shipment already has is never refused, so repeating a request is harmless. Every change is recorded in the shipment's history and moves the shipment's update_time, which is what keeping a copy in sync reads. Any other key, the shipment's other fields included, answers 400 and message names it.

The cargo-ready date

When the day the cargo is ready moves, send the new one. The Cargoplot team handling the shipment gets a task to follow the change up: moving the pickup, and whatever is booked around it, is theirs to arrange.

What is accepted

  • A calendar date, as YYYY-MM-DD. A day that does not exist, such as 2026-02-31, answers 400, and so does an empty value: the date cannot be cleared.
  • Not before today, counted in UTC. Around midnight your own today and the UTC one can differ by a day. A date in the past answers 400 with a field violation on cargo_ready_date, as described under errors.

Once the cargo has been picked up

From then on the date is history rather than a plan, and a change answers 409:

json
{
  "code": 10,
  "message": "the cargo has already been picked up, so its cargo-ready date can no longer be changed",
  "details": []
}

Nothing records the pickup itself, so Cargoplot treats the cargo as picked up once any of these holds:

  • the shipment is completed or cancelled;
  • tracking reports the cargo loaded, sailing, arrived or discharged;
  • its ETD has come: the ETD's day, in UTC, is today or earlier.

If the date has to change after that, get in touch with your Cargoplot contact. The app follows the same rules, so a colleague cannot move it there either.

Client references

Your own order or purchase-order numbers, such as S05749, so you can link a shipment to your orders exactly. A shipment created from an inquiry starts with the inquiry's references; from then on they are kept, and changed, on the shipment.

PATCH
/v1/shipment/C2AE-XEE1
curl -X PATCH 'https://api.cargoplot.com/v1/shipment/C2AE-XEE1' \
  -H 'X-Cargoplot-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d '{ "client_references": ["S05749", "S05750"] }'

What is accepted

  • The list replaces the stored one. Send every reference the shipment should have; an empty list clears them.
  • At most 20 references, each 1 to 64 characters once surrounding whitespace is trimmed, and none twice. A list that breaks a rule answers 400 with a field violation on client_references.
  • Stored as written, case included. S05749 and s05749 are different references, though a filter matches either.

No task is raised: a change of references is recorded in the shipment's history and needs nothing from the Cargoplot team.

Once the shipment is completed or cancelled

References can still be changed after the cargo has been picked up, but not once the shipment is completed or cancelled. A change then answers 409:

json
{
  "code": 10,
  "message": "the shipment is completed or cancelled, so its client references can no longer be changed",
  "details": []
}

When a change is refused

StatusWhy
400A value breaks a rule, the body has a key the request does not have, or it names no field at all (message: "the request body names no field to change")
404No shipment with that reference or id in your organization
409A field is locked: the cargo has been picked up, for the cargo-ready date, or the shipment is completed or cancelled, for the client references

A value that breaks a rule answers with a google.rpc.BadRequest naming the field and why. An unknown key is named in message instead. The errors page shows both shapes in full and says which failures are worth retrying.