Create Shipment

Creates a new shipment with one or more parcels.

Endpoint

POST /v1/shipments

Authentication

API key required. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Body

Parameter	Type	Required	Description
`shipping_channel_id`	string	Yes	The ID of the shipping channel to use for this shipment.
`reference_number`	string	No	Your internal reference number for this shipment.
`shipping_date`	string (date)	No	The date the shipment is expected to be shipped (YYYY-MM-DD). Must be today or in the future.
`label_format`	string	Yes	Desired label format: `pdf` or `zpl`.
`label_comment`	string	No	Comment to be printed on the label (max 1000 chars).
`contains_documents_only`	boolean	No	Set to `true` if the shipment contains only documents.
`cash_on_delivery_amount`	number	No	Amount for Cash on Delivery.
`cash_on_delivery_currency`	string	No	Currency for Cash on Delivery (3-letter ISO code).
`insurance_amount`	number	No	Amount for insurance.
`insurance_currency`	string	No	Currency for insurance (3-letter ISO code).
`origin_pickup_point_id`	string	No	ID of the origin pickup point (if applicable).
`destination_pickup_point_id`	string	No	ID of the destination pickup point (if applicable).
`additional_services`	array	No	Array of additional services for the shipment.
`metadata`	object	No	Arbitrary metadata for the shipment.
`enable_tracking`	boolean	No	Whether to enable tracking for the shipment. Defaults to `true`.

`sender_contact` Object (Required)

Parameter	Type	Required	Description
`company_name`	string	No	Company name of the sender.
`first_name`	string	Conditional	First name of the sender. Required if `company_name` is not provided.
`last_name`	string	Conditional	Last name of the sender. Required if `company_name` is not provided.
`email_address`	string	Yes	Email address of the sender.
`phone_number`	string	Yes	Phone number of the sender.

`recipient_contact` Object (Required)

Parameter	Type	Required	Description
`company_name`	string	No	Company name of the recipient.
`first_name`	string	Conditional	First name of the recipient. Required if `company_name` is not provided.
`last_name`	string	Conditional	Last name of the recipient. Required if `company_name` is not provided.
`email_address`	string	Yes	Email address of the recipient.
`phone_number`	string	Yes	Phone number of the recipient.

`origin_address` Object (Required)

Parameter	Type	Required	Description
`street_name`	string	Yes	Street name of the origin address.
`house_number`	string	Yes	House number of the origin address.
`apartment_number`	string	No	Apartment number of the origin address.
`city_name`	string	Yes	City name of the origin address.
`postal_code`	string	Yes	Postal code of the origin address.
`country_code`	string	Yes	2-letter ISO country code of the origin address.
`province`	string	No	Province or state of the origin address.

`destination_address` Object (Required)

Parameter	Type	Required	Description
`street_name`	string	Yes	Street name of the destination address.
`house_number`	string	Yes	House number of the destination address.
`apartment_number`	string	No	Apartment number of the destination address.
`city_name`	string	Yes	City name of the destination address.
`postal_code`	string	Yes	Postal code of the destination address.
`country_code`	string	Yes	2-letter ISO country code of the destination address.
`province`	string	No	Province or state of the destination address.

`return_address` Object (Optional)

Parameter	Type	Required	Description
`street_name`	string	Yes (if `return_address` is present)	Street name of the return address.
`house_number`	string	Yes (if `return_address` is present)	House number of the return address.
`apartment_number`	string	No	Apartment number of the return address.
`city_name`	string	Yes (if `return_address` is present)	City name of the return address.
`postal_code`	string	Yes (if `return_address` is present)	Postal code of the return address.
`country_code`	string	Yes (if `return_address` is present)	2-letter ISO country code of the return address.
`province`	string	No	Province or state of the return address.

`parcels` Array (Required)

An array of parcel objects. At least one parcel is required.

Parameter	Type	Required	Description
`parcel_type`	string	Yes	Type of parcel. E.g., `package`, `document`.
`reference_number`	string	No	Your internal reference number for the parcel (max 100 chars).
`length_dimension`	number	Yes	Length of the parcel.
`width_dimension`	number	Yes	Width of the parcel.
`height_dimension`	number	Yes	Height of the parcel.
`dimension_unit`	string	Yes	Unit of dimensions. E.g., `CM`, `IN`.
`weight_amount`	number	Yes	Weight of the parcel.
`weight_unit`	string	Yes	Unit of weight. E.g., `KG`, `LB`.
`metadata`	object	No	Arbitrary metadata for the parcel.

`customs_declaration` Object (Optional, required for international shipments)

