Receipts Endpoints: Headers, Lines & Posting

The receipts API covers the full lifecycle of an inbound goods receipt: listing open receiving headers, fetching and updating the individual item lines, and posting the receipt to inventory. The client fetches all headers without a pre-applied Released filter — the status is returned as-is from the server so the handheld UI can display all documents and apply its own presentation logic. All endpoints require a valid bearer token and a company context header. Required headers for all endpoints:

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

GET /api/ReceivingHeaders

Returns a paginated list of receiving headers visible to the authenticated user’s company. An optional status filter narrows the results. The client does not apply a fixed Released status filter — all headers are returned so the operator can see the full picture. Method & path: GET /api/ReceivingHeaders
Auth required: Yes

Query parameters

PageNumber

integer

required

1-based page number.

PageSize

integer

required

Number of records per page.

status

string

Optional status filter. When supplied, only headers matching this status value are returned, e.g. Released, Open, Posted.

Response — 200 OK

Returns a PagedResponse<ReceivingHeaderDto>.

{
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 5,
  "totalPages": 1,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "companyId": "9c8b7a6f-1234-5678-abcd-ef0123456789",
      "receiptNo": "RCV-2024-0001",
      "externalDocumentNo": "PO-2024-0099",
      "vendorCode": "VEND-01",
      "vendorName": "Global Parts Supply",
      "locationCode": "WH-MAIN",
      "status": "Released",
      "documentStatus": "Released",
      "processingStatus": "Partial",
      "receiptDate": "2024-06-01T00:00:00Z",
      "createdAt": "2024-05-30T09:15:00Z",
      "postedAt": null,
      "createdBy": "[email protected]",
      "postedBy": null
    }
  ],
  "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 ReceivingHeaderDto objects.

Show ReceivingHeaderDto

guid

Unique identifier of the receiving header. Use this as {id} in all other receipt endpoints.

companyId

guid

Company the document belongs to.

receiptNo

string

Human-readable receipt number, e.g. RCV-2024-0001.

externalDocumentNo

string | null

Linked purchase order or external reference number.

vendorCode

string | null

Vendor code from the ERP.

vendorName

string | null

Vendor display name.

locationCode

string | null

Warehouse location code. Defaults to MAIN when blank.

status

string

Document status from the ERP, e.g. Open, Released, Posted.

documentStatus

string

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

processingStatus

string

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

receiptDate

datetime

Planned or actual date of receipt.

createdAt

datetime

UTC timestamp when the header was created.

postedAt

datetime | null

UTC timestamp when the receipt was posted. null if not yet posted.

createdBy

string

Email of the user who created the header.

postedBy

string | null

Email of the user who posted the receipt.

Example

curl "https://your-server/api/ReceivingHeaders?PageNumber=1&PageSize=20" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

GET /api/receivinglines/by-header/

Returns all receiving lines belonging to a specific header. The client requests up to 100 lines per call. Each line includes the expected quantity, the quantity already received and posted, the remaining quantity, and the target bin assignment. Method & path: GET /api/receivinglines/by-header/{id}
Auth required: Yes

Path parameters

guid

required

The UUID of the receiving header. Obtain this from GET /api/ReceivingHeaders.

Query parameters

PageNumber

integer

required

1-based page number. The handheld client requests PageNumber=1.

PageSize

integer

required

Records per page. The handheld client requests PageSize=100.

Response — 200 OK

Returns a PagedResponse<ReceivingLineDto>. The data array contains the individual lines.

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalRecords": 3,
  "totalPages": 1,
  "data": [
    {
      "id": "aabbccdd-1234-5678-abcd-ef0123456789",
      "receivingHeaderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "companyId": "9c8b7a6f-1234-5678-abcd-ef0123456789",
      "itemId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "binId": "b9c8d7e6-1234-5678-abcd-ef0123456789",
      "binCode": "A-01-02",
      "itemCode": "ITEM-0042",
      "quantityExpected": 100.0,
      "quantityReceived": 40.0,
      "uom": "EA",
      "createdAt": "2024-06-01T09:00:00Z",
      "postedQuantityReceived": 40.0,
      "remainingQuantity": 60.0,
      "suggestedBinCode": "A-01-02"
    }
  ],
  "hasPrevious": false,
  "hasNext": false
}

data

array

Array of ReceivingLineDto objects.

Show ReceivingLineDto

guid

Unique identifier of the receiving line. Use this as {id} in PUT /api/receivinglines/{id}.

receivingHeaderId

guid

Parent receiving header UUID.

companyId

guid

Company context.

itemId

guid

Internal UUID of the item to be received.

binId

guid | null

Target bin UUID. null if no bin has been assigned yet.

binCode

string

Target bin code, e.g. A-01-02.

itemCode

string

ERP item code.

quantityExpected

decimal

Quantity ordered or expected on this line.

quantityReceived

decimal

Quantity the operator has entered as received (may include not-yet-posted quantities).

uom

string

Unit of measure, e.g. EA, KG.

