> ## Documentation Index
> Fetch the complete documentation index at: https://help.ship.uniuni.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a shipment
> Creates a new shipment in DRAFT status. The shipment must be purchased separately before a label can be generated.
Once you've purchased a shipment and printed the label, visit [ship.uniuni.com/locations](https://ship.uniuni.com/locations) to confirm your drop-off location or [ship.uniuni.com/pickups](https://ship.uniuni.com/pickups) to request a pick-up service (if available).
**`shipmentLineItems` is required.** Every shipment must include at least one line item (`shipmentLineItems` array with >= 1 element). Omitting it or sending an empty array returns a `422 PayloadValidationError`.
**Cross-border shipments (CA → US):** Each item in `shipmentLineItems` must also include `hs_code`, `country_of_origin`, and a `description` identifying the manufacturer. Shipments missing this information may be held at the border.
## OpenAPI
````yaml POST /client/shipments/create
openapi: 3.1.0
info:
title: UniUni Platform Client API
description: >-
API for creating shipments, purchasing labels, managing batches, tracking
deliveries, and receiving webhook notifications.
version: 1.0.0
contact:
name: UniUni Retail Support
email: retailsupport@uniuni.com
servers:
- url: https://api.ship.uniuni.com/prod
description: Production
- url: https://api-sandbox.ship.uniuni.com
description: Sandbox
security:
- bearerAuth: []
tags:
- name: Shipments
description: Create, retrieve, list, purchase, refund, and delete shipments.
- name: Batches
description: Group purchased shipments into batches for drop-off or pickup.
- name: Labels
description: Retrieve shipping and batch labels as Base64-encoded PDFs.
- name: Tracking
description: Track shipment status and scan events.
- name: Webhooks
description: Receive real-time shipment status updates.
paths:
/client/shipments/create:
post:
tags:
- Shipments
summary: Create a shipment
description: >-
Creates a new shipment in DRAFT status. The shipment must be purchased
separately before a label can be generated.
operationId: createShipment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateShipmentRequest'
example:
recipient:
name: Jane Doe
phone: +1-604-123-4567
email: jane@example.com
signature: false
address:
address1: 3460 Cawthra Road
address2: ''
city: Mississauga
province: 'ON'
postalCode: L5A 2Y1
country: CA
dimensions:
length: 1
width: 1
height: 1
dimensionUnit: INCH
weight:
value: 1
weightUnit: LB
postageType: STANDARD
note: Gift Box
shipmentLineItems:
- description: test
quantity: 1
unit_value: 10
currency: CAD
example:
recipient:
name: Jane Doe
phone: +1-604-123-4567
email: jane@example.com
signature: false
address:
address1: 3460 Cawthra Road
city: Mississauga
province: 'ON'
postalCode: L5A 2Y1
country: CA
dimensions:
length: 1
width: 1
height: 1
dimensionUnit: INCH
weight:
value: 1
weightUnit: LB
postageType: STANDARD
note: Gift Box
shipmentLineItems:
- description: T-shirt
quantity: 1
unit_value: 10
currency: CAD
responses:
'200':
description: Shipment created or error returned
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Additional information about the request status.
code:
type: integer
description: Status code. 0 indicates success.
data:
$ref: '#/components/schemas/ShipmentResponseData'
required:
- message
- code
examples:
success:
summary: Shipment created successfully
value:
message: Shipment created successfully
code: 0
data:
orderNumber: UNI031455E90
trackingId: UR07300000000005351
recipient:
name: Jane Doe
phone: +1-604-123-4567
email: jane@example.com
address:
address1: 2455 Meadowvale Blvd
city: Mississauga
province: 'ON'
postalCode: L5N 0H1
country: CA
dimensions:
length: 1
width: 1
height: 1
dimensionUnit: INCH
weight:
value: 1
weightUnit: LB
status: DRAFT
note: Gift Box
createdAt: '2025-07-30T18:32:11.455Z'
updatedAt: '2025-07-30T18:32:11.899Z'
rates:
postageType: NEXT DAY
postageFee: 4.88
tax: 0.63
total: 5.51
currency: CAD
shipmentLineItems:
- description: T-shirt
quantity: 1
unit_value: 10
currency: CAD
notInServiceArea:
summary: Not in service area
value:
message: >-
No service rate for the origin location: Hamilton, ON,
Canada
code: 1009
data: null
'422':
$ref: '#/components/responses/ValidationError'
components:
schemas:
CreateShipmentRequest:
type: object
properties:
recipient:
$ref: '#/components/schemas/Recipient'
description: Recipient details. Provide phone, email, or both.
address:
$ref: '#/components/schemas/Address'
dimensions:
$ref: '#/components/schemas/Dimensions'
description: >-
Package dimensions. Provide either dimensions or packagingId, not
both. If neither is provided, a saved default packaging preset will
be used. If there are no saved packaging presets, dimensions are
required.
packagingId:
type: integer
description: >-
ID of a pre-configured packaging profile. Use instead of dimensions
if the package matches a saved profile.
weight:
$ref: '#/components/schemas/Weight'
postageType:
$ref: '#/components/schemas/PostageType'
note:
type: string
maxLength: 200
description: Optional note, up to 200 characters.
insuranceRequired:
type: boolean
description: Whether parcel protection (insurance) is required for this shipment.
shipmentLineItems:
type: array
items:
$ref: '#/components/schemas/ShipmentLineItem'
minItems: 1
description: Line items describing the contents. Must contain at least one item.
orderNumber:
type: string
description: Optional client-provided order reference.
required:
- recipient
- address
- weight
- shipmentLineItems
- postageType
ShipmentResponseData:
type: object
properties:
orderNumber:
type: string
description: Unique order number.
trackingId:
type: string
description: Shipment tracking ID.
recipient:
$ref: '#/components/schemas/Recipient'
address:
$ref: '#/components/schemas/Address'
dimensions:
$ref: '#/components/schemas/Dimensions'
weight:
$ref: '#/components/schemas/Weight'
status:
$ref: '#/components/schemas/ShipmentStatus'
note:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
rates:
$ref: '#/components/schemas/BillingSummary'
shipmentLineItems:
type: array
items:
$ref: '#/components/schemas/ShipmentLineItem'
insuranceRequired:
type: boolean
required:
- orderNumber
- trackingId
- status
- createdAt
Recipient:
type: object
properties:
name:
type: string
description: Recipient name.
phone:
type: string
description: Recipient phone number.
email:
type: string
format: email
description: Recipient email.
signature:
type: boolean
default: false
description: Whether signature is required on delivery.
required:
- name
Address:
type: object
properties:
address1:
type: string
description: Address line 1.
address2:
type: string
description: Address line 2.
address3:
type: string
description: Address line 3.
city:
type: string
description: City.
province:
type: string
description: Province or state code.
postalCode:
type: string
description: Postal or ZIP code.
country:
type: string
description: Country code (e.g. CA, US).
latitude:
type: number
description: Latitude.
longitude:
type: number
description: Longitude.
required:
- address1
- city
- province
- postalCode
- country
Dimensions:
type: object
properties:
length:
type: number
description: Length.
width:
type: number
description: Width.
height:
type: number
description: Height.
dimensionUnit:
type: string
enum:
- CM
- INCH
- M
- FT
description: Unit of dimension.
Weight:
type: object
properties:
value:
type: number
description: Weight value.
weightUnit:
type: string
enum:
- G
- KG
- LB
- OZ
description: Unit of weight.
required:
- value
- weightUnit
PostageType:
type: string
enum:
- PUBLICATION
- SAME DAY
- NEXT DAY
- STANDARD
- USPS Ground Advantage
- PostNL International Packet Tracked
- OTHER
description: >-
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.
ShipmentLineItem:
type: object
properties:
description:
type: string
description: Item description.
quantity:
type: integer
description: Quantity (must be a positive integer).
unit_value:
type: number
description: >-
Value per unit. Accepted as unit_value (snake_case) or unitValue
(camelCase).
currency:
type: string
enum:
- CAD
- USD
description: Currency code.
hs_code:
type: string
description: >-
HS tariff code for cross-border shipments. Accepted as hs_code or
hsCode.
country_of_origin:
type: string
description: >-
ISO country code of manufacture. Accepted as country_of_origin or
countryOfOrigin.
sku:
type: string
description: Your internal SKU reference.
manufacturer:
type: object
description: Manufacturer details. Required for some cross-border shipments.
properties:
name:
type: string
description: Manufacturer name (min 3 characters).
address1:
type: string
description: Street address.
address2:
type: string
description: Address line 2.
city:
type: string
description: City.
provinceCode:
type: string
description: Province or state code.
postalCode:
type: string
description: Postal or ZIP code.
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code (e.g. CN, US, CA).
phone:
type: string
description: Manufacturer phone number.
email:
type: string
format: email
description: Manufacturer email address.
required:
- name
- address1
- city
- countryCode
required:
- description
- quantity
- unit_value
- currency
ShipmentStatus:
type: string
enum:
- 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
description: Shipment status.
BillingSummary:
type: object
properties:
postageType:
$ref: '#/components/schemas/PostageType'
postageFee:
type: number
description: Postage fee.
signatureFee:
type: number
description: Signature fee.
duty:
type: number
description: Duty amount (cross-border shipments only).
tax:
type: number
description: Tax amount.
total:
type: number
description: Total cost.
currency:
type: string
enum:
- CAD
- USD
description: Currency code.
responses:
ValidationError:
description: Invalid payload
content:
application/json:
schema:
type: object
properties:
message:
type: string
errorCode:
type: string
enum:
- PayloadValidationError
statusCode:
type: integer
enum:
- 422
meta:
type: object
properties:
issues:
type: array
items:
type: object
properties:
code:
type: string
expected:
type: string
received:
type: string
path:
type: array
items:
type: string
message:
type: string
name:
type: string
enum:
- ZodError
example:
message: Invalid payload
errorCode: PayloadValidationError
statusCode: 422
meta:
issues:
- code: invalid_type
expected: number
received: nan
path:
- page
message: Expected number, received nan
name: ZodError
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API access token generated from the UniUni Platform dashboard.
````