Skip to main content

Shipments Guide

This guide will walk you through the process of creating, managing, and generating labels for your shipments using the Shipping Channels API.

1. Creating a Shipment​

To create a shipment, you need to send a POST request to the /v1/shipments endpoint with the necessary details in the request body. A shipment requires information about the shipping channel, sender and recipient contacts, origin and destination addresses, and parcel details.

Example Request Body:

{
  "shipping_channel_id": "ch_123456",
  "reference_number": "ORD-2025-001",
  "shipping_date": "2025-08-15",
  "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",
    "city_name": "New York",
    "postal_code": "10001",
    "country_code": "US"
  },
  "destination_address": {
    "street_name": "Oak Ave",
    "house_number": "456",
    "city_name": "Los Angeles",
    "postal_code": "90001",
    "country_code": "US"
  },
  "parcel": {
    "parcel_type": "package",
    "length_dimension": 10,
    "width_dimension": 10,
    "height_dimension": 10,
    "dimension_unit": "CM",
    "weight_amount": 1.5,
    "weight_unit": "KG",
    "label_format": "PDF"
  }
}

For a full list of available parameters and their descriptions, please refer to the Create Shipment API Reference.

2. Retrieving Shipments​

You can retrieve a list of all your shipments or a specific shipment by its ID.

List All Shipments​

To get a paginated list of your shipments, send a GET request to /v1/shipments.

Example Request:

curl -X GET \
  https://api.shipping-channels.com/v1/shipments \
  -H "Authorization: Bearer YOUR_API_KEY"

For more details, see the List Shipments API Reference.

Retrieve a Specific Shipment​

To retrieve a single shipment, send a GET request to /v1/shipments/{id}.

Example Request:

curl -X GET \
  https://api.shipping-channels.com/v1/shipments/sh_123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

For more details, see the Get Shipment API Reference.

3. Updating a Shipment​

You can update certain fields of an existing shipment by sending a PUT or PATCH request to /v1/shipments/{id}. Currently, only reference_number and metadata can be updated.

Example Request Body:

{
  "reference_number": "UPDATED-ORD-2025-001",
  "metadata": {
    "customer_notes": "Fragile items, handle with care."
  }
}

For more details, see the Update Shipment API Reference.

4. Deleting a Shipment​

Shipments can only be deleted if they have not been successfully created with the shipping provider. To delete a shipment, send a DELETE request to /v1/shipments/{id}.

Example Request:

curl -X DELETE \
  https://api.shipping-channels.com/v1/shipments/sh_123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

For more details, see the Delete Shipment API Reference.

5. Downloading Labels​

Shipping labels are automatically generated upon successful shipment creation. To download the label, send a GET request to /v1/shipments/{id}/label. This endpoint will redirect you to the label file.

Example Request:

curl -L -X GET \
  https://api.shipping-channels.com/v1/shipments/sh_123456/label \
  -H "Authorization: Bearer YOUR_API_KEY"

For more details, see the Download Shipment Label API Reference.

6. Getting Available Shipping Channels and Statuses​

Get Available Shipping Channels​

To retrieve a list of active shipping channels available for creating shipments, send a GET request to /v1/shipments/shipping-channels.

Example Request:

curl -X GET \
  https://api.shipping-channels.com/v1/shipments/shipping-channels \
  -H "Authorization: Bearer YOUR_API_KEY"

For more details, see the Get Available Shipping Channels API Reference.

Get Shipment Statuses​

To retrieve a list of all possible shipment statuses, send a GET request to /v1/shipments/statuses.

Example Request:

curl -X GET \
  https://api.shipping-channels.com/v1/shipments/statuses \
  -H "Authorization: Bearer YOUR_API_KEY"

For more details, see the Get Shipment Statuses API Reference.