Skip to content

List shipments

GET
/shipments
curl --request GET \
--url 'https://api.connectato.com/v1/shipments?sort=created_at' \
--header 'Authorization: Bearer <token>'

Scope: read_shipments.

Newest first by default, filtered and sorted like the Shipments page.

limit
integer
>= 1 <= 200

Items per page. Default: 50.

cursor
string

The previous page’s next_cursor, with the same filter, sort and updated_since.

sort
string
Allowed values: created_at awb cod updated_at -created_at -awb -cod -updated_at

The order; - before a key for descending. Default: -created_at.

updated_since
string format: date-time

Only what changed at or after this moment (RFC 3339), read in sort=updated_at.

filter[status]
Array<string>
Allowed values: pending failed needs_attention created picked_up in_transit customs_hold out_for_delivery awaiting_pickup delivery_issue delivered returning returned cancelled lost

One or more codes, comma-separated (filter[status]=a,b), or filter[status][is_not]=a,b for the others.

filter[integration]
Array<string>

One or more public ids (int_...), comma-separated (filter[integration]=a,b), or filter[integration][is_not]=a,b for the others.

filter[carrier]
Array<string>

One or more of the organization’s own codes, comma-separated (filter[carrier]=a,b), or filter[carrier][is_not]=a,b for the others.

filter[delivery_method]
Array<string>
Allowed values: address pickup_point

One or more codes, comma-separated (filter[delivery_method]=a,b), or filter[delivery_method][is_not]=a,b for the others.

filter[cod]
string

A span: filter[cod][min]= and/or filter[cod][max]=; [is_not] for outside.

filter[created_at]
string

Whole days in the organization’s zone: a period (today, last_7_days, last_30_days, last_90_days, last_12_months) or filter[created_at][from]=Y-m-d&filter[created_at][to]=Y-m-d; [is_not] for outside.

A page of the list.

Media typeapplication/json
object
data
required
Array<object>
ShipmentResource
object
id
required

The shipment’s public id (shp_...).

string
/^shp_[0-9a-z]{26}$/
order_id
required

The order it ships (ord_...); null once the order was deleted.

string | null
/^ord_[0-9a-z]{26}$/
direction
required

Outbound (to the buyer) or return (back to the merchant). New values may appear: treat one you do not know as such.

string
status
required

Pending, failed, needs_attention, created, picked_up, in_transit, customs_hold, out_for_delivery, awaiting_pickup, delivery_issue, delivered, returning, returned, cancelled, lost. New values may appear: treat one you do not know as such.

string
vendor
required

The vendor code of the integration the AWB was made through (woot, sameday, fancourier, …); kept when the account is removed.

string
integration_id
required

The courier account (an installed integration, int_...); null once it was removed.

string | null
/^int_[0-9a-z]{26}$/
carrier
required

Who physically transports the parcel (dpd, sameday, fancourier, …); null until known.

string | null
service_code
required

The courier’s service code the AWB was asked with.

string | null
awb
required

The carrier’s tracking number; null until the courier issues it. Not unique across couriers.

string | null
label_available
required

Whether the label can be printed in the app now; the label file is not served by API v1.

boolean
error_code
required

Why it is failed or needs_attention, a stable code: account_unavailable, not_supported, credentials_rejected, rate_limited, invalid_data, vendor_rejected, not_sent, outcome_unknown. Null in any other status. New codes may appear. New values may appear: treat one you do not know as such.

string | null
error_message
required

The code’s meaning, in English; the app shows the merchant the full reason in their language.

string | null
vendor_message
required

The courier’s own words when it answered (vendor_rejected), as it sent them, in its language: for display only, never to parse.

string | null
delivery_method
required

Address (the recipient’s door) or pickup_point (a locker, office or partner point); an order’s delivery.method in the same codes. New values may appear: treat one you do not know as such.

string
pickup_point
required

The point it is delivered to, for a pickup_point delivery; null otherwise.

object
external_id
required

The point’s id in the courier’s ids.

string | null
total_weight_kg
required
string | null
parcels
required

Every parcel of the shipment, in order (as many as the courier was asked for).

Array<object>
object
kind
required

Parcel, envelope or pallet. New values may appear: treat one you do not know as such.

string
weight_kg
required
string | null
length_cm
required
string | null
width_cm
required
string | null
height_cm
required
string | null
tracking_number
required

The parcel’s own tracking number, where the courier issues one per parcel.

string | null
cod
required

