The following shipment operations are included in the API documentation:

Data scope

This API returns data from the "active" database for the customer. That is, shipments that have not progressed to the historical/archive databases. The timing for archiving shipments varies by customer. This API is not intended for historical reporting and bulk data extraction. Please contact CargoOffice support if you are after bulk data extraction.

Common conventions

Authentication

All requests require an API key supplied in the X-API-KEY request header.

See the Authentication article for complete authentication and API key handling requirements.

Response format

Responses are returned as JSON.

Clients should send the following header:

ShellAccept: application/json

Identifiers and references

Shipment identifiers, tracking numbers and reference numbers are returned as strings.

Values that contain only digits must still be treated as strings. This is important because customer references may contain leading zeroes, such as:

Shell0075052479

Unavailable values

A field with no available value may be returned as:

• null

• An empty string

• An omitted optional object, such as proofOfDelivery or temperature

Consumers should handle these representations without assuming that an unavailable value is zero.

Retrieve shipment details

Returns the details of a single shipment using the shipmentID/connote number (preferred, default) or an external customer reference. If both id and ref are provided, id will be used.

Request

ShellGET /API/external/shipments/details.php?id={shipmentID}
GET /API/external/shipments/details.php?ref={reference}

Production URL:

Shellhttps://api.cargooffice.com.au/API/external/shipments/details.php

Query parameters

The reference is resolved within the customer scope assigned to the API key.

Please note:

ShipmentID's will be unique in the scope of typical access, but customer provided references may not be. To that end, if multiple shipments match the reference, only the most recently created shipment will be returned.

Special characters will be removed, only alphanumeric references are supported.

Example request

Shellcurl --request GET \
  --url "https://api.cargooffice.com.au/API/external/shipments/details.php?id=12345678" \
  --header "Accept: application/json" \
  --header "X-API-KEY: <API key>"

Example success response

The following response is representative and has been sanitised for documentation:

JavaScript{
  "success": true,
  "shipment": {
    "id": "224446",
    "trackingNumber": "19248.224446",
    "customerID": "EXAMPLE",
    "references": {
      "order": "ORDER-001",
      "pickup": null,
      "delivery": "ORDER-001"
    },
    "remarks": null,
    "createdDate": "2026-06-29",
    "pickupDate": "2026-06-30",
    "deliveryDate": "2026-07-07",
    "serviceType": "Local",
    "depot": null,
    "tracking": {
      "realTime": "",
      "trackAndTrace": "https://example.cargooffice.com.au/tracking/?s=224446",
      "trackAndTraceMilestones": {
        "received": {
          "timestamp": "2026-08-04 12:24",
          "status": "EDI Import"
        },
        "planned": {
          "timestamp": "2026-08-04 13:07",
          "status": "assigned delivery"
        },
        "pickedup": {
          "timestamp": "",
          "status": ""
        },
        "enroute": {
          "timestamp": "2026-08-05 06:01:13",
          "status": "en route"
        },
        "delivered": {
          "timestamp": "2026-08-06 13:21:17",
          "status": "delivery ok"
        }
      },
      "externalTracking": {
        "source": "EXTERNAL CARRIER",
        "currentStatus": "In Transit",
        "trackAndTraceUrl": "https://external-tracking.example.com/?id=1234567",
        "trackAndTraceMilestones": [
          {
            "sequence": "1",
            "status": "Pickup",
            "note": "CHC",
            "timestamp": "",
            "expected": ""
          },
          {
            "sequence": "2",
            "status": "InDepot",
            "note": "CHC",
            "timestamp": "2026-09-18T16:19:11.0000000",
            "expected": ""
          },
          {
            "sequence": "3",
            "status": "OnLinehaul",
            "note": "CHC",
            "timestamp": "2026-09-18T17:37:03.0000000",
            "expected": ""
          },
          {
            "sequence": "4",
            "status": "Unload",
            "note": "AKL",
            "timestamp": "",
            "expected": "2026-09-22T00:00:00.0000000"
          },
          {
            "sequence": "5",
            "status": "OFD",
            "note": "AKL",
            "timestamp": "",
            "expected": "2026-09-22T00:00:00.0000000"
          },
          {
            "sequence": "6",
            "status": "Delivered",
            "note": "AKL",
            "timestamp": "",
            "expected": "2026-09-22T00:00:00.0000000"
          }
        ]
      }
    },
    "status": {
      "current": "delivery ok",
      "pickup": null,
      "delivery": "delivery ok",
      "events": [
        {
          "sequence": 1,
          "timestamp": "2026-06-29 09:32",
          "status": "EDI Import",
          "note": null
        },
        {
          "sequence": 2,
          "timestamp": "2026-07-07 10:21:40",
          "status": "POD",
          "note": "signed by: Example Receiver"
        }
      ]
    },
    "stops": [
      {
        "sequence": 1,
        "type": "pickup",
        "date": "2026-06-30",
        "name": "Example Sender",
        "notes": null,
        "reference": null,
        "timeslot": null,
        "address": {
          "address": "1 Example Street",
          "suburb": "Example Suburb",
          "state": "VIC",
          "postcode": "3000",
          "country": "Australia",
          "coordinates": {
            "latitude": -37.8136,
            "longitude": 144.9631
          }
        },
        "contact": {
          "contact": null,
          "phone": null,
          "email": null
        }
      },
      {
        "sequence": 2,
        "type": "delivery",
        "date": "2026-07-07",
        "name": "Example Receiver",
        "notes": null,
        "reference": "ORDER-001",
        "timeslot": null,
        "address": {
          "address": "2 Example Road",
          "suburb": "Example Suburb",
          "state": "QLD",
          "postcode": "4000",
          "country": "Australia",
          "coordinates": {
            "latitude": -27.4698,
            "longitude": 153.0251
          }
        },
        "contact": {
          "contact": "Example Receiver",
          "phone": "0400000000",
          "email": "receiver@example.com"
        },
        "proofOfDelivery": {
          "signedBy": "Example Receiver",
          "signedAt": "2026-07-07 10:21:40"
        }
      }
    ],
    "goods": {
      "lines": [
        {
          "lineNumber": 1,
          "description": "MIXED GOODS",
          "status": "2026-08-03 12:46:40 in transit",
          "notes": null,
          "quantity": 1,
          "weight": {
            "value": 25,
            "unit": "kg"
          },
          "dimensions": {
            "length": null,
            "width": null,
            "height": null
          },
          "volume": {
            "value": 0.2,
            "unit": "m3"
          },
          "packaging": {
            "type": "CTN",
            "temperature": null
          }
        }
      ],
      "totals": {
        "quantity": 1,
        "weight": {
          "value": 25,
          "unit": "kg"
        },
        "volume": {
          "value": 0.2,
          "unit": "m3"
        }
      }
    }
  },
  "remainingDailyQuota": "4996"
}

Top-level response fields

Shipment fields

Dates are returned in YYYY-MM-DD format.

Reference fields

Tracking fields

Applications should verify that a tracking value is non-empty before displaying it as a link.

Track and trace milestone fields

Milestones are a high level overview of the status events, with an internal mapping of statuses to milestones. Not all CargoOffice customers have the same set of statuses and not all shipments have all milestones, milestones can happen more than once.

If a milestone is not detected, the object will contain an empty string for both timestamp and status.

The source of truth is still: shipment.status.events.

External tracking fields

External milestones

External milestones are saved as-is from the external system when they are provided. There is no additional mapping to CargoOffice statuses or milestones and no agreed standardization. Any mapping to CargoOffice statuses and milestones would have already happened.

Shipment status fields

Statuses in CargoOffice are heavily customizable, they can be almost any value, do not need to follow a specific order, can happen more than once or may never happen.

Status descriptions may reflect customer-specific CargoOffice workflows. Consumers should treat them as strings unless a separate agreed status mapping has been provided.

