Shipments

List Shipments

Searches your Shipments and returns key information for each match, including its latest event. Use Retrieve Shipment Details for the full record of a single Shipment.

A date range is required: provide exactly one of the pairs created_date_*, updated_date_*, or latest_event_date_* — both ends together, _from ≤ _to, and _from at most 13 months in the past (the data retention window). Format yyyy-mm-ddThh:mm:ss, processed as UTC.

AND/OR filters: parameters marked AND/OR accept bracket syntax — field=['a','b'] matches both (AND), field=[['a','b']] matches either (OR), field=['x',['a','b']] mixes them. String values must be quoted; URL-encode the brackets and quotes if your client requires it.

Pagination: cursor-based. limit is 25–100 (default 25). Pass the next_page value from each response into the next request; the first page is next_page=0. You have reached the last page when the response no longer returns a next_page value.

No match: a valid search with zero results returns HTTP 404 with api_response 4041 — not an empty array.

GET

shipment

list

List Shipments

curl --request GET \
  --url https://api.perform.ai/v5/shipment/list/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.perform.ai/v5/shipment/list/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.perform.ai/v5/shipment/list/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.perform.ai/v5/shipment/list/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.perform.ai/v5/shipment/list/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "api_response": "200",
  "total_result": 2,
  "next_page": 510603416,
  "data": [
    {
      "shipment_uuid": "5b8ed503-20d2-46cf-8675-ce77a059f691",
      "shipment_id": "SHP-2026-000002",
      "tracking_number": "00340434616780000001",
      "carrier": "DHL eCommerce",
      "status": "active",
      "current_phase": {
        "name": "Out for delivery",
        "key": "G"
      },
      "created_date": "2026-09-19T03:26:29+00:00",
      "updated_date": "2026-09-19T05:12:04+00:00",
      "order": {
        "order_uuid": "a0144751-6530-4135-8d73-f258a28ba27d",
        "order_id": "ORD-2026-000114"
      },
      "latest_event": {
        "event": "Out for delivery",
        "date_time": "2026-09-19T11:10:00+08:00",
        "timezone": "Asia/Singapore",
        "location": {
          "place": "Singapore"
        }
      }
    }
  ]
}

{
  "api_response": "4030",
  "message": "validation_error",
  "errors": {
    "created_date_from": [
      "created_date or updated_date range is required."
    ],
    "created_date_to": [
      "created_date or updated_date range is required."
    ]
  }
}

{
  "api_response": 403,
  "message": "Key not authorized"
}

{
  "api_response": "4041",
  "message": "No results found with the provided search parameters"
}

{
  "api_response": 429,
  "message": "Throttled"
}

{
  "api_response": "500",
  "message": "System error"
}

Authorizations

Authorization

string

header

required

Used by every functional endpoint. Generate the token with POST /auth/oauth/token/ and send it as Authorization: Bearer {token}.

Query Parameters

created_date_from

string

Start of the created-date range. Pair with created_date_to.

created_date_to

string

End of the created-date range.

updated_date_from

string

Start of the updated-date range. Pair with updated_date_to.

updated_date_to

string

End of the updated-date range.

latest_event_date_from

string

Start of the latest-event-date range. Pair with latest_event_date_to.

latest_event_date_to

string

End of the latest-event-date range.

tracking_number

string

Tracking number. Max 75 chars per entry. AND/OR.

shipment_reference

string

Shipment reference. Max 75 chars per entry. AND/OR.

additional_reference

string

Additional reference. Max 75 chars per entry. AND/OR.

order_uuid

string

Order UUID of the associated order. AND/OR.

order_id

string

Order ID of the associated order. Max 75 chars per entry. AND/OR.

order_reference

string

Order reference of the associated order. Max 75 chars per entry. AND/OR.

carrier_id

string

Perform.AI 6-character carrier ID. Exactly 6 characters. AND/OR.

carrier_reference

string

Configured carrier reference. Max 75 chars per entry. AND/OR.

status

enum<string>

Shipment status. AND/OR.

Available options:

pending,

expired,

active,

inactive,

delivered,

return

current_phase

string

Current delivery phase, using standard phase keys. AND/OR.

Response

Matching Shipments.

api_response

string

total_result

integer

Total number of Shipments matching the search.

next_page

integer

Cursor for the next page. Absent on the last page.

data

object[]

Show child attributes

List Shipments

curl --request GET \
  --url https://api.perform.ai/v5/shipment/list/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.perform.ai/v5/shipment/list/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.perform.ai/v5/shipment/list/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.perform.ai/v5/shipment/list/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.perform.ai/v5/shipment/list/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "api_response": "200",
  "total_result": 2,
  "next_page": 510603416,
  "data": [
    {
      "shipment_uuid": "5b8ed503-20d2-46cf-8675-ce77a059f691",
      "shipment_id": "SHP-2026-000002",
      "tracking_number": "00340434616780000001",
      "carrier": "DHL eCommerce",
      "status": "active",
      "current_phase": {
        "name": "Out for delivery",
        "key": "G"
      },
      "created_date": "2026-09-19T03:26:29+00:00",
      "updated_date": "2026-09-19T05:12:04+00:00",
      "order": {
        "order_uuid": "a0144751-6530-4135-8d73-f258a28ba27d",
        "order_id": "ORD-2026-000114"
      },
      "latest_event": {
        "event": "Out for delivery",
        "date_time": "2026-09-19T11:10:00+08:00",
        "timezone": "Asia/Singapore",
        "location": {
          "place": "Singapore"
        }
      }
    }
  ]
}

{
  "api_response": "4030",
  "message": "validation_error",
  "errors": {
    "created_date_from": [
      "created_date or updated_date range is required."
    ],
    "created_date_to": [
      "created_date or updated_date range is required."
    ]
  }
}

{
  "api_response": 403,
  "message": "Key not authorized"
}

{
  "api_response": "4041",
  "message": "No results found with the provided search parameters"
}

{
  "api_response": 429,
  "message": "Throttled"
}

{
  "api_response": "500",
  "message": "System error"
}

Overview

Authentication

Shipments

Booking

Documents

PUDO locations

Carrier configurations

Events

Returns

Webhooks

Checkout

List Shipments

Authorizations

Query Parameters

Response