Cash on delivery the courier collects from the recipient; null without.

object
amount
required
string
currency
required
string
declared_value
required

The declared (insured) value; null when none was declared.

object
amount
required
string
currency
required
string
sender
required

The v1 address shape (first_name, last_name, locality_code and the like null where the AWB holds none) plus the person to ask for at a company.

object
name
required
string | null
first_name
required
string | null
last_name
required
string | null
company
required
string | null
email
required
string | null
phone
required
string | null
address_line_1
required
string | null
address_line_2
required
string | null
city
required
string | null
region
required
string | null
region_code
required
string | null
postal_code
required
string | null
country_code
required
string | null
locality_code
required
string | null
contact_person
required
string | null
recipient
required
object
name
required
string | null
first_name
required
string | null
last_name
required
string | null
company
required
string | null
email
required
string | null
phone
required
string | null
address_line_1
required
string | null
address_line_2
required
string | null
city
required
string | null
region
required
string | null
region_code
required
string | null
postal_code
required
string | null
country_code
required
string | null
locality_code
required
string | null
contact_person
required
string | null
cancellation
required

Carrier: cancelled at the courier (asked by the platform, or reported by its tracking); local: cancelled in the platform only (a courier without a cancel API, or a shipment set aside without an AWB).

object
kind
required

New values may appear: treat one you do not know as such.

string
cancelled_at
required
string | null format: date-time
tracking_events
required

The courier’s latest tracking events, at most 20, newest last.

Array<object>
object
status
required

The same codes as status; null when the courier’s own status maps to none. New values may appear: treat one you do not know as such.

string | null
description
required

The event as the courier worded it, untranslated.

string | null
location
required

Where it happened, as the courier reported it.

string | null
occurred_at
required
string format: date-time
picked_up_at
required
string | null format: date-time
delivered_at
required
string | null format: date-time
returned_at
required
string | null format: date-time
created_at
required

When the AWB was asked for.

string format: date-time
updated_at
required
string format: date-time
next_cursor
required

The next page’s cursor; null on the last page.

string | null

Example generated

{
"data": [
{
"id": "example",
"order_id": "example",
"direction": "example",
"status": "example",
"vendor": "example",
"integration_id": "example",
"carrier": "example",
"service_code": "example",
"awb": "example",
"label_available": true,
"error_code": "example",
"error_message": "example",
"vendor_message": "example",
"delivery_method": "example",
"pickup_point": {
"external_id": "example"
},
"total_weight_kg": "example",
"parcels": [
{
"kind": "example",
"weight_kg": "example",
"length_cm": "example",
"width_cm": "example",
"height_cm": "example",
"tracking_number": "example"
}
],
"cod": {
"amount": "example",
"currency": "example"
},
"declared_value": {
"amount": "example",
"currency": "example"
},
"sender": {
"name": "example",
"first_name": "example",
"last_name": "example",
"company": "example",
"email": "example",
"phone": "example",
"address_line_1": "example",
"address_line_2": "example",
"city": "example",
"region": "example",
"region_code": "example",
"postal_code": "example",
"country_code": "example",
"locality_code": "example",
"contact_person": "example"
},
"recipient": {
"name": "example",
"first_name": "example",
"last_name": "example",
"company": "example",
"email": "example",
"phone": "example",
"address_line_1": "example",
"address_line_2": "example",
"city": "example",
"region": "example",
"region_code": "example",
"postal_code": "example",
"country_code": "example",
"locality_code": "example",
"contact_person": "example"
},
"cancellation": {
"kind": "example",
"cancelled_at": "2026-04-15T12:00:00Z"
},
"tracking_events": [
{
"status": "example",
"description": "example",
"location": "example",
"occurred_at": "2026-04-15T12:00:00Z"
}
],
"picked_up_at": "2026-04-15T12:00:00Z",
"delivered_at": "2026-04-15T12:00:00Z",
"returned_at": "2026-04-15T12:00:00Z",
"created_at": "2026-04-15T12:00:00Z",
"updated_at": "2026-04-15T12:00:00Z"
}
],
"next_cursor": "example"
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

No valid access token.

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

WWW-Authenticate
string

Bearer: send an access token as a Bearer token.

The app was not granted the scope (insufficient_scope).

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

Validation failed (validation_failed, errors per field): an unknown filter, value or sort, a limit out of range, a malformed updated_since, or a cursor of another query.

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

Too many requests: retry after Retry-After seconds.

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

Retry-After
integer

Seconds to wait before retrying.