Create Shipment

Creates a new shipment.

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)	Yes	The date the shipment is expected to be shipped (YYYY-MM-DD). Must be today or in the future.
`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	Yes	First name of the sender.
`last_name`	string	Yes	Last name of the sender.
`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	Yes	First name of the recipient.
`last_name`	string	Yes	Last name of the recipient.
`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.

`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.

`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.

`parcel` Object (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.
`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`.
`label_comment`	string	No	Comment to be printed on the label.
`label_format`	string	No	Desired label format. E.g., `PDF`, `PNG`.
`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).
`contains_documents_only`	boolean	No	Set to `true` if the parcel contains only documents.
`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.
`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

{
  "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"
  }
}

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 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.
`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": "pending",
    "total_price": 15.50,
    "currency": "USD",
    "created_at": "2025-08-10T10:00:00Z",
    "updated_at": "2025-08-10T10:05:00Z"
  }
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Invalid or missing API key
422	Unprocessable Entity - Validation errors
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end

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",
    "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"
    }
  }'

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",
        "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"
        ]
    ],
]);

$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",
    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"
    }
  })
})
.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)​

parcel Object (Required)​

customs_declaration Object (Optional, required for international shipments)​

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

Example Request Body​

Response​

201 Created​

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)

`parcel` Object (Required)

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

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

Example Request Body

Response

201 Created

Error Responses

Example Request

cURL

PHP

JavaScript