createdAt

datetime

UTC timestamp when the line was created.

postedQuantityReceived

decimal

Quantity already committed to inventory by a prior posting. Cannot be changed.

remainingQuantity

decimal

Quantity still to be received = quantityExpected − postedQuantityReceived.

suggestedBinCode

string

Recommended target bin code from the system. Defaults to MAIN.

Example

curl "https://your-server/api/receivinglines/by-header/3fa85f64-5717-4562-b3fc-2c963f66afa6?PageNumber=1&PageSize=100" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

GET /api/receivinglines//detail

Returns the full detail record for a single receiving line by its UUID. Use this to refresh a single line after an update without re-fetching the entire header. Method & path: GET /api/receivinglines/{id}/detail
Auth required: Yes

Path parameters

guid

required

UUID of the receiving line.

Response — 200 OK

Returns a single ReceivingLineDto. See ReceivingLineDto fields above.

Example

curl "https://your-server/api/receivinglines/aabbccdd-1234-5678-abcd-ef0123456789/detail" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

PUT /api/receivinglines/

Updates the received quantity and/or target bin assignment for a single receiving line. This is how the handheld operator records how much of each item has physically arrived and where it will be stored. Method & path: PUT /api/receivinglines/{id}
Auth required: Yes

Path parameters

guid

required

UUID of the receiving line to update.

Request body

{
  "quantityReceived": 60.0,
  "binId": "b9c8d7e6-1234-5678-abcd-ef0123456789"
}

quantityReceived

decimal

required

New received quantity for this line. This is the total quantity received so far — not an increment. Must be ≥ 0.

binId

guid | null

Target bin UUID. Pass null to clear the bin assignment or omit to leave unchanged. Obtain valid bin UUIDs from the item inquiry endpoints.

Response — 200 OK

No response body on success.

Error conditions

Status	Condition
`400 Bad Request`	Invalid quantity or unrecognised `binId`.
`404 Not Found`	No receiving line with the given `id`.
`409 Conflict`	Line has already been fully posted and cannot be modified.

Example

curl -X PUT "https://your-server/api/receivinglines/aabbccdd-1234-5678-abcd-ef0123456789" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "quantityReceived": 60.0,
    "binId": "b9c8d7e6-1234-5678-abcd-ef0123456789"
  }'

POST /api/ReceivingHeaders//post

Posts a completed receipt to inventory. This is a non-reversible operation that commits all pending received quantities across every line to on-hand stock. The operator should confirm all quantities and bins are correct before calling this endpoint.

Posting is irreversible. Once a receipt is posted, postedQuantityReceived is updated on every line and remainingQuantity is recalculated. Lines that have already been fully posted cannot be modified.

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

Path parameters

guid

required

UUID of the receiving header to post. Must match an existing, unposted header in the company.

Request body

None. Send an empty body or omit the Content-Type header.

Response — 200 OK

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

Error conditions

Status	Condition
`400 Bad Request`	No lines have a pending quantity to post (nothing to do).
`400 Bad Request`	One or more lines are missing a bin assignment.
`409 Conflict`	The receipt has already been fully posted.
`422 Unprocessable Entity`	Insufficient available stock for one or more items (negative stock not allowed for item).
`404 Not Found`	No receiving header with the given `id`.

Example

curl -X POST "https://your-server/api/ReceivingHeaders/3fa85f64-5717-4562-b3fc-2c963f66afa6/post" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

API Endpoints

Services

Data Models

Receipts Endpoints: Headers, Lines & Posting

GET /api/ReceivingHeaders

Query parameters

Response — 200 OK

Example

GET /api/receivinglines/by-header/

Path parameters

Query parameters

Response — 200 OK

Example

GET /api/receivinglines//detail

Path parameters

Response — 200 OK

Example

PUT /api/receivinglines/

Path parameters

Request body

Response — 200 OK

Error conditions

Example

POST /api/ReceivingHeaders//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/ReceivingHeaders

​Query parameters

​Response — 200 OK

​Example

​GET /api/receivinglines/by-header/

​Path parameters

​Query parameters

​Response — 200 OK

​Example

​GET /api/receivinglines//detail

​Path parameters

​Response — 200 OK

​Example

​PUT /api/receivinglines/

​Path parameters

​Request body

​Response — 200 OK

​Error conditions

​Example

​POST /api/ReceivingHeaders//post

​Path parameters

​Request body

​Response — 200 OK

​Error conditions

​Example

Build docs developers (and LLMs) love

GET /api/ReceivingHeaders

Query parameters

Response — 200 OK

Example

GET /api/receivinglines/by-header/

Path parameters

Query parameters

Response — 200 OK

Example

GET /api/receivinglines//detail

Path parameters

Response — 200 OK

Example

PUT /api/receivinglines/

Path parameters

Request body

Response — 200 OK

Error conditions

Example

POST /api/ReceivingHeaders//post

Path parameters

Request body

Response — 200 OK

Error conditions

Example