Search invoices

Operation ID: searchInvoice

Group: Accounting › Invoices

POST /accounting/invoices/search

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

Searches invoices.

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: 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<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<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<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<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`	date	no	The inclusive lower bound. Format YYYY-MM-DD.
`filters.invoiceDate.end`	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`	date	no	The inclusive lower bound. Format YYYY-MM-DD.
`filters.dueDate.end`	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 request 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.

{
  "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<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`	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`	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`	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 this system. For example 'NetSuite', 'Quickbooks', 'Stripe' or 'MigrationFile'. Absent on invoices created in this system.
`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 set.
`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 set.
`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<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`	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`	decimal	no	The amount before taxes and discounts, in the invoice currency. Absent when no subtotal has been computed.
`items[].totalTax`	decimal	no	The total tax across all lines, in the invoice currency.
`items[].totalDutiesAndCustoms`	decimal	no	The total duties and customs across all lines, in the invoice currency.
`items[].totalAmount`	decimal	no	The total invoiced, including taxes and duties, in the invoice currency.
`items[].totalAmountDue`	decimal	no	The amount that was due when the invoice was created, in the invoice currency.
`items[].totalCredited`	decimal	no	The total credited back against this invoice by credit memos, in the invoice currency.
`items[].totalLateFeeAmount`	decimal	no	The total late fees charged on this invoice, in the invoice currency.
`items[].lineDiscounts`	decimal	no	The sum of discount amounts across all invoice lines, in the invoice currency.
`items[].oneTimeDiscount`	decimal	no	The one-time discount applied to the invoice as a whole, in the invoice currency.
`items[].paymentsApplied`	decimal	no	The amount settled by payments so far, in the invoice currency.
`items[].adjustments`	decimal	no	The sum of small-balance write-offs and early-payment discounts recorded against this invoice, in the invoice currency.
`items[].lastModifiedDate`	date-time	yes	The date and time the invoice record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
`items[].lines`	array<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`	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`	decimal	no	The price per unit actually charged, in the invoice currency.
`items[].lines[].listPrice`	decimal	no	The undiscounted list price per unit, in the invoice currency.
`items[].lines[].totalPrice`	decimal	no	The line total excluding tax and duties, in the invoice currency.
`items[].lines[].discountAmount`	decimal	no	The discount granted on the line, in the invoice currency.
`items[].lines[].discountPercentage`	decimal	no	The discount granted on the line as a percentage. A rate, not an amount, so it has no currency.
`items[].lines[].taxAmount`	decimal	no	The tax on the line, in the invoice currency.
`items[].lines[].dutiesAndCustomsAmount`	decimal	no	The duties and customs charged on the line, in the invoice currency.
`items[].lines[].amount`	decimal	no	The total billed for the line, including tax and duties, in the invoice currency.
`items[].lines[].totalAmountDue`	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`	date	no	The date the line's tax was determined on. Format YYYY-MM-DD.
`items[].lines[].serviceStartDate`	date	no	The first day of the service period the line covers. Format YYYY-MM-DD.
`items[].lines[].serviceEndDate`	date	no	The last day of the service period the line covers, inclusive. Format YYYY-MM-DD.
`items[].externalIdentifiers`	array<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 set.
`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.

{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "invoiceNumber": "<invoiceNumber>",
        "invoiceDate": "2026-01-15",
        "dueDate": "2026-01-15",
        "lastPaidDate": "2026-01-15",
        "invoiceStatus": "<invoiceStatus>",
        "approvalStatus": "<approvalStatus>",
        "deliveryStatus": "<deliveryStatus>",
        "disputeStatus": "<disputeStatus>",
        "dataSource": "<dataSource>",
        "currency": "<currency>",
        "customerMessage": "<customerMessage>",
        "externalInvoiceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "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>",
        "billToAddress": {
          "addressId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "line1": "<line1>",
          "line2": "<line2>",
          "city": "<city>",
          "stateProvince": "<stateProvince>",
          "country": "<country>",
          "zipCode": "<zipCode>"
        },
        "soldToAddress": {
          "addressId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "line1": "<line1>",
          "line2": "<line2>",
          "city": "<city>",
          "stateProvince": "<stateProvince>",
          "country": "<country>",
          "zipCode": "<zipCode>"
        },
        "invoiceEmail": "<invoiceEmail>",
        "purchaseOrders": [
          "<purchaseOrders>"
        ],
        "purchaseOrderOverride": "<purchaseOrderOverride>",
        "paymentTermDays": 0,
        "exchangeRate": "19.99",
        "excludeFromTaxEngine": true,
        "subtotal": "19.99",
        "totalTax": "19.99",
        "totalDutiesAndCustoms": "19.99",
        "totalAmount": "19.99",
        "totalAmountDue": "19.99",
        "totalCredited": "19.99",
        "totalLateFeeAmount": "19.99",
        "lineDiscounts": "19.99",
        "oneTimeDiscount": "19.99",
        "paymentsApplied": "19.99",
        "adjustments": "19.99",
        "lastModifiedDate": "2026-01-15T09:30:00.000Z",
        "lines": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "invoiceLineNumber": "<invoiceLineNumber>",
            "description": "<description>",
            "lineType": "<lineType>",
            "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "productCode": "<productCode>",
            "productDescription": "<productDescription>",
            "quantity": "19.99",
            "unitOfMeasure": "<unitOfMeasure>",
            "unitPrice": "19.99",
            "listPrice": "19.99",
            "totalPrice": "19.99",
            "discountAmount": "19.99",
            "discountPercentage": "19.99",
            "taxAmount": "19.99",
            "dutiesAndCustomsAmount": "19.99",
            "amount": "19.99",
            "totalAmountDue": "19.99",
            "taxCode": "<taxCode>",
            "taxDate": "2026-01-15",
            "serviceStartDate": "2026-01-15",
            "serviceEndDate": "2026-01-15"
          }
        ],
        "externalIdentifiers": [
          {
            "fieldName": "<fieldName>",
            "value": "<value>",
            "externalUrl": "<externalUrl>"
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code	Status
`UNKNOWN_EXTERNAL_IDENTIFIER`	400
`INVALID_TIMESTAMP`	400

Statuses

400 — Invalid request or business failure. Codes: UNKNOWN_EXTERNAL_IDENTIFIER, INVALID_TIMESTAMP
401 — The request carries no valid access token.
403 — Not authorized
404 — Not found
429 — Too many requests from this client address. The response has no body and no Retry-After header.
500 — Internal server error