Search invoices | Distru Documentation

Searches invoices — one row per invoice with totals, the amount paid, credit applied and the remaining balance, not line items.

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.
dueDateAfter	string	No	Inclusive. YYYY-MM-DD (start of day, company timezone) or ISO 8601 with a UTC offset.
dueDateBefore	string	No	Inclusive. YYYY-MM-DD (end of day, company timezone) or ISO 8601 with a UTC offset.
ids	string[]	No
invoiceDateAfter	string	No	Inclusive. YYYY-MM-DD (start of day, company timezone) or ISO 8601 with a UTC offset.
invoiceDateBefore	string	No	Inclusive. YYYY-MM-DD (end of day, company timezone) or ISO 8601 with a UTC offset.
ownerIds	string[]	No	Sales rep. Resolve via distru-search-users.
paidGreaterThanOrEqualTo	number	No	Dollars.
paidLessThanOrEqualTo	number	No	Dollars.
paymentStatus	enum[] `NOT_PAIDOVER_PAIDPAIDPARTIALLY_PAID`	No
productIds	string[]	No	Any line item of these products. Resolve via distru-search-products.
salesOrderStatus	enum[] `CANCELEDCOMPLETEDDELIVEREDDELIVERINGMERGEDPENDINGPROCESSINGREADY_TO_SHIP`	No
search	string	No	Case-insensitive substring of invoice number. Ranked by similarity; sortBy ignored.
totalGreaterThanOrEqualTo	number	No	Dollars.
totalLessThanOrEqualTo	number	No	Dollars.
voidStatus	enum `NOT_VOIDEDANYVOIDED`	No	Voided invoices (sales order canceled) are no longer owed. Default NOT_VOIDED, or ANY when ids is set.
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 UPDATED_AT DESC. Ignored when search is set.
sortBy.direction	enum `ASCDESC`	Yes
sortBy.field	enum `DUE_DATEINSERTED_ATINVOICE_DATEINVOICE_NUMBERREMAINING_AMOUNTTOTALUPDATED_AT`	Yes	REMAINING_AMOUNT: total minus payments.

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[].invoiceNumber	string	Always
items[].paymentStatus	enum `NOT_PAIDOVER_PAIDPAIDPARTIALLY_PAID`	Always
items[].total	string	Always
items[].paid	string	Always
items[].creditsApplied	string	Can be null
items[].remainingAmount	string	Always
items[].qbInvoiceId	string	Can be null
items[].qbSyncStatus	enum `DELETED_IN_QBOERRORNOT_SYNCEDPARTIALLY_SYNCEDPENDINGSYNCED`	Can be null
items[].voidedAt	string	Can be null
items[].invoiceDate	string	Always
items[].dueDate	string	Always
items[].createdDate	string	Always
items[].updatedDate	string	Always
items[].customer	object	Null or absent
items[].customer.id	string	Always
items[].customer.name	string	Null or absent
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
items[].billingLocation	object	Can be null
items[].billingLocation.id	string	Always
items[].billingLocation.name	string	Always

What the AI reads

Searches invoices — one row per invoice with totals, the amount paid, credit applied and the remaining balance, not line items. Use it to find the sales order or customer behind an invoice or to check payment status and totals live. For one invoice's line items and charges, use distru-get-invoice; for a flattened report with revenue/source breakdowns, distru-report-invoice-history; for line items across invoices, pass the returned salesOrder.orderNumber as the search filter to distru-report-sales-orders with rowsPer LINE_ITEM. For the payments received against an invoice, use distru-search-invoice-payments invoiceIds. A voided invoice keeps its totals and payment status on the row but is no longer owed; voidStatus leaves them out by default. salesOrder is null if the caller lacks access to the underlying order. qbSyncStatus ERROR: distru-search-quickbooks-activities with invoiceIds gives the error. ERROR or NOT_SYNCED: distru-sync-to-quickbooks pushes it, or says why it can't.