Create a sales return

Operation ID: createSalesReturn

Group: Inventory › Sales Returns

POST /inventory/sales-returns

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 sales return as a draft. The draft lists what the customer is sending back, line by line. No stock moves and no credit is created until you commit the return with POST inventory/sales-returns/:id/commit.

The response is the created return with its lines, in the same shape as GET inventory/sales-returns/:id.

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

Field	Type	Required	Description
`businessPartnerId`	string	yes	The unique identifier for the customer returning the goods. Required, a return always comes from one. Despite the name, this is a customer id. See id on GET accounting/customers/:id. Example: `"c73f2b81-5d94-4e60-a812-0f9b6d3e45c7"`.
`entityId`	string	no	The unique identifier for the legal entity. Omit it and the first line's warehouse decides it. See id on GET base/entities.
`documentDate`	date	no	The date the return is dated. Defaults to today. Use format YYYY-MM-DD. Example: `"2026-08-14"`.
`deliveryDate`	date	no	When the goods are expected back. Use format YYYY-MM-DD. Example: `"2026-08-18"`.
`currency`	string	no	The currency for every amount on the return. Format ISO 4217, for example 'EUR'. Defaults to the legal entity's functional currency. Set it when the sale was in another. Example: `"EUR"`.
`referenceNumber`	string	no	The customer's own reference, for example an RMA number. Example: `"RMA-2026-0087"`.
`trackingNumber`	string	no	The carrier's tracking number for the goods coming back. Example: `"3SABCD1234567"`.
`returnType`	string	no	How the business classifies the return.
`returnFeeAmount`	decimal	no	The fee withheld across the return, in the document's currency.
`notes`	string	no	Free text on the document. Example: `"Customer reports transit damage"`.
`lines`	array<object>	yes	The lines of the return. At least one is required. Example: `[{"itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","unitId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","quantity":"6.00","unitPrice":"24.00","condition":"DAMAGED","disposition":"SCRAP","reasonCode":"damagedInTransit","sourceDocumentLineId":"5c1d9a72-0e64-4a1f-8b39-2c7f4a6e15d8","notes":"Carton crushed in transit"}]`.
`lines[].itemId`	string	yes	The unique identifier for the item coming back. See id on GET inventory/items/:id.
`lines[].locationId`	string	yes	The warehouse that receives the returned goods. Use the same warehouse on every line, because a return with lines in different warehouses can't be committed. See id on GET inventory/warehouses/:id.
`lines[].unitId`	string	yes	The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
`lines[].quantity`	decimal	yes	The quantity the customer is returning, in that unit. Greater than zero.
`lines[].unitPrice`	decimal	no	The value of one unit, in the document's currency. Omit it to take the price from the sale.
`lines[].condition`	any	no	The condition the goods are expected in. The inspection may find otherwise and restates it. One of: `"NEW"`, `"GOOD"`, `"USED"`, `"OPENED"`, `"DAMAGED"`, `"DEFECTIVE"`, `"EXPIRED"`, `"REFURBISHED"`.
`lines[].disposition`	any	no	What you intend to do with the goods. The inspection may change it. One of: `"RETURN_TO_STOCK"`, `"RETURN_TO_VENDOR"`, `"SCRAP"`, `"DONATE"`, `"REPAIR"`, `"REWORK"`, `"CREDIT_ONLY"`.
`lines[].reasonCode`	string	no	The customer-facing reason for the return, for example 'defectiveItem'. Reporting only.
`lines[].reasonCodeId`	string	no	The unique identifier for an internal reason code. See id on GET inventory/reason-codes/:id.
`lines[].returnFeeAmount`	decimal	no	The fee withheld on this line, in the document's currency.
`lines[].sourceDocumentLineId`	string	no	The shipment line the goods went out on, where the return follows a delivery. It is a line's id on GET inventory/shipments/:id. Naming it lets the commit value the return from the original shipment cost.
`lines[].notes`	string	no	Free text on the line.
`lines[].batches`	array<object>	no	The batches coming back on this line. Required for a batch-tracked item, and the quantities must add up to the line's quantity in the item's inventory unit. On PATCH inventory/sales-returns/:id this replaces the line's batches.
`lines[].batches[].batchNumberId`	string	no	The unique identifier for the batch coming back, as batchNumberId on the shipment line it went out on (GET inventory/shipments/:id). Either this or batchNumber is required.
`lines[].batches[].batchNumber`	string	no	The batch number as printed. Either this or batchNumberId is required; alone, it must name exactly one batch of the item in the warehouse the line returns to. Given beside batchNumberId, it must be that batch's own number.
`lines[].batches[].expirationDate`	date	no	The expiration date of the lot. Format YYYY-MM-DD.
`lines[].batches[].quantity`	decimal	yes	The quantity of this batch coming back, in the item's inventory unit. The batch quantities of a line must add up to the line's quantity in that unit.
`lines[].serials`	array<object>	no	The serialized units coming back, one entry per unit. Required for a serialized item, and the count must equal the line's quantity. On PATCH inventory/sales-returns/:id this replaces the line's serials.
`lines[].serials[].serialNumberId`	string	no	The unique identifier for the unit coming back, as serialNumberId on the shipment line it went out on (GET inventory/shipments/:id). Either this or serialNumber is required.
`lines[].serials[].serialNumber`	string	no	The serial number stamped on the unit. Either this or serialNumberId is required; alone, it must name exactly one unit of the item in the warehouse the line returns to. Given beside serialNumberId, it must be that unit's own number.
`lines[].binLocations`	array<object>	no	The bins the goods go into, in a bin-tracked warehouse. One flat array. An entry may name a batchNumber or serialNumber of its own line. On PATCH inventory/sales-returns/:id this replaces the line's bin entries.
`lines[].binLocations[].binLocationId`	string	yes	The unique identifier for the bin the goods go into. See id on GET inventory/bins/:id.
`lines[].binLocations[].quantity`	decimal	yes	The quantity going into this bin, in the item's inventory 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": "c73f2b81-5d94-4e60-a812-0f9b6d3e45c7",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "documentDate": "2026-08-14",
  "deliveryDate": "2026-08-18",
  "currency": "EUR",
  "referenceNumber": "RMA-2026-0087",
  "trackingNumber": "3SABCD1234567",
  "returnType": "<returnType>",
  "returnFeeAmount": "19.99",
  "notes": "Customer reports transit damage",
  "lines": [
    {
      "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
      "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
      "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
      "quantity": "6.00",
      "unitPrice": "24.00",
      "condition": "DAMAGED",
      "disposition": "SCRAP",
      "reasonCode": "damagedInTransit",
      "sourceDocumentLineId": "5c1d9a72-0e64-4a1f-8b39-2c7f4a6e15d8",
      "notes": "Carton crushed in transit"
    }
  ]
}

