Import shipments (JSON)

POST /v1/org/shipments/imports

Send up to 1000 shipments in one call, in the published structure. The call returns as soon as the batch is accepted — it does not wait for the shipments to be written. You get an importId; poll it for the outcome and read the rejected rows if any.

Sending the same shipment twice is safe. A shipmentId already in the ledger is updated, not duplicated — its goods lines are replaced by the ones you send. Retries, re-runs and corrected re-sends all do the right thing.

Authorization

string

required

Your organisation API key (dzk_live_…).

Body

Shipment[]

required

1–1000 shipments. See Shipment structure for every field. Each shipment needs at least one entry in items, at most 500, and the batch as a whole may carry at most 10,000 goods lines — send bigger runs as a file.

string

Your own reference for this push — a batch id, run date or filename. It is echoed on the import and recorded against every shipment it creates, so a shipment can be traced back to the run that sent it.

Unknown fields are rejected, not ignored. If you send weight where the structure says itemWeight, you get a 400 naming the field rather than a shipment that silently lost its weight.

Response

202 Accepted with the import’s id and where to poll it.

Field	Description
`importId`	Poll this for the outcome
`status`	`queued` on acceptance
`source`	`data` for this endpoint
`shipmentsReceived`	Shipments accepted for processing (the import’s `counts` are rows)
`statusUrl`	Convenience path to the status endpoint

Errors

Status	When
`400`	Malformed body, more than 1000 shipments, more than 10,000 goods lines in total, more than 500 lines on one shipment, a shipment with no items, an unrecognised field, or a custom field your organisation has not configured
`400`	Too many imports already queued — wait for the queue to drain
`401`	Missing or invalid API key
`429`	Rate limit exceeded — see Rate limits

curl -X POST https://api.dyspach.com/v1/org/shipments/imports \
  -H "x-api-key: $DYSPACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDetails": "nightly-2026-08-14",
    "shipments": [
      {
        "shipmentId": "CONN-88213",
        "customerId": "ACME",
        "originPostCode": "3000",
        "originSuburb": "Melbourne",
        "originState": "VIC",
        "originCountryCode": "AU",
        "destinationPostCode": "2000",
        "destinationSuburb": "Sydney",
        "destinationState": "NSW",
        "destinationCountryCode": "AU",
        "quoteDate": "2026-08-14T02:15:00Z",
        "rateCardAlias": "EXPRESS",
        "totalCostReceived": 412.55,
        "customFields": { "Purchase Order": "PO-99187" },
        "items": [
          { "itemType": "Pallet", "itemQuantity": 2, "itemWeight": 240 },
          { "itemType": "Carton", "itemQuantity": 6, "itemWeight": 18 }
        ]
      }
    ]
  }'

{
  "importId": "9f2b1c44-0d3e-4a71-9b52-0f4c1e77a8d1",
  "status": "queued",
  "source": "data",
  "shipmentsReceived": 1,
  "statusUrl": "/v1/org/shipments/imports/9f2b1c44-0d3e-4a71-9b52-0f4c1e77a8d1"
}

{
  "statusCode": 400,
  "message": ["shipments.0.items should not be empty"],
  "error": "Bad Request"
}

Getting Started

Guides

Quotes

Shipments

Import shipments (JSON)

Authorization

Body

Response

Errors

​Authorization

​Body

​Response

​Errors

Authorization

Body

Response

Errors