Draft a purchase order return

Operation ID: createPurchaseReturnFromPurchaseOrder

Group: Inventory › Purchase Returns

POST /inventory/purchase-returns/from-purchase-order

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

Drafts a return for the returnable lines in a purchase order. The vendor, legal entity, and currency come from the purchase order. Each purchase order line for an item that still has something to return gets one purchase return line:

The quantity is the quantity received on the purchase order line minus the quantity already returned. Only shipped purchase returns count as returned.
For a batch-tracked or serialized item, the line gets the batches or serialized units received on the purchase order line that are not returned yet.

The batches and serialized units are chosen for you, so check them before you approve the purchase return.

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: createPurchaseReturnFromPurchaseOrderInput.

Field	Type	Required	Description
`purchaseOrderId`	string	yes	The unique identifier of the purchase order to create the purchase return from. Format: UUID. See `id` on GET accounting/purchase-orders/:id (getPurchaseOrder). Example: `"c74b1e08-2a95-4f63-b8d1-6e30f9a25c47"`.
`documentDate`	date	no	The date of the purchase return. Format: YYYY-MM-DD. Defaults to today's date in UTC.
`returnType`	string	no	The type of the purchase return. Defaults to 'NORMAL'. 'NORMAL' means the vendor is expected to credit the goods. 'UNCREDITED_REPLACEMENT' means the vendor sends replacement goods, and the quantity can be received again on the purchase order line. 'UNINVOICED_CANCELLATION' means the quantity is canceled from the purchase order before it is invoiced. Shipping an 'UNINVOICED_CANCELLATION' purchase return fails when a line returns more of its purchase order line than is received, not invoiced, and not already canceled. Accepted values: 'NORMAL', 'UNCREDITED_REPLACEMENT', 'UNINVOICED_CANCELLATION'. Example: `"NORMAL"`.

{
  "purchaseOrderId": "c74b1e08-2a95-4f63-b8d1-6e30f9a25c47",
  "documentDate": "2026-01-15",
  "returnType": "NORMAL"
}

Response

200 Success

