Skip to content
HeyX API

Inventory Receipt Lifecycle

All paths use POST /public-api/publicapi.v1.Inventory/. Mutations require inventory write access; recovery reads require inventory read access. Exact API-key scopes apply separately: inventory_receipt:create for draft creation, inventory_receipt:update for line addition, inventory_receipt:post for receiving, and inventory:read for get.

Stock changes only when ReceiveInventory posts the receipt. Creating a draft and adding lines do not increase on-hand or available stock. Add every line before posting. This API does not support receipt editing/deletion, backorder linkage, evidence uploads, or partner inventory.

CreateInventoryReceipt

Section titled “CreateInventoryReceipt”
{
  "locationId": "<inventory-location-id>",
  "reference": "Delivery 2026-09-06",
  "idempotencyKey": "receipt-2026-09-06-001"
}

Returns receiptId and status. Reference is optional, maximum 200 characters; notes maximum 2,000. The nonblank key is required, maximum 200 characters. Reusing the same workspace-scoped draft key with the same payload returns the existing receipt; changed input conflicts.

Generated Reference
POST /public-api/publicapi.v1.Inventory/CreateInventoryReceipt

Receiving is a lifecycle: create a draft, add lines, then ReceiveInventory. Draft and line keys are workspace-scoped; changed payloads conflict.

Request CreateInventoryReceiptRequest
Response CreateInventoryReceiptResponse

CreateInventoryReceiptRequest

Field Type
location_id string
reference string
notes string
idempotency_key string

CreateInventoryReceiptResponse

Field Type
receipt_id string
status string

AddInventoryReceiptLine

Section titled “AddInventoryReceiptLine”
{
  "receiptId": "<receipt-id>",
  "productId": "<product-id>",
  "quantity": "4",
  "idempotencyKey": "receipt-2026-09-06-001-line-1"
}

Quantity must be a positive integer. Optional notes are limited to 1,000 characters. Returns lineId. Each intended line needs its own nonblank key, maximum 200 characters. Line keys are workspace-scoped: do not reuse one for a different receipt/product/quantity. Identical retries recover the original line; changed payloads conflict. New lines cannot be added after posting.

Generated Reference
POST /public-api/publicapi.v1.Inventory/AddInventoryReceiptLine
Request AddInventoryReceiptLineRequest
Response AddInventoryReceiptLineResponse

AddInventoryReceiptLineRequest

Field Type
receipt_id string
product_id string
quantity int64
notes string
idempotency_key string

AddInventoryReceiptLineResponse

Field Type
line_id string

ReceiveInventory

Section titled “ReceiveInventory”
{ "receiptId": "<receipt-id>" }

Posts the existing draft atomically, applying its stock movements. Returns receiptId, status, and postedAt (Unix seconds as an int64 JSON string). Repeating an already-posted receipt is safe and must not add stock twice. This is the receiving action, not an adjustment or a request to create another draft.

Generated Reference
POST /public-api/publicapi.v1.Inventory/ReceiveInventory

Posts an existing draft atomically. Repeating a posted receipt is safe. Add all lines before posting. No backorder linkage or evidence upload here.

Request ReceiveInventoryRequest
Response ReceiveInventoryResponse

ReceiveInventoryRequest

Field Type
receipt_id string

ReceiveInventoryResponse

Field Type
receipt_id string
status string
posted_at int64

GetInventoryReceipt

Section titled “GetInventoryReceipt”
{ "receiptId": "<receipt-id>", "page": 1, "pageSize": 25 }

Supply exactly one lookup: receiptId or the draft-creation idempotencyKey. The latter recovers a receipt after a lost creation response; it is not a line key. Returns receipt and lines. Page defaults to 1, maximum 100,000; size defaults to 25, maximum 100. Increment page while hasMore is true. Lines are ordered by creation time then ID.

Reference/notes are bounded to 200/2,000 characters with textTruncated; line notes to 1,000 with notesTruncated. Missing/foreign receipt IDs return no data. Inspect the recovered receipt before changing keys or posting an uncertain draft.

Generated Reference
POST /public-api/publicapi.v1.Inventory/GetInventoryReceipt

Bounded recovery read by receipt ID or its draft-creation idempotency key.

Request GetInventoryReceiptRequest
Response GetInventoryReceiptResponse

GetInventoryReceiptRequest

Field Type
receipt_id string
idempotency_key string
page int32
page_size int32

GetInventoryReceiptResponse

Field Type
receipt InventoryReceipt
lines repeated InventoryReceiptLine
page int32
page_size int32
has_more bool

Related Types

InventoryReceipt

Field Type
id string
location_id string
reference string
notes string
text_truncated bool
status string
posted_at int64
created_at int64

InventoryReceiptLine

Field Type
id string
product_id string
quantity int64
notes string
notes_truncated bool
HeyX API