Skip to main content
POST
/
graphql#ListShipments
List shipments
curl --request POST \
  --url 'https://clarus-api.com/graphql#ListShipments' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '
{
  "query": "query($filter: ShipmentFilterType) { shipments { all(filter: $filter) { edges { node { id reference name status delivery_notes collection_datetime label_filename packages_count carrier { id code name } carrier_service { id code name } warehouse { id code name } } } } } }"
}
'
{
  "data": {
    "shipments": {
      "all": {
        "edges": [
          {
            "node": {
              "id": "1",
              "reference": "SH-001",
              "name": "Shipment to Customer A",
              "status": "dispatched",
              "delivery_notes": null,
              "collection_datetime": "2026-03-10T14:00:00Z",
              "label_filename": "label-SH-001.pdf",
              "packages_count": 2,
              "carrier": {
                "id": "1",
                "code": "DPD",
                "name": "DPD"
              },
              "carrier_service": {
                "id": "1",
                "code": "NEXT",
                "name": "Next Day"
              },
              "warehouse": {
                "id": "1",
                "code": "WH1",
                "name": "Main Warehouse"
              }
            }
          }
        ]
      }
    }
  }
}

​
Query Structure

query($filter: ShipmentFilterType) {
  shipments {
    all(filter: $filter) {
      edges {
        node {
          id
          reference
          name
          status
          delivery_notes
          collection_datetime
          label_filename
          packages_count
          carrier {
            id
            code
            name
          }
          carrier_service {
            id
            code
            name
          }
          warehouse {
            id
            code
            name
          }
        }
      }
    }
  }
}

​
Filter Argument

All filters are passed inside the filter argument. Each filter field accepts an input object with operators: 
{
  "filter": {
    "status": {
      "eq": "dispatched"
    }
  }
}

​
Available Filters

FilterInput TypeOperatorsDescription
referenceStringInputTypeeq, ilike, like, in, betweenShipment reference
statusStringInputTypeeq, ilike, like, in, betweenShipment status
carrier_idIdInputTypeeq, gt, gteq, lt, lteq, in, filledFilter by carrier ID
warehouse_idIdInputTypeeq, gt, gteq, lt, lteq, in, filledFilter by warehouse ID
goods_out_idIdInputTypeeq, gt, gteq, lt, lteq, in, filledFilter by goods out order ID

​
Filter Operators

Input TypeOperators
StringInputTypeeq (exact), ilike (case-insensitive partial), like (case-sensitive partial), in (array match), between (range)
IntegerInputTypeeq, gt, gteq, lt, lteq, between
DatetimeInputTypeeq, from, to, between
BooleanInputTypeeq (required)
IdInputTypeeq, gt, gteq, lt, lteq, in, filled
More fields and filters available via GraphQL introspection.

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.

​
X-Clarus-Subdomain
string
header
required

The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.

Body

application/json
​
query
string<textarea>
required

GraphQL query string

Example:

"query($filter: ShipmentFilterType) { shipments { all(filter: $filter) { edges { node { id reference name status delivery_notes collection_datetime label_filename packages_count carrier { id code name } carrier_service { id code name } warehouse { id code name } } } } } }"

​
variables
object

Query variables including the filter object

Example:
{
  "filter": { "status": { "eq": "dispatched" } }
}

Response

Successful GraphQL response

​
data
object

Query result data

​
errors
object[]

GraphQL errors, if any