---
title: "Create a shipment"
method: POST
path: "/client/shipments/create"
tags: ["Shipments"]
---

# Create a shipment

`POST /client/shipments/create`

Creates a new shipment in DRAFT status. The shipment must be purchased separately before a label can be generated.

## Request body

- CreateShipmentRequest
  - `recipient` Recipient, required
    - `name` string, required — Recipient name.
    - `phone` string — Recipient phone number.
    - `email` string, email — Recipient email.
    - `signature` boolean — Whether signature is required on delivery.
  - `address` Address, required
    - `address1` string, required — Address line 1.
    - `address2` string — Address line 2.
    - `address3` string — Address line 3.
    - `city` string, required — City.
    - `province` string, required — Province or state code.
    - `postalCode` string, required — Postal or ZIP code.
    - `country` string, required — Country code (e.g. CA, US).
    - `latitude` number — Latitude.
    - `longitude` number — Longitude.
  - `dimensions` Dimensions
    - `length` number — Length.
    - `width` number — Width.
    - `height` number — Height.
    - `dimensionUnit` 'CM' | 'INCH' | 'M' | 'FT' — Unit of dimension.
  - `packagingId` integer — ID of a pre-configured packaging profile. Use instead of dimensions if the package matches a saved profile.
  - `weight` Weight, required
    - `value` number, required — Weight value.
    - `weightUnit` 'G' | 'KG' | 'LB' | 'OZ', required — Unit of weight.
  - `postageType` 'PUBLICATION' | 'SAME DAY' | 'NEXT DAY' | 'STANDARD' | 'USPS Ground Advantage' | 'PostNL International Packet Tracked' | 'OTHER', required — Preferred postage type. Domestic shipments typically use SAME DAY, NEXT DAY, or STANDARD. Cross-border CA→US shipments use USPS Ground Advantage (DDP) or PostNL International Packet Tracked (DDU). If the requested type is unavailable, an available type is selected automatically.
  - `note` string — Optional note, up to 200 characters.
  - `insuranceRequired` boolean — Whether parcel protection (insurance) is required for this shipment.
  - `shipmentLineItems` ShipmentLineItem[], required — Line items describing the contents. Must contain at least one item.
    - `description` string, required — Item description.
    - `quantity` integer, required — Quantity (must be a positive integer).
    - `unit_value` number, required — Value per unit. Accepted as unit_value (snake_case) or unitValue (camelCase).
    - `currency` 'CAD' | 'USD', required — Currency code.
    - `hs_code` string — HS tariff code for cross-border shipments. Accepted as hs_code or hsCode.
    - `country_of_origin` string — ISO country code of manufacture. Accepted as country_of_origin or countryOfOrigin.
    - `sku` string — Your internal SKU reference.
    - `manufacturer` object — Manufacturer details. Required for some cross-border shipments.
      - `name` string, required — Manufacturer name (min 3 characters).
      - `address1` string, required — Street address.
      - `address2` string — Address line 2.
      - `city` string, required — City.
      - `provinceCode` string — Province or state code.
      - `postalCode` string — Postal or ZIP code.
      - `countryCode` string, required — ISO 3166-1 alpha-2 country code (e.g. CN, US, CA).
      - `phone` string — Manufacturer phone number.
      - `email` string, email — Manufacturer email address.
  - `orderNumber` string — Optional client-provided order reference.

## Response `200`

Shipment created or error returned