Parameter	Type	Required	Description
`export_reason`	string	Yes (if `customs_declaration` is present)	Reason for export. E.g., `sale`, `gift`, `sample`.
`sender_tax_number`	string	No	Sender's tax identification number.
`receiver_tax_number`	string	No	Receiver's tax identification number.
`shipment_date`	string (date)	Yes (if `customs_declaration` is present)	Date of shipment for customs purposes (YYYY-MM-DD).
`trade_terms`	string	No	Incoterms. E.g., `DDP`, `DAP`.
`sender_eori_number`	string	No	Sender's EORI number.
`invoice_reference`	string	No	Invoice reference number.
`ioss_registration_number`	string	No	IOSS registration number.

`customs_declaration.items` Array (Required if `customs_declaration` is present)

Parameter	Type	Required	Description
`quantity`	integer	Yes	Quantity of the item.
`unit_value`	number	Yes	Value per unit of the item.
`unit_value_currency`	string	Yes	Currency of the unit value (3-letter ISO code).
`item_type`	string	Yes	Type of item. E.g., `product`, `document`.
`origin_country_code`	string	Yes	2-letter ISO country code of origin.
`harmonized_code`	string	Yes	Harmonized System (HS) code (8 digits).
`description`	string	Yes	Description of the item (max 64 chars).
`gross_unit_value`	number	No	Gross value per unit of the item.
`product_reference_url`	string	No	URL to product reference.
`sku`	string	No	Stock Keeping Unit.
`measurement_unit`	string	No	Unit of measurement for the item.
`net_weight_grams`	integer	No	Net weight of the item in grams.
`gross_weight_grams`	integer	No	Gross weight of the item in grams.

Example Request Body

Single Parcel Shipment

{
  "shipping_channel_id": "ch_123456",
  "reference_number": "ORD-2025-001",
  "shipping_date": "2025-08-15",
  "label_format": "pdf",
  "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"
  },
  "parcels": [
    {
      "parcel_type": "package",
      "length_dimension": 10,
      "width_dimension": 10,
      "height_dimension": 10,
      "dimension_unit": "CM",
      "weight_amount": 1.5,
      "weight_unit": "KG"
    }
  ]
}

Multi-Parcel Shipment

{
  "shipping_channel_id": "ch_123456",
  "reference_number": "ORD-2025-002",
  "shipping_date": "2025-08-15",
  "label_format": "pdf",
  "cash_on_delivery_amount": 150.00,
  "cash_on_delivery_currency": "CZK",
  "sender_contact": {
    "company_name": "Sender Co.",
    "email_address": "sender@example.com",
    "phone_number": "+420123456789"
  },
  "recipient_contact": {
    "first_name": "Jan",
    "last_name": "Novak",
    "email_address": "jan.novak@example.com",
    "phone_number": "+420987654321"
  },
  "origin_address": {
    "street_name": "Hlavni",
    "house_number": "1",
    "city_name": "Praha",
    "postal_code": "11000",
    "country_code": "CZ"
  },
  "destination_address": {
    "street_name": "Namesti",
    "house_number": "5",
    "city_name": "Brno",
    "postal_code": "60200",
    "country_code": "CZ"
  },
  "parcels": [
    {
      "parcel_type": "package",
      "reference_number": "PARCEL-001",
      "length_dimension": 30,
      "width_dimension": 20,
      "height_dimension": 15,
      "dimension_unit": "CM",
      "weight_amount": 2.5,
      "weight_unit": "KG"
    },
    {
      "parcel_type": "package",
      "reference_number": "PARCEL-002",
      "length_dimension": 40,
      "width_dimension": 30,
      "height_dimension": 20,
      "dimension_unit": "CM",
      "weight_amount": 5.0,
      "weight_unit": "KG"
    }
  ]
}

Response

201 Created

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 shipment ID/tracking number.
`status`	string	The current status of the shipment.
`is_successful`	boolean	Whether the shipment was successfully created with the provider.
`has_label`	boolean	Whether a label is available for download.
`is_international`	boolean	Whether this is an international shipment.
`total_parcels_count`	integer	Total number of parcels in the shipment.
`parcels`	array	Array of parcel objects with tracking information.
`label`	object	Label information (when available).
`cash_on_delivery`	object	COD information (when applicable).
`insurance`	object	Insurance information (when applicable).

Response Example

