List Shipments

Retrieves a paginated list of shipments for the authenticated user.

Endpoint

GET /v1/shipments

Authentication

API key required. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Description
page	integer	Page number for pagination. Default is 1.
per_page	integer	Number of items per page. Default is 20. Maximum is 100.
status	string	Filter by status. Possible values: pending, created, shipped, delivered, cancelled, returned.
shipping_channel_id	string	Filter by shipping channel ID.
search	string	Search by reference number or provider shipment ID.

Response

200 OK

{
  "data": [
    {
      "id": "sh_123456",
      "reference_number": "ORD-2025-001",
      "shipping_channel_id": "ch_123456",
      "provider_shipment_id": "DHL-ABC-123",
      "status": "created",
      "total_price": 15.50,
      "currency": "USD",
      "created_at": "2025-08-10T10:00:00Z",
      "updated_at": "2025-08-10T10:05:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.shipping-channels.com/v1/shipments",
    "per_page": 20,
    "to": 1,
    "total": 1
  },
  "links": {
    "first": "https://api.shipping-channels.com/v1/shipments?page=1",
    "last": "https://api.shipping-channels.com/v1/shipments?page=1",
    "next": null,
    "prev": null
  }
}

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end

Example Request

cURL

curl -X GET \
  "https://api.shipping-channels.com/v1/shipments?status=created&shipping_channel_id=ch_123456" \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP

<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.shipping-channels.com/v1/shipments', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
    'query' => [
        'status' => 'created',
        'shipping_channel_id' => 'ch_123456',
    ],
]);

$data = json_decode($response->getBody(), true);

JavaScript

fetch('https://api.shipping-channels.com/v1/shipments?status=created&shipping_channel_id=ch_123456', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Filtering Examples

Filter by Status

GET /v1/shipments?status=delivered

Filter by Shipping Channel

GET /v1/shipments?shipping_channel_id=ch_123456

Search by Reference Number

GET /v1/shipments?search=ORD-2025