Update a purchase return

Operation ID: updatePurchaseReturn

Group: Inventory › Purchase Returns

PATCH /inventory/purchase-returns/{id}

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

Updates a purchase return with the fields you send. A field you leave out keeps its current value. Only a purchase return with the documentStatus 'DRAFT' can be updated.

To change lines, use updateLines, createLines, and deleteLines. The response contains the whole 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.
`id`	path	string	yes	The unique identifier of the purchase return you want to update. Format: UUID. Example: `"6a1f30c9-4d82-4b57-9e60-83c25f0a71b4"`.

Request body

Required, application/json: updatePurchaseReturnInput.

Field	Type	Required	Description
`documentDate`	date	no	The date of the purchase return. Format: YYYY-MM-DD.
`referenceNumber`	string	no	The reference number of the purchase return.
`notes`	string	no	Notes on the purchase return. Example: `"Vendor agreed collection for Friday"`.
`updateLines`	array<object>	no	The purchase return lines to change, each identified by its `id`. A field you leave out keeps its current value. The exceptions are `batches`, `serials`, and `binLocations`, which are replaced as a set. When you send any of them, send all three, with every entry the line should have. Example: `[{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","quantity":"25.00"}]`.
`updateLines[].id`	string	yes	The unique identifier of the line you want to change. Format: UUID.
`updateLines[].itemId`	string	no	The unique identifier of the item being returned. Format: UUID. See `id` on GET inventory/items/:id (getItem).
`updateLines[].locationId`	string	no	The unique identifier of the warehouse that the stock on this line leaves from. Format: UUID. It must belong to the purchase return's legal entity. See `id` on GET inventory/warehouses/:id (getWarehouse).
`updateLines[].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).
`updateLines[].quantity`	decimal	no	The quantity to return, in the line's unit of measure. It must be greater than zero.
`updateLines[].unitPrice`	decimal	no	The price of one unit, in the purchase return's currency. It can be zero, but not less than zero.
`updateLines[].notes`	string	no	Notes on the line.
`updateLines[].batches`	array<object>	no	The batches being returned.
`updateLines[].batches[].batchNumberId`	string	no	The unique identifier of the batch being returned. Format: UUID. See `id` on GET inventory/batch-numbers/:id (getBatchNumber).
`updateLines[].batches[].batchNumber`	string	no	The batch number of the batch being returned. To identify the batch, send `batchNumberId`. To take this batch from a bin, send the same value in `binLocations[].batchNumber`.
`updateLines[].batches[].quantity`	decimal	yes	The quantity of the batch to return, in the item's stocking unit. It must be greater than zero.
`updateLines[].serials`	array<object>	no	The serialized units being returned, one entry for each unit.
`updateLines[].serials[].serialNumberId`	string	no	The unique identifier of the serialized unit being returned. Format: UUID. See `id` on GET inventory/serial-numbers/:id (getSerialNumber).
`updateLines[].serials[].serialNumber`	string	no	The serial number of the unit being returned. To identify the unit, send `serialNumberId`. To take this unit from a bin, send the same value in `binLocations[].serialNumber`.
`updateLines[].binLocations`	array<object>	no	The bins to take the stock on this purchase return line from, with the quantity to take from each bin. An entry with a `batchNumber` or `serialNumber` is for that batch or serialized unit. An entry with neither is for part of the line's quantity, not a particular batch or serialized unit.
`updateLines[].binLocations[].binLocationId`	string	yes	The unique identifier of the bin the stock is taken from. Format: UUID. See `id` on GET inventory/bins/:id (getBin).
`updateLines[].binLocations[].quantity`	decimal	yes	The quantity taken from the bin, in the item's stocking unit.
`updateLines[].binLocations[].batchNumber`	string	no	The batch number of the batch this bin quantity is for. It must match the `batchNumber` of one of the line's batches.
`updateLines[].binLocations[].serialNumber`	string	no	The serial number of the unit this bin quantity is for. It must match the `serialNumber` of one of the line's serials.
`createLines`	array<object>	no	The lines to add to the purchase return.
`createLines[].itemId`	string	yes	The unique identifier of the item being returned. Format: UUID. See `id` on GET inventory/items/:id (getItem).
`createLines[].locationId`	string	yes	The unique identifier of the warehouse that the stock on this line leaves from. Format: UUID. It must belong to the purchase return's legal entity. See `id` on GET inventory/warehouses/:id (getWarehouse).
`createLines[].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).
`createLines[].quantity`	decimal	yes	The quantity to return, in the line's unit of measure. It must be greater than zero.
`createLines[].unitPrice`	decimal	no	The price of one unit, in the purchase return's currency. It can be zero, but not less than zero.
`createLines[].sourceDocumentLineId`	string	no	The identifier of the receipt line or purchase order line that this line returns goods from. Send the line's unique identifier or its numeric `id`. Set `sourceDocumentLineType` to say which kind of line it is. See `lines[].id` on GET inventory/receipts/:id (getReceipt) or GET accounting/purchase-orders/:id (getPurchaseOrder).
`createLines[].sourceDocumentLineType`	string	no	The type of line that `sourceDocumentLineId` points to. Defaults to 'InvPurchaseDeliveryLine'. Accepted values: 'InvPurchaseDeliveryLine' (a receipt line), 'PurchaseOrderLine' (a purchase order line).
`createLines[].notes`	string	no	Notes on the line.
`createLines[].batches`	array<object>	no	The batches being returned. Required when the item is batch-tracked.
`createLines[].batches[].batchNumberId`	string	no	The unique identifier of the batch being returned. Format: UUID. See `id` on GET inventory/batch-numbers/:id (getBatchNumber).
`createLines[].batches[].batchNumber`	string	no	The batch number of the batch being returned. To identify the batch, send `batchNumberId`. To take this batch from a bin, send the same value in `binLocations[].batchNumber`.
`createLines[].batches[].quantity`	decimal	yes	The quantity of the batch to return, in the item's stocking unit. It must be greater than zero.
`createLines[].serials`	array<object>	no	The serialized units being returned, one entry for each unit. Required when the item is serialized.
`createLines[].serials[].serialNumberId`	string	no	The unique identifier of the serialized unit being returned. Format: UUID. See `id` on GET inventory/serial-numbers/:id (getSerialNumber).
`createLines[].serials[].serialNumber`	string	no	The serial number of the unit being returned. To identify the unit, send `serialNumberId`. To take this unit from a bin, send the same value in `binLocations[].serialNumber`.
`createLines[].binLocations`	array<object>	no	The bins to take the stock on this purchase return line from, with the quantity to take from each bin. An entry with a `batchNumber` or `serialNumber` is for that batch or serialized unit. An entry with neither is for part of the line's quantity, not a particular batch or serialized unit.
`createLines[].binLocations[].binLocationId`	string	yes	The unique identifier of the bin the stock is taken from. Format: UUID. See `id` on GET inventory/bins/:id (getBin).
`createLines[].binLocations[].quantity`	decimal	yes	The quantity taken from the bin, in the item's stocking unit.
`createLines[].binLocations[].batchNumber`	string	no	The batch number of the batch this bin quantity is for. It must match the `batchNumber` of one of the line's batches.
`createLines[].binLocations[].serialNumber`	string	no	The serial number of the unit this bin quantity is for. It must match the `serialNumber` of one of the line's serials.
`deleteLines`	array<string>	no	The unique identifiers of the purchase return lines to remove. Format: UUID. Each identifier must be the `id` of a line of this purchase return. Example: `["d0a7e3b5-2f61-4c98-b704-1a5e9c86d243"]`.