Under data (createPurchaseReturnFromPurchaseOrderOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the created purchase return. Format: UUID. Example: `"6a1f30c9-4d82-4b57-9e60-83c25f0a71b4"`.
`documentNumber`	string	no	The purchase return number. Example: `"PRTR-1044"`.
`documentStatus`	string	yes	The status of the purchase return. It is always 'DRAFT' on a created purchase return. Example: `"DRAFT"`.
`documentDate`	date	yes	The date of the purchase return. Format: YYYY-MM-DD. Example: `"2026-08-22"`.
`returnType`	string	no	The type of the purchase return. 'NORMAL' means the vendor is expected to credit the goods. 'UNCREDITED_REPLACEMENT' means the vendor sends replacement goods, and the quantity can be received again on the purchase order line. 'UNINVOICED_CANCELLATION' means the quantity is canceled from the purchase order before it is invoiced. Possible values: 'NORMAL', 'UNCREDITED_REPLACEMENT', 'UNINVOICED_CANCELLATION'. Example: `"NORMAL"`.
`entityId`	string	yes	The unique identifier of the legal entity the purchase return belongs to. Format: UUID. See `id` on GET base/entities (entities). Example: `"1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43"`.
`entityName`	string	no	The name of the legal entity the purchase return belongs to.
`businessPartnerId`	string	yes	The unique identifier of the vendor the goods go back to. Format: UUID. See `id` on GET accounting/vendors/:id (getVendor). Example: `"b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6"`.
`businessPartnerName`	string	no	The name of the vendor the goods go back to.
`currency`	string	no	The currency of the purchase return's amounts. Format: ISO 4217. Example: `"EUR"`.
`totalAmount`	decimal	no	The total value of the purchase return, in its currency. It is the sum, over all lines, of each line's `unitPrice` multiplied by its `quantity`. Absent until the purchase return is shipped.
`notes`	string	no	Notes on the purchase return.
`lines`	array<object>	yes	The lines of the purchase return, one for each purchase order line for an item with a quantity still to return. Example: `[{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","quantity":"30.00","sourceDocumentLineId":"a3e7c915-62d4-4f08-b1a9-7d5c24e8f063","sourceDocumentLineType":"PurchaseOrderLine"}]`.
`lines[].id`	string	yes	The unique identifier for the line. Format: UUID. Use it in `updateLines` and `deleteLines`.
`lines[].itemId`	string	no	The unique identifier of the item being returned. Format: UUID. See `id` on GET inventory/items/:id (getItem).
`lines[].itemCode`	string	no	The code of the item being returned.
`lines[].itemName`	string	no	The name of the item being returned.
`lines[].locationId`	string	no	The unique identifier of the warehouse that the stock on this line leaves from. Format: UUID. It is the warehouse that the purchase order line was received into, taken from a committed receipt for that line. See `id` on GET inventory/warehouses/:id (getWarehouse).
`lines[].locationCode`	string	no	The code of the warehouse that the stock on this line leaves from.
`lines[].unitId`	string	no	The unique identifier of the unit of measure for the line's quantity. Format: UUID. See `id` on GET inventory/unit-of-measures/:id (getUnitOfMeasure).
`lines[].quantity`	decimal	no	The quantity to return, in the line's unit of measure. It is the quantity received on the purchase order line minus the quantity already returned. For a batch-tracked or serialized item, it is no more than the batches or serialized units that are still available to return.
`lines[].unitPrice`	decimal	no	The price of one unit, in the purchase return's currency. It is the purchase order line's price.
`lines[].sourceDocumentLineId`	string	no	The unique identifier of the purchase order line this line returns goods from. Format: UUID. See `lines[].id` on GET accounting/purchase-orders/:id (getPurchaseOrder).
`lines[].sourceDocumentLineType`	string	no	The type of line that `sourceDocumentLineId` points to. It is always 'PurchaseOrderLine'.
`lines[].batches`	array<object>	no	The batches chosen for this purchase return line. They come from the batches received on the purchase order line that have not been returned yet.
`lines[].batches[].batchNumberId`	string	no	The unique identifier of the batch being returned. Format: UUID. See `id` on GET inventory/batch-numbers/:id (getBatchNumber).
`lines[].batches[].batchNumber`	string	yes	The batch number of the batch being returned.
`lines[].batches[].quantity`	decimal	yes	The quantity of the batch being returned, in the item's stocking unit.
`lines[].serials`	array<object>	no	The serialized units chosen for this purchase return line. They come from the units received on the purchase order line that have not been returned yet.
`lines[].serials[].serialNumberId`	string	no	The unique identifier of the serialized unit being returned. Format: UUID. See `id` on GET inventory/serial-numbers/:id (getSerialNumber).
`lines[].serials[].serialNumber`	string	yes	The serial number of the unit being returned.

{
  "data": {
    "id": "6a1f30c9-4d82-4b57-9e60-83c25f0a71b4",
    "documentNumber": "PRTR-1044",
    "documentStatus": "DRAFT",
    "documentDate": "2026-08-22",
    "returnType": "NORMAL",
    "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
    "entityName": "<entityName>",
    "businessPartnerId": "b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6",
    "businessPartnerName": "<businessPartnerName>",
    "currency": "EUR",
    "totalAmount": "19.99",
    "notes": "<notes>",
    "lines": [
      {
        "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
        "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
        "quantity": "30.00",
        "sourceDocumentLineId": "a3e7c915-62d4-4f08-b1a9-7d5c24e8f063",
        "sourceDocumentLineType": "PurchaseOrderLine"
      }
    ]
  },
  "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
`NOTHING_RETURNABLE`	400
`POSTING_REJECTED`	400
`IDEMPOTENCY_KEY_CONFLICT`	409
`IDEMPOTENCY_PAYLOAD_MISMATCH`	422

Statuses

400 — Invalid request or business failure. Codes: REFERENCE_NOT_FOUND, NOTHING_RETURNABLE, 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