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:
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 as2026-02-31, answers400, 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
400with a field violation oncargo_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:
{
"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.
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
400with a field violation onclient_references. - Stored as written, case included.
S05749ands05749are 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:
{
"code": 10,
"message": "the shipment is completed or cancelled, so its client references can no longer be changed",
"details": []
}
When a change is refused
| Status | Why |
|---|---|
400 | A 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") |
404 | No shipment with that reference or id in your organization |
409 | A 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.