Returns the invoices that match the given filters.

POST /accounting/invoices/search

Group: Accounting › Invoices · Operation ID: searchInvoice

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: searchInvoiceInput.

Field Type Required Description
filters object no The filters to apply. An invoice must match every filter you send. Omit to return all invoices.
filters.id string no Limits results to the invoice with this id.
filters.invoiceNumber string no Limits results to the invoice with this invoice number, for example 'INV-1'. The match is exact.
filters.customerId string no Limits results to invoices issued to this customer, given as the customer id. An id that matches no customer matches no invoice.
filters.customerName string no Limits results to invoices whose customer name contains this text. The match is case-insensitive.
filters.customerNumber string no Limits results to invoices issued to the customer with this customer number. The match is exact.
filters.entityId string no Limits results to invoices issued by this legal entity, given as the entity id. An id that matches no entity matches no invoice.
filters.entityName string no Limits results to invoices whose issuing legal entity's name contains this text. The match is case-insensitive.
filters.salesOrderId string no Limits results to invoices billed from this sales order, given as the sales order id. An id that matches no sales order matches no invoice.
filters.salesOrderNumber string no Limits results to invoices billed from the sales order with this number. The match is exact.
filters.invoiceStatus array of string no Limits results to invoices in any of these settlement statuses. Accepted values: 'unpaid', 'partiallyPaid', 'paidInFull', 'creditedInFull', 'isOverdue', 'disputed'. Any other value matches no invoice. An empty array does not constrain.
filters.approvalStatus array of string no Limits results to invoices in any of these approval statuses. Accepted values: 'draft', 'pendingApproval', 'approved', 'revise', 'rejected'. Any other value matches no invoice. An empty array does not constrain.
filters.deliveryStatus array of string no Limits results to invoices in any of these delivery statuses. Accepted values: 'created', 'toBeSent', 'delivered', 'read', 'failed'. Any other value matches no invoice. An empty array does not constrain.
filters.disputeStatus array of string no Limits results to invoices in any of these dispute statuses. Accepted values: 'disputed', 'chargedBack'. Any other value matches no invoice. An empty array does not constrain.
filters.customerMessage string no Limits results to invoices whose customer message contains this text. The match is case-insensitive.
filters.billToAddress string no Limits results to invoices whose bill-to address contains this text across line1, line2, city, stateProvince and zipCode. The match is case-insensitive. Country is excluded, because it is an ISO code and a short term would match every address in the country.
filters.soldToAddress string no Limits results to invoices whose sold-to address contains this text across line1, line2, city, stateProvince and zipCode. The match is case-insensitive. Country is excluded, as with billToAddress.
filters.invoiceEmail string no Limits results to invoices with this billing email. The match is exact and case-sensitive.
filters.purchaseOrderOverride string no Limits results to invoices with this PO override. The match is exact.
filters.externalInvoiceId string no Limits results to invoices with this identifier in an external source system. The match is exact.
filters.invoiceDate object no Limits results to invoices whose invoiceDate falls within these bounds. Omit either bound to leave that side open.
filters.invoiceDate.start string (date) no The inclusive lower bound. Format YYYY-MM-DD.
filters.invoiceDate.end string (date) no The inclusive upper bound. Format YYYY-MM-DD.
filters.dueDate object no Limits results to invoices whose dueDate falls within these bounds. Omit either bound to leave that side open. An aging report is this filter with an open lower bound.
filters.dueDate.start string (date) no The inclusive lower bound. Format YYYY-MM-DD.
filters.dueDate.end string (date) no The inclusive upper bound. Format YYYY-MM-DD.
filters.lastModifiedDate object no Limits results to invoices changed within this window, for polling an incremental sync. Omit either bound to leave that side open.
filters.lastModifiedDate.start string no The inclusive lower bound, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
filters.lastModifiedDate.end string no The inclusive upper bound, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
filters.externalIdentifier object no Matches one identifier owned by another system. Both members are required, because a fieldName on its own would match every value stored under that key. Several invoices may share one value, so this returns the items array, not a single record.
filters.externalIdentifier.fieldName string yes The configured key of the external identifier, a stable camelCase slug such as 'netsuiteInvoiceId', not the human-readable label. It must match an active external-identifier configuration for invoices, or the call fails with UNKNOWN_EXTERNAL_IDENTIFIER.
filters.externalIdentifier.value string yes The identifier as the source system stores it. The match is exact and case-sensitive.
page object no Pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit for the first request.
page.size number no The number of invoices per page. Defaults to 50. A value above 200 is treated as 200, not rejected.

Example:

