Shipments Endpoints: Headers, Lines & Dispatch Posting

The shipments API manages the outbound dispatch workflow: listing open shipment headers, loading the picking lines for a shipment, recording how many units have been packed, and posting the shipment to close it against the sales order. The client includes a legacy-data fallback strategy — if GET /api/shipmentlines fails (common with older tenants), the handheld transparently re-fetches the header detail and extracts the embedded lines array instead. All endpoints require a valid bearer token and company context. Required headers for all endpoints:

Authorization: Bearer <token>
X-Company-Id: <company-guid>

GET /api/shipmentheaders

Returns a paginated, sortable list of shipment headers for the authenticated company. Supports optional filtering by status and shipment number. Results default to newest-first (sortBy=CreatedAt&sortDesc=true). Method & path: GET /api/shipmentheaders
Auth required: Yes

Query parameters

pageNumber

integer

required

1-based page number.

pageSize

integer

required

Number of records per page.

sortBy

string

Field to sort by. Defaults to CreatedAt.

sortDesc

boolean

Sort direction. true for descending (newest first). Defaults to true.

status

string

Optional status filter, e.g. Released, Open, Shipped.

shipmentNo

string

Optional shipment number filter for exact or partial lookup.

Response — 200 OK

Returns a PagedResponse<ShipmentHeaderDto>.

{
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 12,
  "totalPages": 1,
  "data": [
    {
      "id": "7f8e9d0c-1234-5678-abcd-ef0123456789",
      "companyId": "9c8b7a6f-1234-5678-abcd-ef0123456789",
      "companyCode": "ACME",
      "shipmentNo": "SHP-2024-0005",
      "externalShipmentNo": "SO-2024-0123",
      "shipmentType": "SALES",
      "shipmentStatus": "Released",
      "documentStatus": "Released",
      "processingStatus": "Partial",
      "warehouseCode": "WH-MAIN",
      "customerCode": "CUST-007",
      "customerName": "Rapid Retail S.A.",
      "plannedShipDate": "2024-06-10T00:00:00Z",
      "actualShipDate": null,
      "totalLines": 5,
      "totalQty": 320.0,
      "isClosed": false,
      "createdAt": "2024-06-05T08:30:00Z"
    }
  ],
  "hasPrevious": false,
  "hasNext": false
}

pageNumber

integer

Current page number.

pageSize

integer

Records per page as requested.

totalRecords

integer

Total matching records across all pages.

totalPages

integer

Total number of pages.

hasPrevious

boolean

Whether a previous page exists.

hasNext

boolean

Whether a next page exists.

data

array

Array of ShipmentHeaderDto objects.

Show ShipmentHeaderDto

guid

Unique identifier of the shipment header. Used as {id} in all other shipment endpoints.

companyId

guid

Company the shipment belongs to.

companyCode

string

Company short code.

shipmentNo

string

Human-readable shipment number, e.g. SHP-2024-0005.

externalShipmentNo

string | null

Linked sales order or external reference number.

shipmentType

string

Shipment type, e.g. SALES, TRANSFER.

shipmentStatus

string

High-level ERP status of the shipment.

documentStatus

string

Formal document status, used as fallback display when processingStatus is empty.

processingStatus

string

Handheld processing status, e.g. Partial, Complete. Takes precedence over documentStatus in the UI.

warehouseCode

string

Source warehouse code. Also exposed as locationCode (returns MAIN when blank).

customerCode

string

Customer code from the ERP.

customerName

string

Customer display name.

plannedShipDate

datetime | null

Requested or planned dispatch date.

actualShipDate

datetime | null

Actual dispatch date. null until the shipment is posted.

totalLines

integer

Number of picking lines on this shipment.

totalQty

decimal

Total quantity across all lines.

isClosed

boolean

Whether the shipment has been fully closed.

createdAt

datetime

UTC timestamp when the shipment was created.

Example