Please contact your CargoOffice customer for an up to date list of their statuses and for assistance mapping them to your needs.

Status event fields

Status event ordering and timestamps

Status event timestamps are recorded in the local time of the entity that generated the event. They do not include a UTC offset or timezone identifier.

The sequence field represents the recorded event order. Consumers should use sequence, rather than sorting by timestamp, when displaying shipment history.

Timestamps may contain either minutes or seconds:

HTML2026-06-29 09:32
2026-07-07 10:21:40

Consumers should support both:

HTMLYYYY-MM-DD HH:mm
YYYY-MM-DD HH:mm:ss

Stop fields

Each entry in shipment.stops represents a pickup or delivery location.

proofOfDelivery is optional and may be omitted entirely when proof of delivery is unavailable.

Address fields

Contact fields

Phone numbers should be treated as strings because their formatting may vary.

Proof-of-delivery fields

Goods fields

Goods line fields

The current response does not include a unit alongside the dimension fields. The applicable dimension unit should be confirmed as part of the integration specification before these values are consumed.

Goods total fields

A null line value should not automatically be interpreted as zero. A numeric 0 represents the value returned by CargoOffice.

Daily Quota

Quotas reset daily and are shared across all API requests. When this number reaches 0, a 429 status code error will be returned informing the consumer that they have exceeded their quota.

List shipments

Returns a paginated list of shipments within the customer scope assigned to the API key.

The endpoint is read-only. Customer scope restrictions are applied automatically and cannot be overridden using filters.

Request

ShellGET /API/external/shipments/list.php

Production URL:

Shellhttps://api.cargooffice.com.au/API/external/shipments/list.php

Query parameters

The customer scope assigned to the API key is always applied before the requested filters.

Please note:

Filter fields and operators must use the exact spelling and capitalisation documented below.

Query parameter values should be URL encoded. For example, a space should be represented as %20.

The square brackets shown in the examples form part of the query parameter names.

Example request

Shellcurl --globoff 
  --request GET \ 
  --url "https://api.cargooffice.com.au/API/external/shipments/list.php?filter[deliveryDate][gte]=2026-08-07&filter[goods][contains]=4000000015351218&page=1&limit=50" \ 
  --header "Accept: application/json" \ 
  --header "X-API-KEY: <API key>"

The --globoff option prevents curl from interpreting the square brackets in the filter parameters.

Filtering

A filter uses the following structure:

Shellfilter[field][operator]=value

For example:

ShellGET /API/external/shipments/list.php?filter[deliveryDate][gte]=2026-08-07

This returns shipments where the delivery date is on or after 7 August 2026.

Combining filters with AND

Filters at the same level are automatically combined using AND.

ShellGET /API/external/shipments/list.php?filter[deliveryDate][gte]=2026-08-07&filter[goods][contains]=pickles

This means:

ShelldeliveryDate is on or after 2026-08-07
AND
a goods identifier contains pickles

Multiple different operators can be applied to the same field:

ShellGET /API/external/shipments/list.php?filter[deliveryDate][gte]=2026-08-01&filter[deliveryDate][lte]=2026-08-31

This returns shipments with a delivery date between 1 August and 31 August 2026, inclusive.

Explicit AND and OR groups

Numbered and and or groups can be used for more complex conditions.

The general formats are:

Shellfilter[and][0][field][operator]=value
filter[and][1][field][operator]=value

and:

Shellfilter[or][0][field][operator]=value
filter[or][1][field][operator]=value

For example:

ShellGET /API/external/shipments/list.php?filter[or][0][currentStatus][eq]=Acknowledged&filter[or][1][currentStatus][eq]=In%20Transit

This means:

ShellcurrentStatus equals Acknowledged 
OR 
currentStatus equals In Transit

Numbered groups also allow the same field and operator to be used more than once without one query parameter replacing another.

Nested groups

Logical groups can be nested.

The following condition:

