Bulk create sales returns

Operation ID: bulkCreateSalesReturns

Group: Inventory › Sales Returns

Open in the interactive reference

POST /inventory/sales-returns/bulk

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

Creates multiple draft sales returns in one request. Each return in returns takes the same fields as POST inventory/sales-returns. If any return can't be created, none are. 'index' on the error is the position of that return, counting from zero.

The response lists the new drafts with their lines, in the order you sent them.

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

Field Type Required Description
returns array<object> yes The returns to create. At least one, each exactly what POST inventory/sales-returns takes. Example: [{"businessPartnerId":"c73f2b81-5d94-4e60-a812-0f9b6d3e45c7","documentDate":"2026-08-14","deliveryDate":"2026-08-18","referenceNumber":"RMA-2026-0087","trackingNumber":"3SABCD1234567","currency":"EUR","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"}]}].
returns[].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.
returns[].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.
returns[].documentDate date no The date the return is dated. Defaults to today. Use format YYYY-MM-DD.
returns[].deliveryDate date no When the goods are expected back. Use format YYYY-MM-DD.
returns[].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.
returns[].referenceNumber string no The customer's own reference, for example an RMA number.
returns[].trackingNumber string no The carrier's tracking number for the goods coming back.
returns[].returnType string no How the business classifies the return.
returns[].returnFeeAmount decimal no The fee withheld across the return, in the document's currency.
returns[].notes string no Free text on the document.
returns[].lines array<object> yes The lines of this return. At least one is required.
returns[].lines[].itemId string yes The unique identifier for the item coming back. See id on GET inventory/items/:id.
returns[].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.
returns[].lines[].unitId string yes The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
returns[].lines[].quantity decimal yes The quantity the customer is returning, in that unit. Greater than zero.
returns[].lines[].unitPrice decimal no The value of one unit, in the document's currency. Omit it to take the price from the sale.
returns[].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".
returns[].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".
returns[].lines[].reasonCode string no The customer-facing reason for the return, for example 'defectiveItem'. Reporting only.
returns[].lines[].reasonCodeId string no The unique identifier for an internal reason code. See id on GET inventory/reason-codes/:id.
returns[].lines[].returnFeeAmount decimal no The fee withheld on this line, in the document's currency.
returns[].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.
returns[].lines[].notes string no Free text on the line.
returns[].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.
returns[].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.
returns[].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.
returns[].lines[].batches[].expirationDate date no The expiration date of the lot. Format YYYY-MM-DD.
returns[].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.
returns[].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.
returns[].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.
returns[].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.
returns[].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.
returns[].lines[].binLocations[].binLocationId string yes The unique identifier for the bin the goods go into. See id on GET inventory/bins/:id.
returns[].lines[].binLocations[].quantity decimal yes The quantity going into this bin, in the item's inventory unit.
returns[].lines[].binLocations[].batchNumber string no Names one of this line's batches, when the bin entry belongs to it.
returns[].lines[].binLocations[].serialNumber string no Names one of this line's serialized units, when the bin entry belongs to it. 
{
  "returns": [
    {
      "businessPartnerId": "c73f2b81-5d94-4e60-a812-0f9b6d3e45c7",
      "documentDate": "2026-08-14",
      "deliveryDate": "2026-08-18",
      "referenceNumber": "RMA-2026-0087",
      "trackingNumber": "3SABCD1234567",
      "currency": "EUR",
      "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 (bulkCreateSalesReturnsOutput):

Field Type Required Description
items array<object> yes The created returns, in input order. Match them to inputs by index. Example: [{"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","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"}]}].
items[].id string yes The unique identifier for the sales return.
items[].documentNumber string no The sales return number, for example 'SR-1042'. Assigned on create and never supplied by you.
items[].documentStatus string yes The status of the return. Possible values: 'DRAFT', 'OPEN', 'COMMITTED', 'RECEIVED', 'INSPECTED', 'PROCESSED', 'COMPLETED', 'CANCELLED'.
items[].documentDate date yes The date the return is dated. Format YYYY-MM-DD.
items[].deliveryDate date no When the goods are expected back, or came back. Format YYYY-MM-DD.
items[].entityId string yes The unique identifier for the legal entity the return belongs to. See id on GET base/entities.
items[].entityName string no The name of that legal entity.
items[].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.
items[].businessPartnerName string no The name of that customer.
items[].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.
items[].sourceDocumentType string no What kind of document that was, for example 'SalesDelivery'.
items[].referenceNumber string no The customer's own reference for the return, for example an RMA number.
items[].trackingNumber string no The carrier's tracking number for the goods coming back.
items[].returnType string no How the business classifies the return.
items[].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.
items[].totalAmount decimal no The total value of the return, in the document's currency.
items[].returnFeeAmount decimal no The fee withheld across the return, in the document's currency.
items[].notes string no Free text on the document.
items[].createdDate date-time no The date and time the return was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lastModifiedDate date-time no The date and time the return record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lines array<object> yes The lines of the return, oldest first. A sales return always has at least one.
items[].lines[].id string yes The unique identifier for the line. Use it in updateLines and deleteLines on PATCH inventory/sales-returns/:id.
items[].lines[].itemId string yes The unique identifier for the item coming back. See id on GET inventory/items/:id.
items[].lines[].itemCode string no The short code of that item.
items[].lines[].itemName string no The name of that item.
items[].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.
items[].lines[].locationCode string no The short code of that warehouse.
items[].lines[].locationName string no The name of that warehouse.
items[].lines[].unitId string yes The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
items[].lines[].unitCode string no The short code of that unit.
items[].lines[].quantity decimal yes The quantity the customer is returning, in the line's unit.
items[].lines[].inventoryQuantity decimal no The same quantity in the item's stocking unit.
items[].lines[].openQuantity decimal no How much of the line has not yet been received.
items[].lines[].inspectedQuantity decimal no How much of the line the inspection covered.
items[].lines[].approvedQuantity decimal no How much of the line was approved back into stock.
items[].lines[].rejectedQuantity decimal no How much of the line was rejected. Approved plus rejected equals inspected.
items[].lines[].inspectedDate date no When the inspection took place. Format YYYY-MM-DD.
items[].lines[].condition string no The condition the goods arrived in, restated by the inspection. Possible values: 'NEW', 'GOOD', 'USED', 'OPENED', 'DAMAGED', 'DEFECTIVE', 'EXPIRED', 'REFURBISHED'.
items[].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'.
items[].lines[].qualityGrade string no The grade assigned at inspection.
items[].lines[].inspectionNotes string no Free text from the inspector.
items[].lines[].rejectionReason string no Why the rejected portion was rejected.
items[].lines[].unitPrice decimal no The value of one unit, in the document's currency.
items[].lines[].returnFeeAmount decimal no The fee withheld on this line, in the document's currency.
items[].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.
items[].lines[].reasonCodeId string no The unique identifier for an internal reason code, where one was set. See id on GET inventory/reason-codes/:id.
items[].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.
items[].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".
items[].lines[].notes string no Free text on the line.
items[].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.
items[].lines[].batches[].batchNumberId string no The unique identifier for the batch record.
items[].lines[].batches[].batchNumber string yes The batch number as printed.
items[].lines[].batches[].expirationDate date no The expiration date of the lot. Format YYYY-MM-DD.
items[].lines[].batches[].quantity decimal yes The quantity of this batch coming back, in the item's inventory unit.
items[].lines[].batches[].inventoryQuantity decimal no The same quantity in the item's stocking unit.
items[].lines[].batches[].openQuantity decimal no How much of this batch has not yet been received.
items[].lines[].batches[].unitCost decimal no The cost of one unit of this batch, in the document's currency.
items[].lines[].serials array<object> no The serialized units coming back, one entry per unit. Absent when the item is not serialized.
items[].lines[].serials[].serialNumberId string no The unique identifier for the serial record.
items[].lines[].serials[].serialNumber string yes The serial number as stamped on the unit.
items[].lines[].serials[].openQuantity decimal no How much of this unit is still outstanding, one or zero.
items[].lines[].serials[].unitCost decimal no The cost of this unit, in the document's currency.
items[].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.
items[].lines[].binLocations[].binLocationId string yes The unique identifier for the bin the goods go into. See id on GET inventory/bins/:id.
items[].lines[].binLocations[].binLocationCode string no The short code of that bin.
items[].lines[].binLocations[].quantity decimal yes The quantity going into this bin, in the item's inventory unit.
items[].lines[].binLocations[].inventoryQuantity decimal no The same quantity in the item's stocking unit.
items[].lines[].binLocations[].batchNumber string no Set when this bin entry belongs to one of the line's batches, naming it.
items[].lines[].binLocations[].serialNumber string no Set when this bin entry belongs to one of the line's serialized units, naming it.
items[].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.
items[].lines[].inspectionDetails[].approvalStatus string yes What was decided about this portion, recorded as given.
items[].lines[].inspectionDetails[].inspectedQuantity decimal yes How much this finding covers.
items[].lines[].inspectionDetails[].condition string no The condition of this portion. Possible values: 'NEW', 'GOOD', 'USED', 'OPENED', 'DAMAGED', 'DEFECTIVE', 'EXPIRED', 'REFURBISHED'.
items[].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'.
items[].lines[].inspectionDetails[].qualityGrade string no The grade assigned at inspection, where the business uses one.
items[].lines[].inspectionDetails[].inspectionNotes string no Free text from the inspector.
items[].lines[].inspectionDetails[].rejectionReason string no Why this portion was rejected, where it was.
items[].lines[].inspectionDetails[].batchNumber string no The batch this finding is about, where it is about one.
items[].lines[].inspectionDetails[].serialNumber string no The serialized unit this finding is about, where it is about one. 
{
  "data": {
    "items": [
      {
        "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",
        "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

Errors

Code Status
NOTHING_TO_CREATE 400
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