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": "Express Channel",
      "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.uniship.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.uniship.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.uniship.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));