Get Shipment

Retrieves a specific shipment by ID.

Endpoint

GET /v1/shipments/{id}

Authentication

API key required. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Description
id	string	The ID of the shipment to retrieve.

Response

200 OK

Parameter	Type	Description
id	string	The ID of the shipment.
reference_number	string	Your internal reference number for this shipment.
shipping_channel_id	string	The ID of the shipping channel used for this shipment.
provider_shipment_id	string	The remote provider's tracking number.
status	string	The current status of the shipment.
total_price	number	The total price of the shipment.
currency	string	The currency of the total price.
shipping_date	string	The date the shipment is expected to be shipped.
origin_pickup_point_id	string	ID of the origin pickup point.
destination_pickup_point_id	string	ID of the destination pickup point.
additional_services	array	Array of additional services for the shipment.
metadata	object	Arbitrary metadata for the shipment.
sender_contact	object	The sender's contact information.
recipient_contact	object	The recipient's contact information.
origin_address	object	The origin address of the shipment.
destination_address	object	The destination address of the shipment.
return_address	object	The return address of the shipment.
parcel	object	The parcel details.
customs_declaration	object	The customs declaration for international shipments.
tracking_parcel	object	The tracking parcel associated with the shipment.
created_at	string	The timestamp when the shipment was created.
updated_at	string	The timestamp when the shipment was last updated.

{
  "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",
    "shipping_date": "2025-08-15",
    "origin_pickup_point_id": null,
    "destination_pickup_point_id": null,
    "additional_services": [],
    "metadata": {},
    "sender_contact": {
      "id": "sc_123",
      "company_name": "Sender Co.",
      "first_name": "John",
      "last_name": "Doe",
      "email_address": "john.doe@example.com",
      "phone_number": "+1234567890"
    },
    "recipient_contact": {
      "id": "rc_123",
      "company_name": "Recipient Co.",
      "first_name": "Jane",
      "last_name": "Smith",
      "email_address": "jane.smith@example.com",
      "phone_number": "+1987654321"
    },
    "origin_address": {
      "id": "oa_123",
      "street_name": "Main St",
      "house_number": "123",
      "apartment_number": null,
      "city_name": "New York",
      "postal_code": "10001",
      "country_code": "US"
    },
    "destination_address": {
      "id": "da_123",
      "street_name": "Oak Ave",
      "house_number": "456",
      "apartment_number": null,
      "city_name": "Los Angeles",
      "postal_code": "90001",
      "country_code": "US"
    },
    "return_address": null,
    "parcel": {
      "id": "p_123",
      "parcel_type": "package",
      "reference_number": null,
      "length_dimension": 10,
      "width_dimension": 10,
      "height_dimension": 10,
      "dimension_unit": "CM",
      "weight_amount": 1.5,
      "weight_unit": "KG",
      "label_comment": null,
      "label_format": "PDF",
      "cash_on_delivery_amount": null,
      "cash_on_delivery_currency": null,
      "insurance_amount": null,
      "insurance_currency": null,
      "contains_documents_only": false,
      "metadata": {}
    },
    "customs_declaration": null,
    "tracking_parcel": {
      "id": "tp_123",
      "tracking_number": "TRK123456789",
      "status": "created"
    },
    "created_at": "2025-08-10T10:00:00Z",
    "updated_at": "2025-08-10T10:05:00Z"
  }
}

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
403	Forbidden - You don't have permission to access this shipment
404	Not Found - The specified shipment could not be found
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/sh_123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP

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

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

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

JavaScript

fetch('https://api.shipping-channels.com/v1/shipments/sh_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));