curl "https://your-server/api/shipmentheaders?pageNumber=1&pageSize=20&sortBy=CreatedAt&sortDesc=true" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

GET /api/shipmentlines

Returns the individual picking lines for one shipment. The client automatically falls back to extracting the embedded lines array from GET /api/shipmentheaders/{id} if this endpoint returns an error — this handles legacy tenant data that does not expose the standalone lines endpoint.

If GET /api/shipmentlines fails, the client calls GET /api/shipmentheaders/{shipmentId}, reads the lines property from the JSON response, and constructs an equivalent paged response. The operator sees no difference. Design your integrations to populate the standalone endpoint whenever possible; the fallback exists for backward compatibility only.

Method & path: GET /api/shipmentlines
Auth required: Yes

Query parameters

shipmentId

guid

required

UUID of the parent shipment header. Obtain from GET /api/shipmentheaders.

pageNumber

integer

required

1-based page number.

pageSize

integer

required

Records per page.

status

string

Optional status filter for line-level status, e.g. Pending, Picked, Partial.

Response — 200 OK

Returns a PagedResponse<ShipmentLineDto>.

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalRecords": 5,
  "totalPages": 1,
  "data": [
    {
      "companyId": "9c8b7a6f-...",
      "shipmentId": "7f8e9d0c-...",
      "id": "c1d2e3f4-1234-5678-abcd-ef0123456789",
      "lineNo": 10000,
      "lineStatus": "Pending",
      "itemId": "a1b2c3d4-...",
      "itemNo": "ITEM-0042",
      "itemDescription": "Bolt M8 x 30mm",
      "unitOfMeasure": "EA",
      "warehouseId": "wh-main-guid",
      "binId": "b9c8d7e6-...",
      "binCode": "A-01-02",
      "orderedQty": 100.0,
      "pickedQty": 60.0,
      "shippedQty": 60.0,
      "baseUomQty": 60.0,
      "remainingQty": 40.0,
      "remainingQuantity": 40.0,
      "lotNo": null,
      "serialNo": null,
      "expirationDate": null,
      "unitWeight": 0.012,
      "unitVolume": null,
      "isCompleted": false,
      "createdAt": "2024-06-05T08:30:00Z",
      "updatedAt": null,
      "alreadyPostedQty": 0.0,
      "postedQuantity": 0.0
    }
  ],
  "hasPrevious": false,
  "hasNext": false
}

data

array

Array of ShipmentLineDto objects.

Show ShipmentLineDto

companyId

string

Company context for this line.

shipmentId

string

Parent shipment header UUID.

string

Unique identifier of the shipment line. Used as {id} in PUT /api/shipmentlines/{id}.

lineNo

integer

ERP line sequence number.

lineStatus

string

Status of this individual line, e.g. Pending, Partial, Picked.

itemId

string

Internal UUID of the item.

itemNo

string

ERP item code.

itemDescription

string

Item display name.

unitOfMeasure

string

Unit of measure code.

warehouseId

string

Source warehouse UUID.

binId

string

Source bin UUID for picking.

binCode

string

Source bin code.

orderedQty

decimal

Total quantity ordered on this line.

pickedQty

decimal

Quantity physically picked so far.

shippedQty

decimal

Quantity confirmed for shipment. Clamped to [0, orderedQty] client-side.

baseUomQty

decimal | null

Quantity expressed in the base unit of measure.

remainingQty

decimal

Remaining quantity (legacy field).

remainingQuantity

decimal

Remaining quantity to ship. The UI uses max(remainingQuantity, remainingQty) as the effective remaining balance.

lotNo

string | null

Lot number assigned to this line.

serialNo

string | null

Serial number assigned to this line.

expirationDate

datetime | null

Expiration date for lot/serial tracked items.

unitWeight

decimal | null

Weight per unit.

unitVolume

decimal | null

Volume per unit.

isCompleted

boolean

Whether this line has been fully processed.

createdAt

datetime

UTC creation timestamp.

