Returns the sales returns that match the given criteria.

POST /inventory/sales-returns/search

Group: Inventory › Sales Returns · Operation ID: searchSalesReturns

Returns the sales returns that match the criteria in the request body, with the full item schema: header, lines, tracking and inspection detail, the same GET inventory/sales-returns/:id returns. This is the endpoint that returns the lines, and the only one that filters by customer, reference number or tracking number. Filtering by documentStatus is how you work the queue. Every criterion is exact or a range, and criteria combine with AND. An empty filters object returns everything, page by page.

Open in the interactive reference

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.

Request body

Required, application/json: searchSalesReturnsInput.

Field Type Required Description
filters object yes The criteria to apply, combined with AND. Omit to return all sales returns.
filters.documentNumber string no Limits results to the return with this document number. The match is exact.
filters.documentStatus string no Limits results to returns with this status. The match is exact. Possible values: 'DRAFT', 'OPEN', 'COMMITTED', 'RECEIVED', 'INSPECTED', 'PROCESSED', 'COMPLETED', 'CANCELLED'.
filters.entityId string no Limits results to returns for the legal entity with this identifier.
filters.businessPartnerId string no Limits results to returns for the customer with this identifier. Despite the name, this is a customer id.
filters.locationId string no Limits results to returns with a line for the warehouse with this identifier.
filters.itemId string no Limits results to returns with a line for the item with this identifier.
filters.referenceNumber string no Limits results to returns with this customer reference, for example an RMA number. The match is exact.
filters.trackingNumber string no Limits results to returns with this carrier tracking number. The match is exact.
filters.fromDate string (date) no Limits results to returns dated on or after this date. Use format YYYY-MM-DD.
filters.toDate string (date) no Limits results to returns dated on or before this date. Use format YYYY-MM-DD.
filters.modifiedSince string (date-time) no Limits results to returns changed on or after this time, in UTC. Use format YYYY-MM-DDTHH:mm:ss.sssZ.
page object no The pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit on the first request.
page.size number no The maximum number of returns to return. Defaults to 50. The maximum is 200.

Example:

{
  "filters": {
    "documentStatus": "RECEIVED"
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchSalesReturnsOutput):

Field Type Required Description
items array of object yes The matching returns for this page, oldest first, each with its lines. An empty array when nothing matches.
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 string (date) yes The date the return is dated. Format YYYY-MM-DD.
items[].deliveryDate string (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 string (decimal) no The total value of the return, in the document's currency.
items[].returnFeeAmount string (decimal) no The fee withheld across the return, in the document's currency.
items[].notes string no Free text on the document.
items[].createdDate string (date-time) no The date and time the return was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lastModifiedDate string (date-time) no The date and time the return record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lines array of 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 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.
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 string (decimal) yes The quantity the customer is returning, in the line's unit.
items[].lines[].inventoryQuantity string (decimal) no The same quantity in the item's stocking unit.
items[].lines[].openQuantity string (decimal) no How much of the line has not yet been received.
items[].lines[].inspectedQuantity string (decimal) no How much of the line the inspection covered.
items[].lines[].approvedQuantity string (decimal) no How much of the line was approved back into stock.
items[].lines[].rejectedQuantity string (decimal) no How much of the line was rejected. Approved plus rejected equals inspected.
items[].lines[].inspectedDate string (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 string (decimal) no The value of one unit, in the document's currency.
items[].lines[].returnFeeAmount string (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 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.
items[].lines[].notes string no Free text on the line.
items[].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.
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 string (date) no The expiration date of the lot. Format YYYY-MM-DD.
items[].lines[].batches[].quantity string (decimal) yes The quantity of this batch coming back, in the line's unit.
items[].lines[].batches[].inventoryQuantity string (decimal) no The same quantity in the item's stocking unit.
items[].lines[].batches[].openQuantity string (decimal) no How much of this batch has not yet been received.
items[].lines[].batches[].unitCost string (decimal) no The cost of one unit of this batch, in the document's currency.
items[].lines[].serials array of 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 string (decimal) no How much of this unit is still outstanding, one or zero.
items[].lines[].serials[].unitCost string (decimal) no The cost of this unit, in the document's currency.
items[].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.
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 string (decimal) yes The quantity going into this bin, in the line's unit.
items[].lines[].binLocations[].inventoryQuantity string (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 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.
items[].lines[].inspectionDetails[].approvalStatus string yes What was decided about this portion, recorded as given.
items[].lines[].inspectionDetails[].inspectedQuantity string (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.
pagination object yes The pagination cursor for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes True when more results remain beyond this page.

Statuses