Skip to main content

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​

ParameterTypeDescription
idstringThe ID of the shipment to retrieve.

Response​

200 OK​

ParameterTypeDescription
idstringThe ID of the shipment.
reference_numberstringYour internal reference number for this shipment.
shipping_channel_idstringThe ID of the shipping channel used for this shipment.
provider_shipment_idstringThe remote provider's shipment ID.
statusstringThe current status of the shipment.
status_colorstringColor code for the status (for UI display).
is_successfulbooleanWhether the shipment was successfully created with the provider.
can_generate_labelbooleanWhether a label can be generated for this shipment.
has_labelbooleanWhether a label is available for download.
is_internationalbooleanWhether this is an international shipment.
shipping_datestringThe date the shipment is expected to be shipped.
estimated_delivery_datestringEstimated delivery date (when available).
origin_pickup_point_idstringID of the origin pickup point.
destination_pickup_point_idstringID of the destination pickup point.
additional_servicesarrayArray of additional services for the shipment.
metadataobjectArbitrary metadata for the shipment.
labelobjectLabel information (when available).
label_commentstringComment printed on the label.
contains_documents_onlybooleanWhether shipment contains only documents.
shipping_channelobjectThe shipping channel information.
sender_contactobjectThe sender's contact information.
recipient_contactobjectThe recipient's contact information.
origin_addressobjectThe origin address of the shipment.
destination_addressobjectThe destination address of the shipment.
return_addressobjectThe return address of the shipment.
parcelsarrayArray of parcel objects with tracking information.
total_parcels_countintegerTotal number of parcels in the shipment.
cash_on_deliveryobjectCOD information (when applicable).
insuranceobjectInsurance information (when applicable).
customs_declarationobjectThe customs declaration for international shipments.

Response Example​

{
  "data": {
    "id": "sh_123456",
    "reference_number": "ORD-2025-001",
    "shipping_channel_id": "ch_123456",
    "provider_shipment_id": "20655836776",
    "status": "pending",
    "status_color": "yellow",
    "is_successful": true,
    "can_generate_label": false,
    "has_label": true,
    "is_international": false,
    "shipping_date": "2025-08-15",
    "estimated_delivery_date": "2025-08-17",
    "origin_pickup_point_id": null,
    "destination_pickup_point_id": null,
    "additional_services": [],
    "metadata": {},
    "label": {
      "format": "pdf",
      "url": "/v1/shipments/sh_123456/label",
      "has_label": true
    },
    "label_comment": null,
    "contains_documents_only": false,
    "shipping_channel": {
      "id": "ch_123456",
      "name": "PPL CZ",
      "provider": "ppl"
    },
    "sender_contact": {
      "company_name": "Sender Co.",
      "first_name": "John",
      "last_name": "Doe",
      "email_address": "john.doe@example.com",
      "phone_number": "+1234567890"
    },
    "recipient_contact": {
      "company_name": "Recipient Co.",
      "first_name": "Jane",
      "last_name": "Smith",
      "email_address": "jane.smith@example.com",
      "phone_number": "+1987654321"
    },
    "origin_address": {
      "street_name": "Main St",
      "house_number": "123",
      "apartment_number": null,
      "city_name": "New York",
      "postal_code": "10001",
      "country_code": "US",
      "province": null
    },
    "destination_address": {
      "street_name": "Oak Ave",
      "house_number": "456",
      "apartment_number": null,
      "city_name": "Los Angeles",
      "postal_code": "90001",
      "country_code": "US",
      "province": null
    },
    "return_address": null,
    "parcels": [
      {
        "id": "prc_001",
        "parcel_number": 1,
        "status": "pending",
        "status_color": "yellow",
        "provider_parcel_id": "20655836776",
        "provider_tracking_number": "20655836776",
        "parcel_type": "package",
        "reference_number": "PARCEL-001",
        "dimensions": {
          "length": 30,
          "width": 20,
          "height": 15,
          "unit": "CM",
          "formatted": "30x20x15 CM"
        },
        "weight": {
          "amount": 2.5,
          "unit": "KG",
          "formatted": "2.5 KG"
        },
        "tracking_parcel": {
          "id": "trk_001",
          "tracking_number": "20655836776",
          "status": "pending",
          "status_color": "yellow",
          "last_status_update": "2025-08-15T14:30:00Z"
        },
        "parcel_specific_comment": null,
        "metadata": {},
        "error_message": null
      },
      {
        "id": "prc_002",
        "parcel_number": 2,
        "status": "pending",
        "status_color": "yellow",
        "provider_parcel_id": "20655836777",
        "provider_tracking_number": "20655836777",
        "parcel_type": "package",
        "reference_number": "PARCEL-002",
        "dimensions": {
          "length": 40,
          "width": 30,
          "height": 20,
          "unit": "CM",
          "formatted": "40x30x20 CM"
        },
        "weight": {
          "amount": 5.0,
          "unit": "KG",
          "formatted": "5.0 KG"
        },
        "tracking_parcel": {
          "id": "trk_002",
          "tracking_number": "20655836777",
          "status": "pending",
          "status_color": "yellow",
          "last_status_update": "2025-08-15T14:30:00Z"
        },
        "parcel_specific_comment": null,
        "metadata": {},
        "error_message": null
      }
    ],
    "total_parcels_count": 2,
    "cash_on_delivery": {
      "amount": 150.00,
      "currency": "CZK"
    },
    "insurance": null,
    "customs_declaration": null
  }
}

Parcel Object​

Each parcel in the parcels array contains:

FieldTypeDescription
idstringUnique parcel ID.
parcel_numberintegerSequential number within the shipment (1, 2, 3...).
statusstringCurrent status of the parcel.
status_colorstringColor code for UI display.
provider_parcel_idstringProvider's unique ID for this parcel.
provider_tracking_numberstringTracking number for this parcel.
parcel_typestringType of parcel (package, document, etc.).
reference_numberstringYour reference number for this parcel.
dimensionsobjectParcel dimensions with formatted string.
weightobjectParcel weight with formatted string.
tracking_parcelobjectTracking information for this parcel.
parcel_specific_commentstringComment specific to this parcel.
metadataobjectArbitrary metadata for the parcel.
error_messagestringError message if parcel creation failed.

Error Responses​

Status CodeDescription
401Unauthorized - Invalid or missing API key
403Forbidden - You don't have permission to access this shipment
404Not Found - The specified shipment could not be found
429Too Many Requests - Rate limit exceeded
500Server 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);

// Access parcels
foreach ($data['data']['parcels'] as $parcel) {
    echo "Parcel #{$parcel['parcel_number']}: {$parcel['provider_tracking_number']}\n";
}

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('Shipment:', data.data.id);
  console.log('Total parcels:', data.data.total_parcels_count);

  // Access each parcel's tracking number
  data.data.parcels.forEach(parcel => {
    console.log(`Parcel #${parcel.parcel_number}: ${parcel.provider_tracking_number}`);
  });
})
.catch(error => console.error('Error:', error));