{
  "data": {
    "id": "sh_123456",
    "reference_number": "ORD-2025-001",
    "shipping_channel_id": "ch_123456",
    "provider_shipment_id": "20655836776",
    "status": "pending",
    "is_successful": true,
    "has_label": true,
    "is_international": false,
    "total_parcels_count": 2,
    "label": {
      "format": "pdf",
      "url": "/v1/shipments/sh_123456/label",
      "has_label": true
    },
    "parcels": [
      {
        "id": "prc_001",
        "parcel_number": 1,
        "status": "pending",
        "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",
          "last_status_update": null
        }
      },
      {
        "id": "prc_002",
        "parcel_number": 2,
        "status": "pending",
        "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",
          "last_status_update": null
        }
      }
    ],
    "cash_on_delivery": {
      "amount": 150.00,
      "currency": "CZK"
    },
    "shipping_channel": {
      "id": "ch_123456",
      "name": "PPL CZ",
      "provider": "ppl"
    },
    "sender_contact": {
      "company_name": "Sender Co.",
      "first_name": null,
      "last_name": null,
      "email_address": "sender@example.com",
      "phone_number": "+420123456789"
    },
    "recipient_contact": {
      "company_name": null,
      "first_name": "Jan",
      "last_name": "Novak",
      "email_address": "jan.novak@example.com",
      "phone_number": "+420987654321"
    },
    "origin_address": {
      "street_name": "Hlavni",
      "house_number": "1",
      "apartment_number": null,
      "city_name": "Praha",
      "postal_code": "11000",
      "country_code": "CZ"
    },
    "destination_address": {
      "street_name": "Namesti",
      "house_number": "5",
      "apartment_number": null,
      "city_name": "Brno",
      "postal_code": "60200",
      "country_code": "CZ"
    }
  }
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Invalid or missing API key
422	Unprocessable Entity - Validation errors or provider rejected the shipment
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end
503	Service Unavailable - Unable to communicate with shipping provider

Example Request

cURL

curl -X POST \
  https://api.shipping-channels.com/v1/shipments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_channel_id": "ch_123456",
    "reference_number": "ORD-2025-001",
    "shipping_date": "2025-08-15",
    "label_format": "pdf",
    "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"
    },
    "parcels": [
      {
        "parcel_type": "package",
        "length_dimension": 10,
        "width_dimension": 10,
        "height_dimension": 10,
        "dimension_unit": "CM",
        "weight_amount": 1.5,
        "weight_unit": "KG"
      }
    ]
  }'

PHP

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

$response = $client->request('POST', 'https://api.shipping-channels.com/v1/shipments', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'shipping_channel_id' => 'ch_123456',
        'reference_number' => 'ORD-2025-001',
        'shipping_date' => '2025-08-15',
        'label_format' => 'pdf',
        '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'
        ],
        'parcels' => [
            [
                'parcel_type' => 'package',
                'length_dimension' => 10,
                'width_dimension' => 10,
                'height_dimension' => 10,
                'dimension_unit' => 'CM',
                'weight_amount' => 1.5,
                'weight_unit' => 'KG'
            ]
        ]
    ],
]);

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

JavaScript

fetch('https://api.shipping-channels.com/v1/shipments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    shipping_channel_id: 'ch_123456',
    reference_number: 'ORD-2025-001',
    shipping_date: '2025-08-15',
    label_format: 'pdf',
    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'
    },
    parcels: [
      {
        parcel_type: 'package',
        length_dimension: 10,
        width_dimension: 10,
        height_dimension: 10,
        dimension_unit: 'CM',
        weight_amount: 1.5,
        weight_unit: 'KG'
      }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Endpoint​

Authentication​

Request Body​

sender_contact Object (Required)​

recipient_contact Object (Required)​

origin_address Object (Required)​

destination_address Object (Required)​

return_address Object (Optional)​

parcels Array (Required)​

customs_declaration Object (Optional, required for international shipments)​

customs_declaration.items Array (Required if customs_declaration is present)​

Example Request Body​

Single Parcel Shipment​

Multi-Parcel Shipment​

Response​

201 Created​

Response Example​

Error Responses​

Example Request​

cURL​

PHP​

JavaScript​

Endpoint

Authentication

Request Body

`sender_contact` Object (Required)

`recipient_contact` Object (Required)

`origin_address` Object (Required)

`destination_address` Object (Required)

`return_address` Object (Optional)

`parcels` Array (Required)

`customs_declaration` Object (Optional, required for international shipments)

`customs_declaration.items` Array (Required if `customs_declaration` is present)

Example Request Body

Single Parcel Shipment

Multi-Parcel Shipment

Response

201 Created

Response Example

Error Responses

Example Request

cURL

PHP

JavaScript