- object
  - `message` string, required — Additional information about the request status.
  - `code` integer, required — Status code. 0 indicates success.
  - `data` ShipmentResponseData
    - `orderNumber` string, required — Unique order number.
    - `trackingId` string, required — Shipment tracking ID.
    - `recipient` Recipient
      - `name` string, required — Recipient name.
      - `phone` string — Recipient phone number.
      - `email` string, email — Recipient email.
      - `signature` boolean — Whether signature is required on delivery.
    - `address` Address
      - `address1` string, required — Address line 1.
      - `address2` string — Address line 2.
      - `address3` string — Address line 3.
      - `city` string, required — City.
      - `province` string, required — Province or state code.
      - `postalCode` string, required — Postal or ZIP code.
      - `country` string, required — Country code (e.g. CA, US).
      - `latitude` number — Latitude.
      - `longitude` number — Longitude.
    - `dimensions` Dimensions
      - `length` number — Length.
      - `width` number — Width.
      - `height` number — Height.
      - `dimensionUnit` 'CM' | 'INCH' | 'M' | 'FT' — Unit of dimension.
    - `weight` Weight
      - `value` number, required — Weight value.
      - `weightUnit` 'G' | 'KG' | 'LB' | 'OZ', required — Unit of weight.
    - `status` 'DRAFT' | 'PENDING' | 'PENDING_REVIEW' | 'PICKUP_REQUESTED' | 'PICKUP_CANCELLED' | 'PARTNER_RECEIVED' | 'PICKED_UP' | 'RECEIVED' | 'GATEWAY_TRANSIT' | 'PARCEL_SCANNED' | 'TRANSSHIPMENT_COMPLETE' | 'IN_TRANSIT' | 'OUT_FOR_DELIVERY' | 'DELIVERED' | 'SHIPMENT_EXCEPTION' | 'AGED_OUT' | 'RETURNED' | 'CANCELLED' | 'STORAGE' | 'FAILED' | 'FAILED_DELIVERY1' | 'FAILED_DELIVERY2' | 'GATEWAY_TO_GATEWAY_TRANSIT' | 'GATEWAY_TRANSIT_OUT', required — Shipment status.
    - `note` string
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time
    - `rates` BillingSummary
      - `postageType` 'PUBLICATION' | 'SAME DAY' | 'NEXT DAY' | 'STANDARD' | 'USPS Ground Advantage' | 'PostNL International Packet Tracked' | 'OTHER' — Preferred postage type. Domestic shipments typically use SAME DAY, NEXT DAY, or STANDARD. Cross-border CA→US shipments use USPS Ground Advantage (DDP) or PostNL International Packet Tracked (DDU). If the requested type is unavailable, an available type is selected automatically.
      - `postageFee` number — Postage fee.
      - `signatureFee` number — Signature fee.
      - `duty` number — Duty amount (cross-border shipments only).
      - `tax` number — Tax amount.
      - `total` number — Total cost.
      - `currency` 'CAD' | 'USD' — Currency code.
    - `shipmentLineItems` ShipmentLineItem[]
      - `description` string, required — Item description.
      - `quantity` integer, required — Quantity (must be a positive integer).
      - `unit_value` number, required — Value per unit. Accepted as unit_value (snake_case) or unitValue (camelCase).
      - `currency` 'CAD' | 'USD', required — Currency code.
      - `hs_code` string — HS tariff code for cross-border shipments. Accepted as hs_code or hsCode.
      - `country_of_origin` string — ISO country code of manufacture. Accepted as country_of_origin or countryOfOrigin.
      - `sku` string — Your internal SKU reference.
      - `manufacturer` object — Manufacturer details. Required for some cross-border shipments.
        - `name` string, required — Manufacturer name (min 3 characters).
        - `address1` string, required — Street address.
        - `address2` string — Address line 2.
        - `city` string, required — City.
        - `provinceCode` string — Province or state code.
        - `postalCode` string — Postal or ZIP code.
        - `countryCode` string, required — ISO 3166-1 alpha-2 country code (e.g. CN, US, CA).
        - `phone` string — Manufacturer phone number.
        - `email` string, email — Manufacturer email address.
    - `insuranceRequired` boolean

## Other responses

- `422` — Invalid payload

---

[API](https://skmtc.dev/uniuni/apis/uniuni-platform-client-api.md) · [All operations](https://skmtc.dev/uniuni/apis/uniuni-platform-client-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/uniuni/uniuni-platform-client-api/revisions/d61334c7f8b1/schema)