Response

200 Success

Under data (createSalesReturnOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the sales return. Example: `"5e9b0c74-1a26-4d83-b5f0-73c8e2a91d46"`.
`documentNumber`	string	no	The sales return number, for example 'SR-1042'. Assigned on create and never supplied by you. Example: `"SR-1042"`.
`documentStatus`	string	yes	The status of the return. Possible values: 'DRAFT', 'OPEN', 'COMMITTED', 'RECEIVED', 'INSPECTED', 'PROCESSED', 'COMPLETED', 'CANCELLED'. Example: `"DRAFT"`.
`documentDate`	date	yes	The date the return is dated. Format YYYY-MM-DD. Example: `"2026-08-14"`.
`deliveryDate`	date	no	When the goods are expected back, or came back. Format YYYY-MM-DD. Example: `"2026-08-18"`.
`entityId`	string	yes	The unique identifier for the legal entity the return belongs to. See id on GET base/entities. Example: `"1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43"`.
`entityName`	string	no	The name of that legal entity. Example: `"Acme Netherlands B.V."`.
`businessPartnerId`	string	yes	The unique identifier for the customer returning the goods. Despite the name, this is a customer id. See id on GET accounting/customers/:id. Example: `"c73f2b81-5d94-4e60-a812-0f9b6d3e45c7"`.
`businessPartnerName`	string	no	The name of that customer. Example: `"Bakker Retail B.V."`.
`sourceDocumentId`	string	no	The document the goods went out on, where the platform recorded one, as its own numeric id in a string. It is not an identifier this API can look up. The usable link is sourceDocumentLineId on the line. Example: `"55120"`.
`sourceDocumentType`	string	no	What kind of document that was, for example 'SalesDelivery'. Example: `"SalesDelivery"`.
`referenceNumber`	string	no	The customer's own reference for the return, for example an RMA number. Example: `"RMA-2026-0087"`.
`trackingNumber`	string	no	The carrier's tracking number for the goods coming back. Example: `"3SABCD1234567"`.
`returnType`	string	no	How the business classifies the return.
`currency`	string	no	The currency every amount on the document is in. Format ISO 4217, for example 'EUR'. A return is valued in the currency it was sold in, which need not be the legal entity's functional currency. Example: `"EUR"`.
`totalAmount`	decimal	no	The total value of the return, in the document's currency. Example: `"144.00"`.
`returnFeeAmount`	decimal	no	The fee withheld across the return, in the document's currency. Example: `"0.00"`.
`notes`	string	no	Free text on the document. Example: `"Customer reports transit damage"`.
`createdDate`	date-time	no	The date and time the return was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T08:30:00.000Z"`.
`lastModifiedDate`	date-time	no	The date and time the return record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T08:30:00.000Z"`.
`lines`	array<object>	yes	The lines of the return, oldest first. A sales return always has at least one. Example: [{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","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":"6.00","inventoryQuantity":"6.00","openQuantity":"6.00","condition":"DAMAGED","disposition":"SCRAP","unitPrice":"24.00","reasonCode":"damagedInTransit","sourceDocumentLineId":"5c1d9a72-0e64-4a1f-8b39-2c7f4a6e15d8","sourceDocumentLineType":"IMInventorySalesDeliveryLine","notes":"Carton crushed in transit"}].
`lines[].id`	string	yes	The unique identifier for the line. Use it in updateLines and deleteLines on PATCH inventory/sales-returns/:id.
`lines[].itemId`	string	yes	The unique identifier for the item coming back. See id on GET inventory/items/:id.
`lines[].itemCode`	string	no	The short code of that item.
`lines[].itemName`	string	no	The name of that item.
`lines[].locationId`	string	yes	The warehouse that receives the returned goods. Use the same warehouse on every line, because a return with lines in different warehouses can't be committed. See id on GET inventory/warehouses/:id.
`lines[].locationCode`	string	no	The short code of that warehouse.
`lines[].locationName`	string	no	The name of that warehouse.
`lines[].unitId`	string	yes	The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
`lines[].unitCode`	string	no	The short code of that unit.
`lines[].quantity`	decimal	yes	The quantity the customer is returning, in the line's unit.
`lines[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].openQuantity`	decimal	no	How much of the line has not yet been received.
`lines[].inspectedQuantity`	decimal	no	How much of the line the inspection covered.
`lines[].approvedQuantity`	decimal	no	How much of the line was approved back into stock.
`lines[].rejectedQuantity`	decimal	no	How much of the line was rejected. Approved plus rejected equals inspected.
`lines[].inspectedDate`	date	no	When the inspection took place. Format YYYY-MM-DD.
`lines[].condition`	string	no	The condition the goods arrived in, restated by the inspection. Possible values: 'NEW', 'GOOD', 'USED', 'OPENED', 'DAMAGED', 'DEFECTIVE', 'EXPIRED', 'REFURBISHED'.
`lines[].disposition`	string	no	What is to be done with the goods. Possible values: 'RETURN_TO_STOCK', 'RETURN_TO_VENDOR', 'SCRAP', 'DONATE', 'REPAIR', 'REWORK', 'CREDIT_ONLY'.
`lines[].qualityGrade`	string	no	The grade assigned at inspection.
`lines[].inspectionNotes`	string	no	Free text from the inspector.
`lines[].rejectionReason`	string	no	Why the rejected portion was rejected.
`lines[].unitPrice`	decimal	no	The value of one unit, in the document's currency.
`lines[].returnFeeAmount`	decimal	no	The fee withheld on this line, in the document's currency.
`lines[].reasonCode`	string	no	The customer-facing reason for the return, for example 'defectiveItem'. Reporting only, it does not affect how the return is processed.
`lines[].reasonCodeId`	string	no	The unique identifier for an internal reason code, where one was set. See id on GET inventory/reason-codes/:id.
`lines[].sourceDocumentLineId`	string	no	The shipment line the goods went out on, where the return cites one. It is a line's id on GET inventory/shipments/:id.
`lines[].sourceDocumentLineType`	any	no	What kind of document line that was. 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 coming back 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.
`lines[].batches[].batchNumber`	string	yes	The batch number as printed.
`lines[].batches[].expirationDate`	date	no	The expiration date of the lot. Format YYYY-MM-DD.
`lines[].batches[].quantity`	decimal	yes	The quantity of this batch coming back, in the item's inventory unit.
`lines[].batches[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].batches[].openQuantity`	decimal	no	How much of this batch has not yet been received.
`lines[].batches[].unitCost`	decimal	no	The cost of one unit of this batch, in the document's currency.
`lines[].serials`	array<object>	no	The serialized units coming back, one entry per unit. Absent when the item is not serialized.
`lines[].serials[].serialNumberId`	string	no	The unique identifier for the serial record.
`lines[].serials[].serialNumber`	string	yes	The serial number as stamped on the unit.
`lines[].serials[].openQuantity`	decimal	no	How much of this unit is still outstanding, one or zero.
`lines[].serials[].unitCost`	decimal	no	The cost of this unit, in the document's currency.
`lines[].binLocations`	array<object>	no	The bins the goods go into, in a bin-tracked warehouse. One flat array. An entry naming a batchNumber or serialNumber belongs to that batch or unit, and one naming neither belongs to the line.
`lines[].binLocations[].binLocationId`	string	yes	The unique identifier for the bin the goods go into. See id on GET inventory/bins/:id.
`lines[].binLocations[].binLocationCode`	string	no	The short code of that bin.
`lines[].binLocations[].quantity`	decimal	yes	The quantity going into this bin, in the item's inventory unit.
`lines[].binLocations[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].binLocations[].batchNumber`	string	no	Set when this bin entry belongs to one of the line's batches, naming it.
`lines[].binLocations[].serialNumber`	string	no	Set when this bin entry belongs to one of the line's serialized units, naming it.
`lines[].inspectionDetails`	array<object>	no	What the inspection found, broken down by batch or unit. Absent before the inspection runs. The line has the totals and these give the detail.
`lines[].inspectionDetails[].approvalStatus`	string	yes	What was decided about this portion, recorded as given.
`lines[].inspectionDetails[].inspectedQuantity`	decimal	yes	How much this finding covers.
`lines[].inspectionDetails[].condition`	string	no	The condition of this portion. Possible values: 'NEW', 'GOOD', 'USED', 'OPENED', 'DAMAGED', 'DEFECTIVE', 'EXPIRED', 'REFURBISHED'.
`lines[].inspectionDetails[].disposition`	string	no	What is to be done with this portion. Possible values: 'RETURN_TO_STOCK', 'RETURN_TO_VENDOR', 'SCRAP', 'DONATE', 'REPAIR', 'REWORK', 'CREDIT_ONLY'.
`lines[].inspectionDetails[].qualityGrade`	string	no	The grade assigned at inspection, where the business uses one.
`lines[].inspectionDetails[].inspectionNotes`	string	no	Free text from the inspector.
`lines[].inspectionDetails[].rejectionReason`	string	no	Why this portion was rejected, where it was.
`lines[].inspectionDetails[].batchNumber`	string	no	The batch this finding is about, where it is about one.
`lines[].inspectionDetails[].serialNumber`	string	no	The serialized unit this finding is about, where it is about one.

{
  "data": {
    "id": "5e9b0c74-1a26-4d83-b5f0-73c8e2a91d46",
    "documentNumber": "SR-1042",
    "documentStatus": "DRAFT",
    "documentDate": "2026-08-14",
    "deliveryDate": "2026-08-18",
    "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
    "entityName": "Acme Netherlands B.V.",
    "businessPartnerId": "c73f2b81-5d94-4e60-a812-0f9b6d3e45c7",
    "businessPartnerName": "Bakker Retail B.V.",
    "sourceDocumentId": "55120",
    "sourceDocumentType": "SalesDelivery",
    "referenceNumber": "RMA-2026-0087",
    "trackingNumber": "3SABCD1234567",
    "returnType": "<returnType>",
    "currency": "EUR",
    "totalAmount": "144.00",
    "returnFeeAmount": "0.00",
    "notes": "Customer reports transit damage",
    "createdDate": "2026-08-14T08:30:00.000Z",
    "lastModifiedDate": "2026-08-14T08:30:00.000Z",
    "lines": [
      {
        "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
        "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": "6.00",
        "inventoryQuantity": "6.00",
        "openQuantity": "6.00",
        "condition": "DAMAGED",
        "disposition": "SCRAP",
        "unitPrice": "24.00",
        "reasonCode": "damagedInTransit",
        "sourceDocumentLineId": "5c1d9a72-0e64-4a1f-8b39-2c7f4a6e15d8",
        "sourceDocumentLineType": "IMInventorySalesDeliveryLine",
        "notes": "Carton crushed in transit"
      }
    ]
  },
  "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
`DUPLICATE_TRACKING_NUMBER`	400
`UNKNOWN_TRACKING_REFERENCE`	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, DUPLICATE_TRACKING_NUMBER, 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