Skip to main content

Importing shipments

Bring tracked shipments into Orderly from any system, by CSV in the Portal, or through the API. Every source goes through the same canonical ingest, so tenancy, idempotency, EasyPost tracker registration, and Intelligence sync behave identically no matter how a shipment arrives.

CSV import (Portal)​

Shipments → Import opens the import wizard:

  1. Download the template. The versioned CSV template lists every accepted column. The required minimum is external_shipment_id, tracking_number, and carrier; useful optional columns include order_id, service, ship_date, promised_date, origin/destination address fields, and declared_value / currency.
  2. Upload (drag & drop or browse, up to 10 MB). Rows are validated server-side, nothing is created yet.
  3. Review the preview. You'll see total / valid / invalid / duplicate counts and a per-row error table (for example a malformed ship_date or a missing external_shipment_id).
  4. Commit valid rows. Only valid rows import; invalid rows never block the rest. Progress updates live while shipments are created in bounded background batches.
  5. Download the error report if any rows failed: a CSV with row numbers and reasons, safe to open in a spreadsheet.

Imports are idempotent: re-uploading the same file shows the existing job instead of creating duplicates, and a retried commit can never double-create shipments, trackers, or tracking events.

What happens after commit​

  • Each shipment with a tracking number gets exactly one EasyPost tracker; carrier webhooks then keep status, ETA, location, and the full scan timeline current.
  • Shipments and subsequent tracking changes sync to Orderly Intelligence with full source lineage.
  • If your organization runs Parcel Pro, eligible shipments are reported for coverage automatically (reporting only, this is not a claim).

API import​

POST /api/v1/shipments with an API key holding shipments:write:

curl -X POST https://api.orderly-hub.com/api/v1/shipments \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipment-1" \
  -d '{
    "externalId": "SHP-1042",
    "trackingNumber": "1Z999AA10123456784",
    "carrier": "UPS",
    "service": "Ground",
    "shipDate": "2026-08-27T10:00:00Z"
  }'
  • Idempotency-Key (recommended): replays return the original shipment without duplicating trackers or integrations.
  • The organization is always derived from the API key, an org_id in the payload is never trusted.
  • Carrier names are normalized (FeD Ex → fedex) while the original value is preserved.

The full request/response contract lives in the API reference.