Shell( 
    deliveryDate is on or after 2026-08-07 
    AND 
    deliveryDate is on or before 2026-08-31 
) 
OR 
( 
    currentStatus equals Invoiced 
    AND 
    totalVolume is greater than 0 
)

Can be represented as:

ShellGET /API/external/shipments/list.php 
    ?filter[or][0][and][0][deliveryDate][gte]=2026-08-07 
    &filter[or][0][and][1][deliveryDate][lte]=2026-08-31 
    &filter[or][1][and][0][currentStatus][eq]=Invoiced 
    &filter[or][1][and][1][totalVolume][gt]=0 
    &sort[]=deliveryDate:asc 
    &sort[]=createdDate:desc

NOTE: The line breaks above are included for readability. The actual request URL should be sent as one continuous URL.

Please note:

Each logical group must contain either an and key or an or key.

A group cannot contain both and and or, and a logical key cannot be mixed with direct field filters at the same level.

Group entries must use numeric indexes such as [0], [1], and [2].

Filter operators

Not every operator is available for every field. Refer to the field tables for the exact operators supported by each field.

Values supplied to contains, notContains, and startsWith are treated as literal text. Characters such as % and _ are not treated as client-supplied wildcard characters.

Using IN and NOT IN

The in and notIn operators require an array of values.

ShellGET /API/external/shipments/list.php?filter[currentStatus][in][]=Acknowledged&filter[currentStatus][in][]=In%20Transit

This returns shipments where the current status is either Acknowledged or In Transit.

A comma-separated string should not be used:

Shellfilter[currentStatus][in]=Acknowledged,In Transit

Each value must be supplied separately using [].

Available filter fields

Shipment identifiers and references

Shipment IDs should be treated as strings because they may contain leading zeroes.

Example customer filter:

ShellGET /API/external/shipments/list.php?filter[customerID][eq]=TESTCUSTOMER

The supplied customer ID must still be within the customer scope assigned to the API key.

Dates

Date filter values must use YYYY-MM-DD format.

Example date range:

ShellGET /API/external/shipments/list.php?filter[createdDate][gte]=2026-08-01&filter[createdDate][lt]=2026-09-01

This returns shipments created during August 2026.

Statuses

currentStatus examines only the current status.

statusHistory searches the complete status history. It can be used to find shipments that previously passed through a particular status, even if that status is no longer current.

Example:

ShellGET /API/external/shipments/list.php?filter[statusHistory][contains]=in%20transit&filter[statusHistory][notContains]=Invoiced

This returns shipments whose status history contains in transit but does not contain Invoiced.

Pickup details

Example:

ShellGET /API/external/shipments/list.php?filter[pickupSuburb][eq]=Mount%20Wellington&filter[pickupState][eq]=AKL

Delivery details

Example:

ShellGET /API/external/shipments/list.php?filter[deliveryName][contains]=Building%20Services&filter[deliverySuburb][eq]=Dunedin

Shipment totals and goods

The goods field searches every numbered goods line associated with a shipment. Clients do not need to know which goods line contains the identifier.

Example:

ShellGET /API/external/shipments/list.php?filter[goods][contains]=pickles

This matches when any goods text that contains "pickles".

Sorting

Sorting uses one or more sort[] query parameters:

Shellsort[]=field:direction

The supported directions are:

Example:

ShellGET /API/external/shipments/list.php?sort[]=deliveryDate:asc

Multiple sort fields are applied in the order supplied:

ShellGET /API/external/shipments/list.php?sort[]=deliveryDate:asc&sort[]=createdDate:desc

This sorts by delivery date first. Shipments with the same delivery date are then sorted by created date in descending order.

Please note:

A maximum of five sort fields may be supplied.

The same field cannot be included more than once.

Only fields marked as sortable in the field tables can be used.

If no sorting is supplied, results are sorted by createdDate:desc.

Pagination

Pagination is page-based.

ShellGET /API/external/shipments/list.php?page=2&limit=25

