Search sales returns

Operation ID: searchAccountingSalesReturn

Group: Accounting › Sales Returns

Open in the interactive reference

POST /accounting/sales-returns/search

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches sales returns. Each sales return is returned with its lines.

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.

Request body

Required, application/json: searchAccountingSalesReturnInput.

Field Type Required Description
filters object no The filters to apply. A sales return must match every filter you send. Omit to return all sales returns.
filters.id string no Limits results to the sales return with this identifier.
filters.salesReturnNumber string no Limits results to the sales return with this RMA number, for example 'SR-104'.
filters.status array<string> no Limits results to sales returns in any of these statuses. Accepted values: 'draft', 'submitted', 'received', 'approved', 'completed', 'cancelled', 'rejected'. An unknown value matches nothing. An empty array does not constrain.
filters.returnType array<string> no Limits results to sales returns of any of these resolution paths. Accepted values: 'credit', 'replacement'. An unknown value matches nothing. An empty array does not constrain.
filters.reasonCode array<string> no Limits results to sales returns with any of these header-level reasons. Accepted values: 'defectiveItem', 'wrongItemShipped', 'damagedInTransit', 'customerRequest', 'duplicateOrder', 'notAsDescribed', 'other'. An empty array does not constrain.
filters.salesOrderId string no Limits results to sales returns raised against the sales order with this identifier. An identifier matching no sales order returns an empty page.
filters.currency string no Limits results to sales returns in this currency. Format ISO 4217, for example 'USD'.
filters.notes string no Limits results to sales returns whose notes contain this text. The match is case-insensitive.
filters.returnTrackingNumber string no Limits results to the sales return with this carrier tracking number.
filters.returnDate object no Limits results to sales returns whose returnDate falls in this range. Omit either bound to leave that side open.
filters.returnDate.start date no The earliest date to include. Format YYYY-MM-DD.
filters.returnDate.end date no The latest date to include. Format YYYY-MM-DD.
filters.lastModifiedDate object no Limits results to sales returns changed in this range, for polling an incremental sync. Omit either bound to leave that side open.
filters.lastModifiedDate.start string no The earliest time to include, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
filters.lastModifiedDate.end string no The latest time to include, in UTC. 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 for the first page.
page.size number no The number of sales returns per page. Defaults to 50. A value above 200 is treated as 200, not rejected. 
{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "salesReturnNumber": "<salesReturnNumber>",
    "status": [
      "<status>"
    ],
    "returnType": [
      "<returnType>"
    ],
    "reasonCode": [
      "<reasonCode>"
    ],
    "salesOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "<currency>",
    "notes": "<notes>",
    "returnTrackingNumber": "<returnTrackingNumber>",
    "returnDate": {
      "start": "2026-01-15",
      "end": "2026-01-15"
    },
    "lastModifiedDate": {
      "start": "<start>",
      "end": "<end>"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchAccountingSalesReturnOutput):

Field Type Required Description
items array<object> yes The sales returns on this page, oldest first. An empty array when nothing matches.
items[].id string yes The unique identifier for the sales return.
items[].salesReturnNumber string no The RMA number, for example 'SR-1'. Absent while none has been assigned.
items[].status string yes The lifecycle status of the sales return. Possible values: 'draft', 'submitted', 'received', 'approved', 'completed', 'cancelled', 'rejected'.
items[].returnType string yes The resolution path for the return. Possible values: 'credit', 'replacement'. It cannot be changed once status moves past 'draft'.
items[].returnDate string yes The transaction date for the return. Format YYYY-MM-DD.
items[].salesOrderId string yes The sales order this return is against. A sales return is always against exactly one sales order. See id on GET accounting/sales-orders/:id.
items[].currency string yes The currency of every amount on this record and its lines. Format ISO 4217, for example 'USD'.
items[].reasonCode string no The customer-facing reason for the return. Possible values: 'defectiveItem', 'wrongItemShipped', 'damagedInTransit', 'customerRequest', 'duplicateOrder', 'notAsDescribed', 'other'. It is for reporting and does not affect how the return is resolved.
items[].notes string no Free-form notes for the return.
items[].returnTrackingNumber string no The carrier tracking number for the inbound return shipment.
items[].totalReturnAmount decimal no The total return amount, the sum of every line's totalPrice, in the return currency.
items[].returnFeeAmount decimal no The fee deducted from the customer refund, such as a restocking fee, in the return currency. Credit returns only. It is set either here or on the lines, never both.
items[].shippingRefundAmount decimal no The shipping charge refunded to the customer, in the return currency. Credit returns only.
items[].totalRevenueImpact decimal no The revenue reversed to the customer, the product-line revenue impact plus the shipping refund, in the return currency. Always 0 for the replacement path.
items[].revenueStatus string no The revenue reversal status. Possible values: 'notApplicable', 'notStarted', 'reversed'. 'notApplicable' is the replacement path, and 'reversed' is a completed credit return.
items[].inventoryReturnNumber string no The document number of the linked inventory sales return. Absent until one has been created.
items[].lastModifiedDate date-time yes The date and time the sales return last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lines array<object> yes The product lines being returned.
items[].lines[].id string yes The unique identifier for this return line.
items[].lines[].salesOrderProductLineId string yes The sales order product line this line returns. See salesOrderProductLineId on GET accounting/sales-orders/:id.
items[].lines[].lineType string yes The product line type, copied from the sales order line at creation.
items[].lines[].quantity decimal yes The quantity being returned.
items[].lines[].unitOfMeasure string yes The unit of measure, copied from the sales order line.
items[].lines[].currency string yes The currency of unitPrice, totalPrice and returnFeeAmount on this line, copied from the sales return. Format ISO 4217, for example 'USD'.
items[].lines[].unitPrice decimal yes The unit price, copied from the sales order line at creation, in this line's currency.
items[].lines[].totalPrice decimal no The total price for the line, quantity times unitPrice, in this line's currency.
items[].lines[].returnFeeAmount decimal no The fee deducted from the customer refund for this line, in this line's currency. Credit returns only. Set only when fees are tracked per line rather than on the header.
items[].lines[].revenueImpactAmount decimal no The revenue reversed for this line, in this line's currency. 0 for the replacement path.
items[].lines[].lineStatus string yes The lifecycle status of this line. Possible values: 'pending', 'received', 'approved', 'completed', 'cancelled', 'rejected'.
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 sales returns remain beyond this page. 
{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "salesReturnNumber": "<salesReturnNumber>",
        "status": "<status>",
        "returnType": "<returnType>",
        "returnDate": "<returnDate>",
        "salesOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "currency": "<currency>",
        "reasonCode": "<reasonCode>",
        "notes": "<notes>",
        "returnTrackingNumber": "<returnTrackingNumber>",
        "totalReturnAmount": "19.99",
        "returnFeeAmount": "19.99",
        "shippingRefundAmount": "19.99",
        "totalRevenueImpact": "19.99",
        "revenueStatus": "<revenueStatus>",
        "inventoryReturnNumber": "<inventoryReturnNumber>",
        "lastModifiedDate": "2026-01-15T09:30:00.000Z",
        "lines": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "salesOrderProductLineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "lineType": "<lineType>",
            "quantity": "19.99",
            "unitOfMeasure": "<unitOfMeasure>",
            "currency": "<currency>",
            "unitPrice": "19.99",
            "totalPrice": "19.99",
            "returnFeeAmount": "19.99",
            "revenueImpactAmount": "19.99",
            "lineStatus": "<lineStatus>"
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
INVALID_TIMESTAMP 400

Statuses