Get returns
List returns, newest first (by return date), with optional filters: by customer (company_ids), by originating sales order (order_ids), by statuses, by custom field values (custom_data), and by the inserted_datetime / return_datetime / updated_datetime windows. When more than one filter is supplied they are combined with AND — a return must satisfy every filter to appear.
A return records product a customer sent back. It reverses the related inventory and financials, and — when the return is set to create a credit — generates a customer credit, which can sync to QuickBooks Online as a credit memo. A return is usually tied to the original sales order; a return created without an order is a generic return and leaves the order-derived fields (order, order_quantity, return_quantity, return_type, invoice_numbers) empty.
Returned goods are added back to sellable inventory only once a return reaches COMPLETED; while PROCESSING, SHIPPED, or RECEIVED they are held aside as returning stock. Line items flagged as waste are written off rather than restocked.
Results are ordered by return date, newest first, and paginated. Follow the next_page URL in the response to fetch the following page rather than incrementing the page number yourself. This endpoint is eventually consistent: a change can take up to 1 second to appear here.
Required permission: returns_permissions_view.
Query parameters
Restrict the result to specific returns by ID (the same ID returned as each return's id). Repeat the bracketed key once per ID. Unknown IDs simply match nothing; an empty list is treated as no filter. At most 200 IDs may be given.
Restrict to returns issued to specific customers by company ID (the same ID returned as each return's company.id). Repeat the bracketed key once per ID; matches ANY. Unknown IDs match nothing; an empty list is no filter. At most 200 IDs.
Filter by creation datetime, given as an inclusive after,before range of ISO 8601 timestamps separated by a comma. Either bound may be left empty: after, keeps only returns created on or after after; ,before only those created on or before before; after,before keeps those inside the closed range. A range with both bounds empty is rejected.
Restrict to returns tied to specific sales orders by order ID (the same ID returned as each return's order.id). Repeat the bracketed key once per ID; matches ANY. A malformed ID is rejected with a 400; an unknown-but-well-formed ID matches nothing; an empty list is no filter. Generic returns (created without an order) never match. At most 200 IDs.
Restrict to returns owned by any of these Distru users (each return's owner.id). Repeat the bracketed key once per ID; matches ANY. Unknown IDs match nothing; an empty list is no filter. At most 200 IDs.
Restrict to returns in any of the given statuses (SCREAMING_CASE, matches ANY): PROCESSING, SHIPPED, RECEIVED, COMPLETED. Repeat the bracketed key once per status. An empty list is no filter; at most 200 statuses.
Page selector. Page size is fixed by the server; paginate by following the next_page URL in each response rather than building page selectors yourself — it is null on the last page. next_page uses page[after]=<cursor>, an opaque token marking where the next page resumes; pass it back exactly as given, and only to the endpoint that issued it. This is seek-based, so every page stays fast no matter how deep you page.
Filter by return date — the business date on the return, which can differ from when the record was created — given as an inclusive after,before range of ISO 8601 timestamps separated by a comma, with the same empty-bound rules as inserted_datetime.
Filter by last-modified datetime, given as an inclusive after,before range of ISO 8601 timestamps separated by a comma, with the same empty-bound rules as inserted_datetime.
Filter by custom field values, as custom_data[{id}]=value where {id} is a custom field's numeric id. Repeat with different ids to filter on several fields at once; a record must match every one (AND). Matching is case-sensitive exact against the value stored on the record. The id must be a filterable custom field defined on this entity — use GET /public/v1/custom-fields?parent_object=return to list the ids, their types, and which are filterable. A non-numeric id, an id not defined on this entity, or an id that isn't filterable returns a 400.
Response
A list of returns
Changes
No recorded changes to this endpoint across all 1 revision of this API.