Prepare orders and shipments

Orders, shipments, and appointments#

An order describes expected freight. A shipment allocates some or all of that freight for a visit. An appointment reserves time. Preparing a shipment does not check in a driver or create yard presence.

One shipment can combine compatible orders at the same location; an order can be split across shipments. Unknown quantity can be allocated whole once. Set a total before splitting it.

Import expected orders#

Use POST /api/v1/expected-work/orders with orders:write. A batch accepts 1–500 records. Keep a stable source and source_key for recurring imports. Identity is location + source + source key, not a guessed PO match.

{
  "location_id": "dock-id",
  "rows": [
    {
      "source": "erp",
      "source_key": "ERP-001",
      "references": [
        {
          "type": "ORDER",
          "value": "ORD-001",
          "primary": true
        },
        {
          "type": "PO",
          "value": "000123"
        }
      ],
      "direction": "out",
      "quantity": 10,
      "unit": "pallets",
      "expected_date": "2026-10-01"
    }
  ]
}

Replaying identical source data reuses the order and can add aliases. Conflicting details return 409 and roll back the batch. Use the update endpoint for changes. Preserve leading zeros in references.

Create a shipment#

POST /api/v1/expected-work/shipments requires both orders:write and appointments:write.

{
  "location_id": "dock-id",
  "request_id": "unique-request-001",
  "direction": "out",
  "service_method": "live",
  "issue_invitation": false,
  "references": [
    {
      "type": "LOAD",
      "value": "LOAD-001",
      "primary": true
    }
  ],
  "allocations": [
    {
      "order_id": "order-id",
      "quantity": 4
    }
  ]
}

The example prepares four pallets without issuing a private invitation. The response includes id and stopId. Pass loadStopId: stopId when booking through the v1 appointment endpoint to avoid creating a second load.

A repeated request_id returns 409. After a lost response, read and reconcile shipments before retrying. With invitation issuance enabled (the default), a returned bookingUrl is a bearer secret.

Quantities and release#

Supported units are pieces, pallets, cases, pounds, and kilograms, with up to three decimal places and one unit per order. No automatic unit conversion is performed. Quantities cannot be changed while allocations remain active.

Cancelling an appointment preserves its shipment and allocations. To return quantity to an order, first cancel the appointment, then release the unbooked shipment. Arrived or completed work cannot be released this way.

List and import limits#

Order and shipment lists return at most 1,000 records with no pagination in this version. Filter before treating a list as a complete export. Preview validates input; database conflicts are checked during atomic import.

Expected-work handler errors contain error but may omit a machine code. Do not branch on human-readable message text.