Using the Shipper API to update shipment statuses in a TMS

A shipper already books freight in Cargobase, but the transport team lives in a TMS. Once a request is awarded, the TMS still shows the old status unless someone copies it across. This write-up is how we would connect those two systems with the Shipper API: which calls to make, how they land in the TMS, and what “done” looks like.

The problem

Cargobase is the system of record for the shipment after award. The TMS is the system of record for the internal team. The statuses diverge because nothing pushes shipment_status from one into the other.

The integration should:

• See only this company’s shipments.
• Ignore freight that is still a quote request.
• Write the current Cargobase status onto the matching TMS shipment.
• Pick up later changes without a person refreshing a screen.

What we use

A Shipper token, scoped to the company. Start on Sandbox (https://sandbox.cargobase.com), then switch to Production (https://pluto.cargobase.com) with a separate production token. Credentials are requested through support, not created in the docs portal. See Get API access and Environments.

Every call uses Token auth:

Authorization: Token <access_token>
Accept: application/json

Two read endpoints do the status work. Both are in the Shipper API reference.

Need	Call
Which awarded shipments exist	GET /api/1/shipments/
Current status and the rest of the record	GET /api/1/shipments/{shipment_reference}/

shipment_reference is the Cargobase id, for example S12345678. Until a request is awarded it is not in the shipment list. Those records stay on GET /api/1/requests/{shipment_reference}/. Do not treat a quote request as a live shipment in the TMS.

Posting milestones with POST /api/1/carrier-tracking-webhook is a provider call. A shipper TMS that only needs to read status does not use it.

How it plugs into the TMS

Store the Cargobase shipment id on the TMS job the first time the two records are linked (at booking, or the first time the shipment appears in the list). Later updates are a lookup by that id, not a search by title or tracking number.

1. Authenticate with the company Shipper token against the same host you used in Sandbox.
2. Call the shipment list to discover awarded shipments.
3. For each shipment_reference the TMS does not yet know, or that is still open, call shipment detail.
4. Read shipment_status from the organization object in the detail response.
5. Map that string onto the TMS status vocabulary and write it on the matching job.
6. On the next run, skip shipments the TMS has already marked delivered unless you still want a confirmation read.

A status read looks like this:

GET https://sandbox.cargobase.com/api/1/shipments/S12345678/
Authorization: Token <access_token>
Accept: application/json

A 200 body is grouped into organization, service, schedule, good_items, and related blocks. Status lives on organization.shipment_status. Dimensions, schedule, and packing lines are on the same response if the TMS needs more than a status code.

If the payload gets large or the same shipments are idle, prefer a webhook over a tight poll. Cargobase can POST a shipment update to an HTTPS URL you host whenever a tracking event arrives. Acknowledge with 2xx and update the TMS off that request thread. The event shape is in the Webhooks collection; the pattern is in Webhooks.

Keep the poll as a backstop: webhooks can be missed, and a periodic GET of open shipment ids repairs the TMS without waiting for the next event.

Failures the TMS should expect

What happened	Status	What the job should do
Status returned	200	Map organization.shipment_status and store it
Token missing or wrong environment	401 or 403	Stop the run. Do not mark the TMS shipment failed as a cargo status
Shipment not visible to this company, or wrong id	404 or 403	Leave the TMS row unchanged and flag the link
Too many reads	429	Back off and retry. See Errors
Cargobase unavailable	5xx	Retry a few times, then keep the last known TMS status

One shipment per request. There is no bulk status endpoint, so the TMS job loops ids and paces itself.

What this achieves

After the job runs, an awarded shipment in Cargobase has a matching TMS record with the same status, and later milestone changes update that record from shipment detail or from a webhook. The transport team stops copying status by hand, and Sandbox is used to prove the mapping before the host and token are switched to Production.