Search returns | Distru Documentation

Searches returns (product a customer sent back, reversing inventory and financials) — header fields only; for one return's line items, use distru-get-return with includeReturnItems.

Inputs

Every tool also takes the common inputs.

Field	Type	Required	Description
limit	integer	No	Default: `10`
cursor	string	No	nextCursor of the previous call; keep the other arguments unchanged.
customerIds	string[]	No	Resolve via distru-search-companies.
orderIds	string[]	No	Generic returns (no order) never match. Resolve via distru-search-sales-orders.
ownerIds	string[]	No	Resolve via distru-search-users.
returnDateAfter	string	No	Inclusive. YYYY-MM-DD (start of day, company timezone) or ISO 8601 with a UTC offset.
returnDateBefore	string	No	Inclusive. YYYY-MM-DD (end of day, company timezone) or ISO 8601 with a UTC offset.
statuses	enum[] `COMPLETEDPROCESSINGRECEIVEDSHIPPED`	No	PROCESSING, SHIPPED and RECEIVED hold goods aside; COMPLETED restocks them except waste items.
customFields	object[]	No	Set one of contains, anyOf or onOrAfter/onOrBefore per entry. Records with no value for the field never match.
customFields[].customFieldId	string	Yes	Resolve via distru-search-custom-fields.
customFields[].contains	string	No	TEXT: case-insensitive substring.
customFields[].anyOf	string[]	No	DROPDOWN, CHECKBOX: any of these options, case-sensitive.
customFields[].onOrAfter	string	No	DATE: YYYY-MM-DD, company timezone.
customFields[].onOrBefore	string	No	DATE: YYYY-MM-DD, company timezone.
sortBy	object	No	Default RETURN_DATE DESC.
sortBy.direction	enum `ASCDESC`	Yes
sortBy.field	enum `INSERTED_ATRETURN_DATERETURN_NUMBERSTATUSTOTAL`	Yes	RETURN_DATE: undated returns sort last either direction.

Output

Presence on a nested field assumes its parent exists.

Field	Type	Presence
hasMore	boolean	Always
nextCursor	string	Can be absent
totalCount	integer	Can be absent
items	object[]	Always
items[].id	string	Always
items[].customFields	object[]	Always
items[].customFields[].customField	object	Always
items[].customFields[].customField.id	string	Always
items[].customFields[].customField.name	string	Always
items[].customFields[].customField.fieldType	enum `CHECKBOXDATEDROPDOWNTEXT`	Always
items[].customFields[].value	string	Can be null
items[].description	string	Can be null
items[].invoiceNumbers	string[]	Always
items[].orderQuantity	string	Can be null
items[].qbCreditMemoId	string	Can be null
items[].qbSyncStatus	enum `DELETED_IN_QBOERRORNOT_SYNCEDPARTIALLY_SYNCEDPENDINGSYNCED`	Can be null
items[].returnDate	string	Can be null
items[].returnNumber	string	Always
items[].returnQuantity	string	Can be null
items[].returnType	enum `FULL_RETURNPARTIAL_RETURN`	Can be null
items[].status	enum `COMPLETEDPROCESSINGRECEIVEDSHIPPED`	Always
items[].total	number	Always
items[].company	object	Null or absent
items[].company.id	string	Always
items[].company.name	string	Null or absent
items[].location	object	Can be null
items[].location.id	string	Always
items[].location.name	string	Always
items[].owner	object	Can be null
items[].owner.id	string	Always
items[].owner.profile	object	Always
items[].owner.profile.fullName	string	Always
items[].salesOrder	object	Can be null
items[].salesOrder.id	string	Always
items[].salesOrder.orderNumber	string	Always

What the AI reads

Searches returns (product a customer sent back, reversing inventory and financials) — header fields only; for one return's line items, use distru-get-return with includeReturnItems. Generic returns have no sales order: salesOrder, orderQuantity, returnQuantity and returnType are null and invoiceNumbers is empty. qbCreditMemoId is the QuickBooks credit memo the return itself synced as. qbSyncStatus is null unless the company's QuickBooks module is on and connected, and while the company syncs credits to QuickBooks: the credit the return created then syncs instead and carries the credit memo, so qbCreditMemoId is set only if the return synced before that. PENDING and ERROR are its latest sync's outcome and win over the rest; NOT_SYNCED = it has no QuickBooks credit memo. For why a sync failed, use distru-search-quickbooks-activities with returnIds. Scoped to the returns the caller's team may see.