Create a Shipment

Creating a Shipment registers it in your account so Perform.AI can track it, notify recipients, and surface it across the platform. This guide covers the workflow and the rules that trip integrators up; every field is specified in the API reference and the field reference.

Prerequisites

A Bearer token.
To enable tracking: a carrier reference configured under Settings > Carriers. Check what’s configured with the Carrier Configurations API.

The minimum Shipment

Only shipment_id is required:

curl --request POST \
  --url https://api.perform.ai/v5/shipment/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "shipment_id": "SHP-2026-000002" }'

A Shipment without a tracking number and carrier is an Open Shipment — a standalone record you can enrich later, or hand to the Booking API to book with a carrier (which assigns the tracking number for you).

shipment_id must be unique across your account and cannot be changed after creation. Use a stable identifier from your own system, such as your OMS shipment ID.

Enable tracking

Add tracking_number and carrier_reference so Perform.AI can retrieve events from the carrier:

{
  "shipment_id": "SHP-2026-000002",
  "tracking_number": "00340434616780000001",
  "carrier_reference": "dhl-ecommerce-de"
}

Rules that matter here:

carrier_reference must be configured in Settings > Carriers — an unconfigured value rejects the whole request (4030: “carrier_reference specified in request has not been created.”).
tracking_number needs at least 6 characters including one digit; allowed characters are A–Z a–z 0–9 _ - . /, no spaces. It is stored uppercase.
Once the Shipment has track events, tracking_number and carrier_reference can no longer be changed — get them right at creation.

Recommended enrichment

These fields aren’t required but power search, notifications, and analytics:

Field	Why it matters
`to_address.postal_code`, `to_address`/`from_address` city + country	Drive EDD prediction, domestic/international classification, and issue detection.
`tags`	Fast filtering in Parcel Overview and the List Shipments API. Stored lowercase; standardize your vocabulary.
`order_id`	Groups shipments into orders; creates the order if it doesn’t exist.
`notification_email` / `notification_phone`	Subscribe recipients to tracking notifications. Only these arrays notify — the `email`/`phone` inside address objects never do.
`tracking_page_reference`	Routes notifications and tracking links through your branded tracking page. Unconfigured values return a `299` warning.
`line_items`, `shipping_costs`, `documents`	Enrich the record for returns, analytics, and the Parcel Details view.

Keep address lines short even though the API accepts up to 150 characters — carriers commonly enforce ~35 characters per line at booking, and long lines fail there, not here.

Read the response

Success returns the identifiers Perform.AI assigned, flat under data:

{
  "api_response": "200",
  "data": {
    "shipment_uuid": "5b8ed503-20d2-46cf-8675-ce77a059f691",
    "order_uuid": "a0144751-6530-4135-8d73-f258a28ba27d",
    "documents": [],
    "created_date": "2026-09-19T03:26:29+00:00"
  }
}

Store shipment_uuid — it identifies the Shipment in every other endpoint. HTTP 299 means the Shipment was created but part of the request was skipped (an unconfigured tracking page, events without a carrier). Inspect warnings and fix with an update — don’t resend the create, that attempts a duplicate. HTTP 400 (4030) means nothing was created; fix the listed fields and resend. See responses and errors.

Common validation failures

Error message	Cause
`Duplicated.` (on `shipment_id`)	The ID already exists in your account.
`carrier_reference specified in request has not been created.`	The value isn’t configured under Settings > Carriers.
`Cannot define a new order_reference for existing order_id.`	`order_reference` can only be set together with a new `order_id`.
`All shipping costs entries must be in the same currency.`	Mixed currencies in `shipping_costs`.
`Either description or standard_key is required.`	An entry in `events` has neither.
`Country or country_code is required.`	An address object has neither.

Next steps

Update the Shipment — replace-vs-add semantics matter.
Retrieve its details and watch all_events fill.
Receive webhooks instead of polling.

Get Started

Core Concepts

API Essentials

Shipments

Booking & Labels

Returns

Events

Webhooks

Checkout

Customer Experience

Integrations

Resources

Prerequisites

The minimum Shipment

Enable tracking

Recommended enrichment

Read the response

Common validation failures

Next steps

​Prerequisites

​The minimum Shipment

​Enable tracking

​Recommended enrichment

​Read the response

​Common validation failures

​Next steps

Prerequisites

The minimum Shipment

Enable tracking

Recommended enrichment

Read the response

Common validation failures

Next steps