Create a receipt

Operation ID: createReceipt

Group: Inventory › Receipts

POST /inventory/receipts

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Creates a receipt in draft status. No stock is brought in and no journal entry is created for the accrual until you commit the receipt with POST inventory/receipts/:id/commit.

Every line's warehouse must belong to the receipt's legal entity. Otherwise the request fails with LOCATION_ENTITY_MISMATCH.

The response is the created receipt, with the same fields GET inventory/receipts/:id returns.

Parameters

Name	In	Type	Required	Description
`Api-Version`	header	string · v1	yes	The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`.
`Idempotency-Key`	header	string	no	An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with `400 IDEMPOTENCY_NOT_SUPPORTED` rather than silently ignored.

Request body

Required, application/json: createReceiptInput.

Field	Type	Required	Description
`businessPartnerId`	string	yes	The vendor the goods came from. Required. Example: `"b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6"`.
`entityId`	string	no	The legal entity. Omit it and the first line's warehouse decides it, but a receipt of only Service or Expense lines has no warehouse, so send it for those. Every line's locationId must belong to this entity or the request fails with LOCATION_ENTITY_MISMATCH.
`documentDate`	date	no	The date of the receipt. Use format YYYY-MM-DD. Defaults to today. Example: `"2026-08-14"`.
`deliveryDate`	date	no	The date the goods arrived. Use format YYYY-MM-DD. Example: `"2026-08-14"`.
`currency`	string	no	The currency for every amount on the receipt. Format ISO 4217, for example 'EUR'. Defaults to the vendor's or the entity's, as the platform resolves it. Example: `"EUR"`.
`referenceNumber`	string	no	The vendor's own reference, typically their delivery note number. Example: `"DN-77120"`.
`trackingNumber`	string	no	The carrier's tracking number for the inbound shipment. Free text: no format check, and no lookup against a carrier.
`notes`	string	no	Free text on the document. Example: `"Received at the back dock"`.
`lines`	array<object>	yes	The lines of the receipt. At least one is required. Example: `[{"lineType":"Inventory","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","unitId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","quantity":"200.00","unitPrice":"3.20","sourceDocumentLineId":"551043","notes":"Two pallets"},{"lineType":"Service","serviceDescription":"Inbound freight","lineTotal":"85.00","expenseAccountId":"4b7c0e29-6d15-4830-9f42-8a3e57c1d604"}]`.
`lines[].lineType`	any	no	What this line receives. Defaults to Inventory. An Inventory line needs itemId, unitId, locationId and quantity, because it moves stock into a warehouse. A Service or Expense line needs serviceDescription and an amount, and has no item or warehouse. A line with a description and no item is taken as a Service line. One of: `"Inventory"`, `"Service"`, `"Expense"`.
`lines[].itemId`	string	no	The item received. Required on an Inventory line, and not used on a Service or Expense line.
`lines[].serviceDescription`	string	no	What was bought. Required on a Service or Expense line, and not used on an Inventory line.
`lines[].locationId`	string	no	The warehouse the goods go into. Required on an Inventory line, and it must belong to the receipt's legal entity.
`lines[].unitId`	string	no	The unit the quantity is counted in. Required on an Inventory line.
`lines[].quantity`	decimal	no	The quantity received, in that unit. Required on an Inventory line, and greater than zero.
`lines[].unitPrice`	decimal	no	The price of one unit, in the receipt's currency.
`lines[].lineTotal`	decimal	no	The total for the line, in the receipt's currency. Leave it out to have it calculated as quantity × unitPrice, rounded to the currency's decimals. When quantity and unitPrice are also given it must equal that, once rounded the same way, or the request fails with LINE_TOTAL_MISMATCH. On a Service or Expense line without a quantity or unitPrice it is taken as given, and such a line needs this or a unitPrice.
`lines[].expenseAccountId`	string	no	The general ledger account to charge. Required on a Service or Expense line, or the request fails with INCOMPLETE_LINE. Not used on an Inventory line.
`lines[].sourceDocumentLineId`	string	no	The purchase order line this line receives against, as its id under lines on GET accounting/purchase-orders/:id. Its numeric id in string form is also accepted. The line type is set from it.
`lines[].notes`	string	no	Free text on the line.
`lines[].batches`	array<object>	no	The batches received on this line. Required for a batch-tracked item, and the quantities must add up to the line's quantity. When you send it on update, it replaces the line's batches.
`lines[].batches[].batchNumberId`	string	no	The unique identifier of the batch, when it already exists. Optional: the number decides the lot. Given, it must be the batch batchNumber names for the item in this warehouse.
`lines[].batches[].batchNumber`	string	no	The batch number as printed. Required. It names the lot within the item and the warehouse, and a number new to both creates the batch record.
`lines[].batches[].expirationDate`	date	no	The expiration date of the batch. Format YYYY-MM-DD.
`lines[].batches[].quantity`	decimal	yes	The quantity of this batch received, in the line's unit. The batch quantities of a line must add up to the line's quantity.
`lines[].serials`	array<object>	no	The serialized units received, one entry per unit. Required for a serialized item, and the count must equal the line's quantity. When you send it on update, it replaces the line's serials.
`lines[].serials[].serialNumberId`	string	no	The unique identifier of the unit, when it already exists. Optional: the number decides the unit. Given, it must be the unit serialNumber names for the item in this warehouse.
`lines[].serials[].serialNumber`	string	no	The serial number stamped on the unit. Required. It names the unit within the item and the warehouse, and a number new to both creates the serial record.
`lines[].binLocations`	array<object>	no	The bins the goods go into, in a bin-tracked warehouse. One flat array, where an entry may name a batchNumber or serialNumber of its own line. When you send it on update, it replaces the line's bin entries.
`lines[].binLocations[].binLocationId`	string	yes	The bin the goods go into.
`lines[].binLocations[].quantity`	decimal	yes	The quantity going into this bin, in the line's unit.
`lines[].binLocations[].batchNumber`	string	no	Names one of this line's batches, when the bin entry belongs to it.
`lines[].binLocations[].serialNumber`	string	no	Names one of this line's serialized units, when the bin entry belongs to it.

{
  "businessPartnerId": "b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "documentDate": "2026-08-14",
  "deliveryDate": "2026-08-14",
  "currency": "EUR",
  "referenceNumber": "DN-77120",
  "trackingNumber": "<trackingNumber>",
  "notes": "Received at the back dock",
  "lines": [
    {
      "lineType": "Inventory",
      "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
      "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
      "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
      "quantity": "200.00",
      "unitPrice": "3.20",
      "sourceDocumentLineId": "551043",
      "notes": "Two pallets"
    },
    {
      "lineType": "Service",
      "serviceDescription": "Inbound freight",
      "lineTotal": "85.00",
      "expenseAccountId": "4b7c0e29-6d15-4830-9f42-8a3e57c1d604"
    }
  ]
}

Response

200 Success

Under data (createReceiptOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the receipt. Example: `"6a1f30c9-4d82-4b57-9e60-83c25f0a71b4"`.
`documentNumber`	string	no	The receipt number, for example 'GR-2291'. Assigned when the receipt is created. Example: `"GR-2291"`.
`documentStatus`	string	yes	The status of the receipt. It is DRAFT when the receipt is created through this API and COMMITTED once you commit it with POST inventory/receipts/:id/commit. The receiving and invoicing processes set the other statuses. Example: `"DRAFT"`.
`documentDate`	date	yes	The date of the receipt. Format YYYY-MM-DD. Example: `"2026-08-14"`.
`deliveryDate`	date	no	The date the goods arrived or are expected. Format YYYY-MM-DD. Example: `"2026-08-14"`.
`entityId`	string	yes	The legal entity the receipt belongs to. Example: `"1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43"`.
`entityName`	string	no	The name of that legal entity. Example: `"Acme Netherlands B.V."`.
`businessPartnerId`	string	yes	The vendor the goods came from. Example: `"b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6"`.
`businessPartnerName`	string	no	The name of that vendor. Example: `"Van Dijk Components B.V."`.
`referenceNumber`	string	no	The vendor's own reference, typically their delivery note number. Example: `"DN-77120"`.
`trackingNumber`	string	no	The carrier's tracking number for the inbound shipment.
`currency`	string	no	ISO 4217 code governing every amount on the document. The VENDOR's currency, which need not be the entity's functional one — see functionalUnitPrice on the line. Example: `"EUR"`.
`totalAmount`	decimal	no	The total value of the receipt, in the receipt's currency. Example: `"725.00"`.
`notes`	string	no	Free text on the receipt. Example: `"Received at the back dock"`.
`createdDate`	date-time	no	The date and time the receipt was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T09:20:00.000Z"`.
`lastModifiedDate`	date-time	no	The date and time the receipt last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T09:20:00.000Z"`.
`lines`	array<object>	yes	The lines of the receipt, oldest first. A receipt always has at least one line. Example: [{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","lineType":"Inventory","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","itemCode":"WIDGET-01","itemName":"Standard widget","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","locationCode":"WH-01","locationName":"Rotterdam Distribution Centre","unitId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","unitCode":"EA","quantity":"200.00","inventoryQuantity":"200.00","openQuantity":"200.00","unitPrice":"3.20","lineTotal":"640.00","sourceDocumentLineId":"551043","sourceDocumentLineType":"PurchaseOrderLine","notes":"Two pallets"},{"id":"d0a7e3b5-2f61-4c98-b704-1a5e9c86d243","lineType":"Service","serviceDescription":"Inbound freight","lineTotal":"85.00","expenseAccountId":"4b7c0e29-6d15-4830-9f42-8a3e57c1d604","expenseAccountNumber":"615200","expenseAccountName":"Inbound freight"}].
`lines[].id`	string	yes	The unique identifier for the line. Use it in updateLines and deleteLines.
`lines[].lineType`	string	no	The type of the line. Possible values: 'Inventory', 'Service', 'Expense'. Only an Inventory line moves stock. A Service or Expense line records something bought that does not enter a warehouse and has a description instead of an item.
`lines[].itemId`	string	no	The item received. Absent on a Service or Expense line.
`lines[].itemCode`	string	no	The short code of that item.
`lines[].itemName`	string	no	The name of that item.
`lines[].serviceDescription`	string	no	What a Service or Expense line is for. Absent on an Inventory line.
`lines[].locationId`	string	no	The warehouse the goods went into. Absent on a Service or Expense line.
`lines[].locationCode`	string	no	The short code of that warehouse.
`lines[].locationName`	string	no	The name of that warehouse.
`lines[].unitId`	string	no	The unit the quantity is counted in.
`lines[].unitCode`	string	no	The short code of that unit.
`lines[].quantity`	decimal	no	The quantity received, in the line's unit.
`lines[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].receivedQuantity`	decimal	no	The quantity actually received, where the receiving process records it separately.
`lines[].openQuantity`	decimal	no	The quantity still to be invoiced.
`lines[].returnedQuantity`	decimal	no	The quantity that has gone back on a purchase return.
`lines[].unitPrice`	decimal	no	The price of one unit, in the receipt's currency.
`lines[].lineTotal`	decimal	no	The total for the line, in the receipt's currency.
`lines[].functionalUnitPrice`	decimal	no	The unit price in the entity's functional currency. Present when the receipt is in another currency.
`lines[].functionalLineTotal`	decimal	no	The line total in the entity's functional currency.
`lines[].expenseAccountId`	string	no	The general ledger account a Service or Expense line is charged to. Absent on an Inventory line.
`lines[].expenseAccountNumber`	string	no	The number of that account.
`lines[].expenseAccountName`	string	no	The name of that account.
`lines[].status`	string	no	Where the line is in the receiving process. This is free text, with no fixed set of values.
`lines[].sourceDocumentLineId`	string	no	The purchase order line this line was received against. It is a numeric id in string form, not a UUID. Purchase order lines are not individually addressable, so there is no endpoint that takes it.
`lines[].sourceDocumentLineType`	any	no	The kind of source document line this receipt line was created from. One of: `"IMInventorySalesOrderLine"`, `"IMInventorySalesDeliveryLine"`, `"IMSalesOrderLine"`, `"IMInventoryPurchaseReturnLine"`, `"IMInventorySalesReturnLine"`, `"IMWarehouseTransferLine"`, `"IMInventoryDecreaseLine"`, `"IMInventoryIncreaseLine"`, `"IMInventoryRevaluationLine"`, `"IMInventoryTransferLine"`, `"IMInventoryAdjustmentLine"`, `"IMInventoryCountLine"`, `"IMInventoryPutAwayTask"`, `"IMInventoryPurchaseReturnReversal"`, `"PurchaseOrderLine"`, `"IMLandedCostAllocationLine"`, `"SalesOrderProductItem"`, `"IMWarehouseTransferOrderLine"`, `"VendorBillItemBase"`, `"InvPurchaseDeliveryLine"`.
`lines[].notes`	string	no	Free text on the line.
`lines[].batches`	array<object>	no	The batches received on this line, for a batch-tracked item. Absent when the item is not batch-tracked.
`lines[].batches[].batchNumberId`	string	no	The unique identifier for the batch record this entry created or matched.
`lines[].batches[].batchNumber`	string	yes	The batch number as printed.
`lines[].batches[].expirationDate`	date	no	The expiration date of the batch. Format YYYY-MM-DD.
`lines[].batches[].quantity`	decimal	yes	The quantity of this batch received, in the line's unit.
`lines[].batches[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].batches[].openQuantity`	decimal	no	The quantity of this batch still to be invoiced.
`lines[].batches[].returnedQuantity`	decimal	no	The quantity of this batch that has gone back to the vendor.
`lines[].batches[].unitCost`	decimal	no	The cost of one unit of this batch, in the receipt's currency.
`lines[].serials`	array<object>	no	The serialized units received, one entry per unit. Absent when the item is not serialized.
`lines[].serials[].serialNumberId`	string	no	The unique identifier for the serial record this entry created or matched.
`lines[].serials[].serialNumber`	string	yes	The serial number as stamped on the unit.
`lines[].serials[].openQuantity`	decimal	no	The quantity of this unit still to be invoiced.
`lines[].serials[].returnedQuantity`	decimal	no	The quantity of this unit that has gone back to the vendor.
`lines[].serials[].unitCost`	decimal	no	The cost of this unit, in the receipt's currency.
`lines[].binLocations`	array<object>	no	The bins the goods went into, in a bin-tracked warehouse. One flat array per line: an entry that names a batchNumber or serialNumber belongs to that batch or unit, and one that names neither belongs to the line.
`lines[].binLocations[].binLocationId`	string	yes	The bin the goods went into.
`lines[].binLocations[].binLocationCode`	string	no	The short code of that bin.
`lines[].binLocations[].quantity`	decimal	yes	The quantity put into this bin, in the line's unit.
`lines[].binLocations[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].binLocations[].batchNumber`	string	no	The batch this bin entry belongs to, when it belongs to one of the line's batches.
`lines[].binLocations[].serialNumber`	string	no	The serialized unit this bin entry belongs to, when it belongs to one of the line's units.

{
  "data": {
    "id": "6a1f30c9-4d82-4b57-9e60-83c25f0a71b4",
    "documentNumber": "GR-2291",
    "documentStatus": "DRAFT",
    "documentDate": "2026-08-14",
    "deliveryDate": "2026-08-14",
    "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
    "entityName": "Acme Netherlands B.V.",
    "businessPartnerId": "b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6",
    "businessPartnerName": "Van Dijk Components B.V.",
    "referenceNumber": "DN-77120",
    "trackingNumber": "<trackingNumber>",
    "currency": "EUR",
    "totalAmount": "725.00",
    "notes": "Received at the back dock",
    "createdDate": "2026-08-14T09:20:00.000Z",
    "lastModifiedDate": "2026-08-14T09:20:00.000Z",
    "lines": [
      {
        "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
        "lineType": "Inventory",
        "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
        "itemCode": "WIDGET-01",
        "itemName": "Standard widget",
        "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
        "locationCode": "WH-01",
        "locationName": "Rotterdam Distribution Centre",
        "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
        "unitCode": "EA",
        "quantity": "200.00",
        "inventoryQuantity": "200.00",
        "openQuantity": "200.00",
        "unitPrice": "3.20",
        "lineTotal": "640.00",
        "sourceDocumentLineId": "551043",
        "sourceDocumentLineType": "PurchaseOrderLine",
        "notes": "Two pallets"
      },
      {
        "id": "d0a7e3b5-2f61-4c98-b704-1a5e9c86d243",
        "lineType": "Service",
        "serviceDescription": "Inbound freight",
        "lineTotal": "85.00",
        "expenseAccountId": "4b7c0e29-6d15-4830-9f42-8a3e57c1d604",
        "expenseAccountNumber": "615200",
        "expenseAccountName": "Inbound freight"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Idempotency-Replayed — Present and true only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as false.

Errors

Code	Status
`REFERENCE_NOT_FOUND`	400
`NO_LINES`	400
`INVALID_QUANTITY`	400
`LINE_TOTAL_MISMATCH`	400
`INCOMPLETE_LINE`	400
`DUPLICATE_TRACKING_NUMBER`	400
`UNKNOWN_TRACKING_REFERENCE`	400
`LOCATION_ENTITY_MISMATCH`	400
`POSTING_REJECTED`	400
`IDEMPOTENCY_KEY_CONFLICT`	409
`IDEMPOTENCY_PAYLOAD_MISMATCH`	422

Statuses

400 — Invalid request or business failure. Codes: REFERENCE_NOT_FOUND, NO_LINES, INVALID_QUANTITY, LINE_TOTAL_MISMATCH, INCOMPLETE_LINE, DUPLICATE_TRACKING_NUMBER, UNKNOWN_TRACKING_REFERENCE, LOCATION_ENTITY_MISMATCH, POSTING_REJECTED
401 — The request carries no valid access token.
403 — Not authorized
404 — Not found
409 — The Idempotency-Key is still being processed by another request.
422 — The Idempotency-Key was already used with a different request payload.
429 — Too many requests from this client address. The response has no body and no Retry-After header.
500 — Internal server error