Filtering and sorting are applied before pagination.

If there are more pages, the top-level attribute "hasNextPage" will be true

Exact total result and total page counts are not calculated by this endpoint. Clients can request successive pages until "hasNextPage" is false or a page contains fewer shipments than the requested limit.

Request limits

Some string fields have smaller limits, as shown in the field tables.

Requests must also fit within normal HTTP URL length limits. Avoid unnecessarily large filter trees or value lists.

Invalid requests

A request may be rejected when it contains:

• An unsupported filter field.

• An operator that is not available for the selected field.

• An invalid date, integer, decimal, or boolean value.

• An empty logical group.

• An invalid combination of and and or.

• Too many filter conditions or nested groups.

• An unsupported or repeated sort field.

• An invalid page or limit value.

• More than 50 values in an in or notIn filter.

Invalid filtering, sorting, or pagination normally produces a 400 Bad Request response. Authentication failures are handled as described in the Authentication section.

Debug mode

Including the request parameter debug with a value of true will return the parsed filter as JSON. This can be useful for checking that the URL filtering is formatted correctly.

ShellGET /API/external/shipments/list.php?debug=true

For the example filter:

ShellGET API/external/shipments/list.php?filter[or][0][currentStatus][eq]=Acknowledged&filter[or][1][currentStatus][eq]=In%20Transit&page=1&limit=100&debug=true

The top-level JSON attribute "filters" is:

JavaScript"filters": {
        "or": [
            {
                "currentStatus": {
                    "eq": "Acknowledged"
                }
            },
            {
                "currentStatus": {
                    "eq": "In Transit"
                }
            }
        ]
    }

Further examples

Shipments due during August 2026

ShellGET /API/external/shipments/list.php?filter[deliveryDate][gte]=2026-08-01&filter[deliveryDate][lte]=2026-08-31

Shipments with one of several current statuses

ShellGET /API/external/shipments/list.php?filter[currentStatus][in][]=Acknowledged&filter[currentStatus][in][]=In%20Transit

Exclude invoiced and cancelled shipments

ShellGET /API/external/shipments/list.php?filter[currentStatus][notIn][]=Invoiced&filter[currentStatus][notIn][]=Cancelled

Search by the beginning of a reference

ShellGET /API/external/shipments/list.php?filter[reference][startsWith]=0075

Search by customer and delivery date

ShellGET /API/external/shipments/list.php?filter[customerID][eq]=TESTCUSTOMER&filter[deliveryDate][gte]=2026-08-07

Find shipments without a pickup date

ShellGET /API/external/shipments/list.php?filter[pickupDate][isNull]=true

Search the complete status history

ShellGET /API/external/shipments/list.php?filter[statusHistory][contains]=in%20transit

Exclude shipments that have ever been invoiced

ShellGET /API/external/shipments/list.php?filter[statusHistory][notContains]=Invoiced

Apply an OR condition

ShellGET /API/external/shipments/list.php?filter[or][0][currentStatus][eq]=Acknowledged&filter[or][1][currentStatus][eq]=In%20Transit

Apply a nested condition

ShellGET /API/external/shipments/list.php?filter[or][0][and][0][deliveryDate][gte]=2026-08-07&filter[or][0][and][1][deliveryDate][lte]=2026-08-31&filter[or][1][and][0][currentStatus][eq]=Invoiced&filter[or][1][and][1][totalVolume][gt]=0

Sort and paginate results

JavaScriptGET /API/external/shipments/list.php?page=2&limit=25&sort[]=deliveryDate:asc&sort[]=createdDate:desc

Update a shipment

NOT YET AVAILABLE

Documentation pending

Updates permitted fields on an existing shipment.

Provisional endpoint:

Shell/API/external/shipments/update.php

Update shipment status

EXTREMELY LIMITED AVAILABILITY

Documentation pending

Records a status update against an existing shipment.

Provisional endpoint:

Shell/API/external/shipments/update-status.php