# Creates a sales return.

`POST /inventory/sales-returns`

Group: Inventory › Sales Returns · Operation ID: `createSalesReturn`

Creates one sales return, a draft. Nothing moves: no stock, no credit. The document records what the customer says is coming back. POST inventory/sales-returns/:id/commit is what accepts it, bringing the goods back into stock, writing the postings and raising the credit memo where one is due. condition and disposition on a line are expectations here, what the customer reported and what you intend to do. A batch-tracked item needs batches adding up to the line's quantity, and a serialized item needs one serials entry per unit. The whole call is one transaction: a rejected request writes nothing. The response is the created return in the shape GET inventory/sales-returns/:id returns.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=createSalesReturn)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"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. |
| `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` | string (date) | no | The date the return is dated. Defaults to today. Use format YYYY-MM-DD. |
| `deliveryDate` | string (date) | no | When the goods are expected back. Use format YYYY-MM-DD. |
| `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. |
| `referenceNumber` | string | no | The customer's own reference, for example an RMA number. |
| `trackingNumber` | string | no | The carrier's tracking number for the goods coming back. |
| `returnType` | string | no | How the business classifies the return. |
| `returnFeeAmount` | string (decimal) | no | The fee withheld across the return, in the document's currency. |
| `notes` | string | no | Free text on the document. |
| `lines` | array of object | yes | The lines of the return. At least one is required. |
| `lines[].itemId` | string | yes | The unique identifier for the item coming back. See id on GET inventory/items/:id. |
| `lines[].locationId` | string | yes | The unique identifier for the warehouse the goods come back to. Each line of a return may use a different warehouse. 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` | string (decimal) | yes | The quantity the customer is returning, in that unit. Greater than zero. |
| `lines[].unitPrice` | string (decimal) | no | The value of one unit, in the document's currency. Omit it to take the price from the sale. |
| `lines[].condition` | string, one of `"NEW"`, `"GOOD"`, `"USED"`, `"OPENED"`, `"DAMAGED"`, `"DEFECTIVE"`, `"EXPIRED"`, `"REFURBISHED"` | no | The condition the goods are expected in. The inspection may find otherwise and restates it. |
| `lines[].disposition` | string, one of `"RETURN_TO_STOCK"`, `"RETURN_TO_VENDOR"`, `"SCRAP"`, `"DONATE"`, `"REPAIR"`, `"REWORK"`, `"CREDIT_ONLY"` | no | What you intend to do with the goods. The inspection may change it. |
| `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` | string (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 of 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. On PATCH inventory/sales-returns/:id this replaces the line's batches. |
| `lines[].batches[].batchNumberId` | string | no | The unique identifier for an existing batch. Omit it and give batchNumber for a lot the system has not seen. |
| `lines[].batches[].batchNumber` | string | no | The batch number as printed. Required unless batchNumberId is given. |
| `lines[].batches[].expirationDate` | string (date) | no | The expiration date of the lot. Format YYYY-MM-DD. |
| `lines[].batches[].quantity` | string (decimal) | yes | The quantity of this batch coming back, in the line's unit. The batch quantities of a line must add up to the line's quantity. |
| `lines[].serials` | array of 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 an existing serial record. Omit it and give serialNumber. |
| `lines[].serials[].serialNumber` | string | no | The serial number stamped on the unit. Required unless serialNumberId is given. |
| `lines[].binLocations` | array of 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` | string (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. |

Example:

```json
{
  "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. |
| `documentNumber` | string | no | The sales return number, for example 'SR-1042'. Assigned on create and never supplied by you. |
| `documentStatus` | string | yes | The status of the return. Possible values: 'DRAFT', 'OPEN', 'COMMITTED', 'RECEIVED', 'INSPECTED', 'PROCESSED', 'COMPLETED', 'CANCELLED'. |
| `documentDate` | string (date) | yes | The date the return is dated. Format YYYY-MM-DD. |
| `deliveryDate` | string (date) | no | When the goods are expected back, or came back. Format YYYY-MM-DD. |
| `entityId` | string | yes | The unique identifier for the legal entity the return belongs to. See id on GET base/entities. |
| `entityName` | string | no | The name of that legal entity. |
| `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. |
| `businessPartnerName` | string | no | The name of that customer. |
| `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. |
| `sourceDocumentType` | string | no | What kind of document that was, for example 'SalesDelivery'. |
| `referenceNumber` | string | no | The customer's own reference for the return, for example an RMA number. |
| `trackingNumber` | string | no | The carrier's tracking number for the goods coming back. |
| `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. |
| `totalAmount` | string (decimal) | no | The total value of the return, in the document's currency. |
| `returnFeeAmount` | string (decimal) | no | The fee withheld across the return, in the document's currency. |
| `notes` | string | no | Free text on the document. |
| `createdDate` | string (date-time) | no | The date and time the return was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `lastModifiedDate` | string (date-time) | no | The date and time the return record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `lines` | array of object | yes | The lines of the return, oldest first. A sales return always has at least one. |
| `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 unique identifier for the warehouse the goods come back to. Each line of a return may use a different warehouse. 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` | string (decimal) | yes | The quantity the customer is returning, in the line's unit. |
| `lines[].inventoryQuantity` | string (decimal) | no | The same quantity in the item's stocking unit. |
| `lines[].openQuantity` | string (decimal) | no | How much of the line has not yet been received. |
| `lines[].inspectedQuantity` | string (decimal) | no | How much of the line the inspection covered. |
| `lines[].approvedQuantity` | string (decimal) | no | How much of the line was approved back into stock. |
| `lines[].rejectedQuantity` | string (decimal) | no | How much of the line was rejected. Approved plus rejected equals inspected. |
| `lines[].inspectedDate` | string (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` | string (decimal) | no | The value of one unit, in the document's currency. |
| `lines[].returnFeeAmount` | string (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` | string, one of `"IMInventorySalesOrderLine"`, `"IMInventorySalesDeliveryLine"`, `"IMSalesOrderLine"`, `"IMInventoryPurchaseReturnLine"`, `"IMInventorySalesReturnLine"`, `"IMWarehouseTransferLine"`, `"IMInventoryDecreaseLine"`, `"IMInventoryIncreaseLine"`, `"IMInventoryRevaluationLine"`, `"IMInventoryTransferLine"`, `"IMInventoryAdjustmentLine"`, `"IMInventoryCountLine"`, `"IMInventoryPutAwayTask"`, `"IMInventoryPurchaseReturnReversal"`, `"PurchaseOrderLine"`, `"IMLandedCostAllocationLine"`, `"SalesOrderProductItem"`, `"IMWarehouseTransferOrderLine"`, `"VendorBillItemBase"`, `"InvPurchaseDeliveryLine"` | no | What kind of document line that was. |
| `lines[].notes` | string | no | Free text on the line. |
| `lines[].batches` | array of 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` | string (date) | no | The expiration date of the lot. Format YYYY-MM-DD. |
| `lines[].batches[].quantity` | string (decimal) | yes | The quantity of this batch coming back, in the line's unit. |
| `lines[].batches[].inventoryQuantity` | string (decimal) | no | The same quantity in the item's stocking unit. |
| `lines[].batches[].openQuantity` | string (decimal) | no | How much of this batch has not yet been received. |
| `lines[].batches[].unitCost` | string (decimal) | no | The cost of one unit of this batch, in the document's currency. |
| `lines[].serials` | array of 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` | string (decimal) | no | How much of this unit is still outstanding, one or zero. |
| `lines[].serials[].unitCost` | string (decimal) | no | The cost of this unit, in the document's currency. |
| `lines[].binLocations` | array of 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` | string (decimal) | yes | The quantity going into this bin, in the line's unit. |
| `lines[].binLocations[].inventoryQuantity` | string (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 of 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` | string (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. |

## 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` — Missing or invalid 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
- `500` — Internal server error