updatedAt

datetime | null

UTC timestamp of last update.

alreadyPostedQty

decimal

Quantity posted in previous sessions.

postedQuantity

decimal

Total quantity committed to inventory by posting.

Example

curl "https://your-server/api/shipmentlines?shipmentId=7f8e9d0c-1234-5678-abcd-ef0123456789&pageNumber=1&pageSize=50" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

PUT /api/shipmentlines/

Updates the shipped quantity for a single shipment line. The operator enters how many units they are dispatching; the value is saved and used during the final posting step. Method & path: PUT /api/shipmentlines/{id}
Auth required: Yes

Path parameters

string

required

UUID (as string) of the shipment line to update. Obtain from GET /api/shipmentlines.

Request body

{
  "shippedQty": 80.0
}

shippedQty

decimal

required

New shipped quantity for this line. Must be ≥ 0 and should not exceed orderedQty. The client enforces the upper bound locally before sending.

Response — 200 OK

No response body on success.

Error conditions

Status	Condition
`400 Bad Request`	`shippedQty` is negative or otherwise invalid.
`404 Not Found`	No shipment line with the given `id`.
`409 Conflict`	The line has already been fully posted.

Example

curl -X PUT "https://your-server/api/shipmentlines/c1d2e3f4-1234-5678-abcd-ef0123456789" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789" \
  -H "Content-Type: application/json" \
  -d '{"shippedQty": 80.0}'

POST /api/shipmentheaders//post

Posts a completed shipment to the ERP. All pending shipped quantities across every line are committed, the shipment is closed against the sales order, and stock is decremented. This operation is non-reversible.

Posting is irreversible. Verify all line quantities with the operator before calling this endpoint. Lines that are already posted cannot be modified.

Method & path: POST /api/shipmentheaders/{id}/post
Auth required: Yes

Path parameters

string

required

UUID of the shipment header to post.

Request body

None. No body is required.

Response — 200 OK

No response body on success. The client should re-fetch the header and lines to reflect the updated statuses and posted quantities.

Error conditions

Status	Condition
`400 Bad Request`	No lines have a pending shipped quantity (nothing to post).
`400 Bad Request`	One or more lines are missing required lot, serial, or bin information.
`409 Conflict`	The shipment has already been fully posted.
`422 Unprocessable Entity`	Insufficient available stock for one or more items.
`404 Not Found`	No shipment header with the given `id`.

Example

curl -X POST "https://your-server/api/shipmentheaders/7f8e9d0c-1234-5678-abcd-ef0123456789/post" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

API Endpoints

Services

Data Models

Shipments Endpoints: Headers, Lines & Dispatch Posting

GET /api/shipmentheaders

Query parameters

Response — 200 OK

Example

GET /api/shipmentlines

Query parameters

Response — 200 OK

Example

PUT /api/shipmentlines/

Path parameters

Request body

Response — 200 OK

Error conditions

Example

POST /api/shipmentheaders//post

Path parameters

Request body

Response — 200 OK

Error conditions

Example

Build docs developers (and LLMs) love

API Endpoints

Services

Data Models

Documentation Index

​GET /api/shipmentheaders

​Query parameters

​Response — 200 OK

​Example

​GET /api/shipmentlines

​Query parameters

​Response — 200 OK

​Example

​PUT /api/shipmentlines/

​Path parameters

​Request body

​Response — 200 OK

​Error conditions

​Example

​POST /api/shipmentheaders//post

​Path parameters

​Request body

​Response — 200 OK

​Error conditions

​Example

Build docs developers (and LLMs) love

GET /api/shipmentheaders

Query parameters

Response — 200 OK

Example

GET /api/shipmentlines

Query parameters

Response — 200 OK

Example

PUT /api/shipmentlines/

Path parameters

Request body

Response — 200 OK

Error conditions

Example

POST /api/shipmentheaders//post

Path parameters

Request body

Response — 200 OK

Error conditions

Example