{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "invoiceNumber": "<invoiceNumber>",
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customerName": "<customerName>",
    "customerNumber": "<customerNumber>",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityName": "<entityName>",
    "salesOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "salesOrderNumber": "<salesOrderNumber>",
    "invoiceStatus": [
      "<invoiceStatus>"
    ],
    "approvalStatus": [
      "<approvalStatus>"
    ],
    "deliveryStatus": [
      "<deliveryStatus>"
    ],
    "disputeStatus": [
      "<disputeStatus>"
    ],
    "customerMessage": "<customerMessage>",
    "billToAddress": "<billToAddress>",
    "soldToAddress": "<soldToAddress>",
    "invoiceEmail": "<invoiceEmail>",
    "purchaseOrderOverride": "<purchaseOrderOverride>",
    "externalInvoiceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "invoiceDate": {
      "start": "2026-01-15",
      "end": "2026-01-15"
    },
    "dueDate": {
      "start": "2026-01-15",
      "end": "2026-01-15"
    },
    "lastModifiedDate": {
      "start": "<start>",
      "end": "<end>"
    },
    "externalIdentifier": {
      "fieldName": "<fieldName>",
      "value": "<value>"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchInvoiceOutput):

Field Type Required Description
items array of object yes The invoices on this page, most recently created first. An empty array when nothing matches.
items[].id string yes The unique identifier for the invoice.
items[].invoiceNumber string no The invoice number, for example 'INV-1', unique within the tenant. Absent while none has been assigned.
items[].invoiceDate string (date) yes The date the invoice was issued. Format YYYY-MM-DD. Payment terms and the general ledger impact are both based on this date.
items[].dueDate string (date) no The date payment falls due, the invoice date plus the payment term. Format YYYY-MM-DD. Absent when no term has been resolved.
items[].lastPaidDate string (date) no The date the most recent payment was applied. Format YYYY-MM-DD. Absent on an invoice that has never been paid against.
items[].invoiceStatus string no The settlement status of the invoice. Possible values: 'unpaid', 'partiallyPaid', 'paidInFull', 'creditedInFull', 'isOverdue', 'disputed'.
items[].approvalStatus string no The finance approval status of the invoice. Possible values: 'draft', 'pendingApproval', 'approved', 'revise', 'rejected'.
items[].deliveryStatus string no How far the invoice has got in being sent to the customer. Possible values: 'created', 'toBeSent', 'delivered', 'read', 'failed'.
items[].disputeStatus string no The dispute status of the invoice, set only when payments against it are under dispute. Possible values: 'disputed', 'chargedBack'.
items[].dataSource string no The system the invoice record was imported from, for invoices that arrived through an integration or migration rather than being created in Everest. For example 'NetSuite', 'Quickbooks', 'Stripe' or 'MigrationFile'. Absent on invoices created in Everest.
items[].currency string yes The currency of the invoice. Format ISO 4217, for example 'USD'. It applies to every amount on the record, on the header and on every line.
items[].customerMessage string no A free-form message printed on the invoice for the customer.
items[].externalInvoiceId string no The invoice's identifier in an external source system, kept for reconciliation. For identifiers owned by your other systems, prefer externalIdentifiers below.
items[].customerId string yes The customer the invoice is issued to. See id on GET accounting/customers/:id.
items[].customerName string no The display name of the customer, as it appears on the document.
items[].customerNumber string no The customer number of the customer, unique within the tenant.
items[].entityId string yes The legal entity issuing the invoice. See id on GET base/entities.
items[].entityName string no The name of the issuing legal entity.
items[].salesOrderId string no The sales order the invoice was billed from. Absent on invoices created directly. See id on GET accounting/sales-orders/:id.
items[].salesOrderNumber string no The number of the source sales order. Present whenever salesOrderId is.
items[].billToAddress object no The bill-to address the invoice is sent to. Absent when the invoice references no bill-to record.
items[].billToAddress.addressId string no The unique identifier for the address record. Absent when none is stored.
items[].billToAddress.line1 string yes The first address line: street number and name, or PO box.
items[].billToAddress.line2 string no The second address line: apartment, suite, unit, building or floor.
items[].billToAddress.city string yes The city or locality.
items[].billToAddress.stateProvince string no The state, province or region.
items[].billToAddress.country string yes The country, as a name or ISO 3166-1 code.
items[].billToAddress.zipCode string yes The postal or ZIP code.
items[].soldToAddress object no The sold-to address the product or service was delivered to, used for tax determination. Absent when the invoice references no sold-to record.
items[].soldToAddress.addressId string no The unique identifier for the address record. Absent when none is stored.
items[].soldToAddress.line1 string yes The first address line: street number and name, or PO box.
items[].soldToAddress.line2 string no The second address line: apartment, suite, unit, building or floor.
items[].soldToAddress.city string yes The city or locality.
items[].soldToAddress.stateProvince string no The state, province or region.
items[].soldToAddress.country string yes The country, as a name or ISO 3166-1 code.
items[].soldToAddress.zipCode string yes The postal or ZIP code.
items[].invoiceEmail string no The email address of the business contact that receives this invoice.
items[].purchaseOrders array of string no The purchase order references the customer supplied, derived from the sales order. These are the customer's own document numbers. An empty array when none were supplied.
items[].purchaseOrderOverride string no A manually entered PO number that overrides the sales-order-derived values in purchaseOrders.
items[].paymentTermDays number no The number of days after the invoice date that payment falls due, resolved from the invoice's payment term. The term record itself is not published, only its day count.
items[].exchangeRate string (decimal) no The rate used to convert the invoice's currency to the entity's functional currency. Absent when no conversion applies.
items[].excludeFromTaxEngine boolean no Whether the invoice is left out of the tax engine. Derived from the sales order.
items[].subtotal string (decimal) no The amount before taxes and discounts, in the invoice currency. Absent when no subtotal has been computed.
items[].totalTax string (decimal) no The total tax across all lines, in the invoice currency.
items[].totalDutiesAndCustoms string (decimal) no The total duties and customs across all lines, in the invoice currency.
items[].totalAmount string (decimal) no The total invoiced, including taxes and duties, in the invoice currency.
items[].totalAmountDue string (decimal) no The amount that was due when the invoice was created, in the invoice currency.
items[].totalCredited string (decimal) no The total credited back against this invoice by credit memos, in the invoice currency.
items[].totalLateFeeAmount string (decimal) no The total late fees charged on this invoice, in the invoice currency.
items[].lineDiscounts string (decimal) no The sum of discount amounts across all invoice lines, in the invoice currency.
items[].oneTimeDiscount string (decimal) no The one-time discount applied to the invoice as a whole, in the invoice currency.
items[].paymentsApplied string (decimal) no The amount settled by payments so far, in the invoice currency.
items[].adjustments string (decimal) no The sum of small-balance write-offs and early-payment discounts recorded against this invoice, in the invoice currency.
items[].lastModifiedDate string (date-time) yes The date and time the invoice record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lines array of object no The lines of the invoice, each billing one product or free-text item. An empty array when the invoice has no lines. All line amounts are in the invoice currency.
items[].lines[].id string yes The unique identifier for the invoice line.
items[].lines[].invoiceLineNumber string no The sequential line number within the invoice.
items[].lines[].description string no The line description, as shown to the customer.
items[].lines[].lineType string no The kind of charge the line is. Possible values: 'recurring', 'oneTime', 'oneTimeDiscount', 'usageOverage', 'overage', 'payAsYouGo', 'commit', 'lateFee', 'creditCardProcessingFee', 'billableTime', 'billablePassThrough', 'billableTravelExpense'.
items[].lines[].productId string no The billed product. Set only on lines created from a product reference, absent on free-text lines. See id on GET accounting/products/:id.
items[].lines[].productCode string no The product code as it stood when the line was created. A snapshot, so it does not follow later changes to the product.
items[].lines[].productDescription string no The product description as it stood when the line was created. A snapshot, as with productCode.
items[].lines[].quantity string (decimal) no The quantity billed. A count, not an amount, so it has no currency.
items[].lines[].unitOfMeasure string no The unit the quantity is measured in, for example 'each', 'hour' or 'gigabyte'.
items[].lines[].unitPrice string (decimal) no The price per unit actually charged, in the invoice currency.
items[].lines[].listPrice string (decimal) no The undiscounted list price per unit, in the invoice currency.
items[].lines[].totalPrice string (decimal) no The line total excluding tax and duties, in the invoice currency.
items[].lines[].discountAmount string (decimal) no The discount granted on the line, in the invoice currency.
items[].lines[].discountPercentage string (decimal) no The discount granted on the line as a percentage. A rate, not an amount, so it has no currency.
items[].lines[].taxAmount string (decimal) no The tax on the line, in the invoice currency.
items[].lines[].dutiesAndCustomsAmount string (decimal) no The duties and customs charged on the line, in the invoice currency.
items[].lines[].amount string (decimal) no The total billed for the line, including tax and duties, in the invoice currency.
items[].lines[].totalAmountDue string (decimal) no The amount of the line still due, in the invoice currency.
items[].lines[].taxCode string no The tax code applied to the line.
items[].lines[].taxDate string (date) no The date the line's tax was determined on. Format YYYY-MM-DD.
items[].lines[].serviceStartDate string (date) no The first day of the service period the line covers. Format YYYY-MM-DD.
items[].lines[].serviceEndDate string (date) no The last day of the service period the line covers, inclusive. Format YYYY-MM-DD.
items[].externalIdentifiers array of object no External identifiers owned by your other systems. At most one entry per fieldName. An empty array when the invoice has none.
items[].externalIdentifiers[].fieldName string yes The configured key of the external identifier, a stable camelCase slug such as 'netsuiteInvoiceId', not the human-readable label. It must match an active external-identifier configuration for invoices.
items[].externalIdentifiers[].value string yes The identifier as the source system stores it.
items[].externalIdentifiers[].externalUrl string no An absolute http or https link to the object in the originating system. Absent when none is stored.
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 matches remain beyond this page.

Errors

Code Status
UNKNOWN_EXTERNAL_IDENTIFIER 400
INVALID_TIMESTAMP 400

Statuses