{
  "documentDate": "2026-01-15",
  "referenceNumber": "<referenceNumber>",
  "notes": "Vendor agreed collection for Friday",
  "updateLines": [
    {
      "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
      "quantity": "25.00"
    }
  ],
  "createLines": [
    {
      "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "locationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "unitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": "19.99",
      "unitPrice": "19.99",
      "sourceDocumentLineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sourceDocumentLineType": "<sourceDocumentLineType>",
      "notes": "<notes>",
      "batches": [
        {
          "batchNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "batchNumber": "<batchNumber>",
          "quantity": "19.99"
        }
      ],
      "serials": [
        {
          "serialNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "serialNumber": "<serialNumber>"
        }
      ],
      "binLocations": [
        {
          "binLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "quantity": "19.99",
          "batchNumber": "<batchNumber>",
          "serialNumber": "<serialNumber>"
        }
      ]
    }
  ],
  "deleteLines": [
    "d0a7e3b5-2f61-4c98-b704-1a5e9c86d243"
  ]
}

Response

200 Success

Under data (updatePurchaseReturnOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the purchase return. Format: UUID. Example: `"6a1f30c9-4d82-4b57-9e60-83c25f0a71b4"`.
`documentNumber`	string	no	The purchase return number. Example: `"PRTR-1043"`.
`documentStatus`	string	yes	The status of the purchase return. It is always 'DRAFT', because only a draft can be updated. Example: `"DRAFT"`.
`documentDate`	date	yes	The date of the purchase return. Format: YYYY-MM-DD. Example: `"2026-08-20"`.
`deliveryDate`	date	no	The delivery date of the purchase return. Format: YYYY-MM-DD.
`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'.
`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.
`referenceNumber`	string	no	The reference number of the purchase return.
`originalReceiptId`	string	no	The unique identifier of the receipt the purchase return was created against. Format: UUID. See `id` on GET inventory/receipts/:id (getReceipt).
`currency`	string	no	The currency of the purchase return's amounts. Format: ISO 4217.
`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. Example: `"Vendor agreed collection for Friday"`.
`createdDate`	date-time	no	The date and time the purchase return was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ.
`lastModifiedDate`	date-time	no	The date and time the purchase return last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ.
`lines`	array<object>	yes	The lines of the purchase return. Example: `[{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","quantity":"25.00"}]`.
`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. 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[].locationName`	string	no	The name 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[].unitCode`	string	no	The code of the unit of measure for the line's quantity.
`lines[].quantity`	decimal	no	The quantity being returned, in the line's unit of measure.
`lines[].inventoryQuantity`	decimal	no	The quantity being returned, in the item's stocking unit.
`lines[].openQuantity`	decimal	no	The quantity of the line still outstanding, in the line's unit of measure.
`lines[].unitPrice`	decimal	no	The price of one unit, in the purchase return's currency.
`lines[].functionalUnitPrice`	decimal	no	The price of one unit, in the legal entity's functional currency. It is `functionalLineTotal` divided by `quantity`. Absent until the purchase return is shipped, and on lines whose `sourceDocumentLineType` is not 'PurchaseOrderLine'.
`lines[].functionalLineTotal`	decimal	no	The total of the line, in the legal entity's functional currency. It is calculated from the receipts the quantity was taken from, at their original prices. Absent until the purchase return is shipped, and on lines whose `sourceDocumentLineType` is not 'PurchaseOrderLine'.
`lines[].status`	string	no	The status of the line. It is 'PENDING' until the purchase return is shipped, and 'SHIPPED' after.
`lines[].sourceDocumentLineId`	string	no	The unique identifier of the receipt line or purchase order line that this line returns goods from. Format: UUID. `sourceDocumentLineType` says whether it is a receipt line or a purchase order line. See `lines[].id` on GET inventory/receipts/:id (getReceipt) or GET accounting/purchase-orders/:id (getPurchaseOrder).
`lines[].sourceDocumentLineType`	string	no	The type of line that `sourceDocumentLineId` points to. Possible values: 'InvPurchaseDeliveryLine' (a receipt line), 'PurchaseOrderLine' (a purchase order line).
`lines[].notes`	string	no	Notes on the line.
`lines[].batches`	array<object>	no	The batches being returned.
`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[].expirationDate`	date	no	The date the batch expires. Format: YYYY-MM-DD. See `expirationDate` on GET inventory/batch-numbers/:id (getBatchNumber).
`lines[].batches[].quantity`	decimal	yes	The quantity of the batch being returned, in the item's stocking unit.
`lines[].batches[].inventoryQuantity`	decimal	no	The quantity of the batch being returned, in the item's stocking unit.
`lines[].batches[].unitCost`	decimal	no	The purchase return line's `unitPrice` when the batch was added to that line, in the purchase return's currency. It is per unit of the line's unit of measure, not per stocking unit like `quantity`.
`lines[].serials`	array<object>	no	The serialized units being returned, one entry for each unit.
`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.
`lines[].serials[].unitCost`	decimal	no	The cost of the serialized unit, in the purchase return's currency. It is the purchase return line's `unitPrice` when the serialized unit was added to that line.
`lines[].binLocations`	array<object>	no	The bins the stock on this purchase return line is taken from, with the quantity taken from each bin. An entry with a `batchNumber` or `serialNumber` is for that batch or serialized unit. An entry with neither is for part of the line's quantity, not a particular batch or serialized unit.
`lines[].binLocations[].binLocationId`	string	yes	The unique identifier of the bin the stock is taken from. Format: UUID. See `id` on GET inventory/bins/:id (getBin).
`lines[].binLocations[].binLocationCode`	string	no	The code of the bin the stock is taken from.
`lines[].binLocations[].quantity`	decimal	yes	The quantity taken from the bin, in the item's stocking unit.
`lines[].binLocations[].batchNumber`	string	no	The batch number of the batch this bin quantity is for.
`lines[].binLocations[].serialNumber`	string	no	The serial number of the unit this bin quantity is for.
`applications`	array<object>	no	The receipt lines that the returned quantity was taken from, for purchase return lines that return goods from a purchase order line. A purchase order line can be received on several receipts, so shipping records which receipt lines the quantity came from. Absent until the purchase return is shipped, and when no purchase return line returns goods from a purchase order line.
`applications[].receiptLineId`	string	yes	The unique identifier of the receipt line the quantity was taken from. Format: UUID. See `lines[].id` on GET inventory/receipts/:id (getReceipt).
`applications[].quantity`	decimal	yes	The quantity taken from the receipt line, in the purchase return line's unit of measure.
`applications[].unitCost`	decimal	no	The cost of one unit of the quantity taken from the receipt line, in the purchase return line's unit of measure, as taken off the inventory's value (relieved) when the purchase return was shipped. It is `totalCost` divided by `quantity`, not rounded.
`applications[].totalCost`	decimal	no	The cost of the whole quantity taken from the receipt line, as taken off the inventory's value (relieved) when the purchase return was shipped.

{
  "data": {
    "id": "6a1f30c9-4d82-4b57-9e60-83c25f0a71b4",
    "documentNumber": "PRTR-1043",
    "documentStatus": "DRAFT",
    "documentDate": "2026-08-20",
    "deliveryDate": "2026-01-15",
    "returnType": "<returnType>",
    "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
    "entityName": "<entityName>",
    "businessPartnerId": "b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6",
    "businessPartnerName": "<businessPartnerName>",
    "referenceNumber": "<referenceNumber>",
    "originalReceiptId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "<currency>",
    "totalAmount": "19.99",
    "notes": "Vendor agreed collection for Friday",
    "createdDate": "2026-01-15T09:30:00.000Z",
    "lastModifiedDate": "2026-01-15T09:30:00.000Z",
    "lines": [
      {
        "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
        "quantity": "25.00"
      }
    ],
    "applications": [
      {
        "receiptLineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "quantity": "19.99",
        "unitCost": "19.99",
        "totalCost": "19.99"
      }
    ]
  },
  "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
`NOT_FOUND`	400
`WRONG_STATUS`	400
`REFERENCE_NOT_FOUND`	400
`INVALID_QUANTITY`	400
`INCOMPLETE_LINE`	400
`MISSING_TRACKING_SELECTION`	400
`UNKNOWN_TRACKING_REFERENCE`	400
`POSTING_REJECTED`	400
`IDEMPOTENCY_KEY_CONFLICT`	409
`IDEMPOTENCY_PAYLOAD_MISMATCH`	422

Statuses

400 — Invalid request or business failure. Codes: NOT_FOUND, WRONG_STATUS, REFERENCE_NOT_FOUND, INVALID_QUANTITY, INCOMPLETE_LINE, MISSING_TRACKING_SELECTION, UNKNOWN_TRACKING_REFERENCE, 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