# Search invoices

Returns a paginated list of invoices that match the specified filters, ordered newest first. Results are eventually consistent, so new and updated records are not immediately searchable. Do not use this endpoint for read-after-write flows. To get the current state of an invoice, use get invoice.

Endpoint: POST /invoices/search
Version: 2.0.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer asec_xxx

## Request fields (application/json):

  - `filters` (object)
    Filters for invoices. All filters must match.

  - `filters.status` (object)
    Operator and value for invoice status filter.

  - `filters.status.operator` (string, required)
    Comparison operator. Use `IN` to match any of several statuses.
    Enum: "EQ", "IN"

  - `filters.status.value` (string, required)
    One allowed value of the field for `EQ` and `NEQ`, or a comma-separated list of them for `IN`.

  - `filters.customer_id` (object)
    Operator and value for customer identifier filter.

  - `filters.customer_id.operator` (string, required)
    Comparison operator.
    Enum: "EQ"

  - `filters.customer_id.value` (string, required)
    One identifier for `EQ` and `NEQ`, or a comma-separated list for `IN`, with a comma inside a value escaped as `\,`. It cannot be empty or contain only spaces.

  - `filters.customer_email` (object)
    Operator and value for an email address filter. `EQ` takes a full email address, `STARTS_WITH` takes its beginning. Both ignore case.
    Example: {"operator":"EQ","value":"jane.doe@example.com"}

  - `filters.customer_email.operator` (string, required)
    Comparison operator. `EQ` matches the full email address, ignoring case.
    Enum: "EQ"

  - `filters.customer_email.value` (string, required)
    Email address.
    Example: jane.doe@example.com

  - `filters.customer_email.operator` (string, required)
    Comparison operator. `STARTS_WITH` matches email addresses that start with the given value, ignoring case.
    Enum: "STARTS_WITH"

  - `filters.customer_email.value` (string, required)
    Beginning of the email address. Leading and trailing spaces are ignored.
    Example: jane.doe@ex

  - `filters.subscription_id` (object)
    Operator and value for subscription identifier filter.

  - `filters.subscription_id.operator` (string, required)
    Comparison operator.
    Enum: "EQ"

  - `filters.created_at` (object)
    Operator and value for a date and time filter. `GTE` and `LTE` take a single date and time, `RANGE` takes an inclusive range.
    Example: {"operator":"RANGE","value":{"from":"2024-01-01T10:00:00.000000Z","to":"2024-01-31T10:00:00.000000Z"}}

  - `filters.created_at.operator` (string, required)
    Comparison operator. `GTE` matches values at or after the date and time, `LTE` at or before it.
    Enum: "GTE", "LTE"

  - `filters.created_at.value` (string, required)
    Date and time value.
    Example: 2024-01-01T10:00:00.000000Z

  - `filters.created_at.operator` (string, required)
    Comparison operator. `RANGE` matches values within the inclusive range.
    Enum: "RANGE"

  - `filters.created_at.value` (object, required)
    Inclusive range of dates and times.

  - `filters.created_at.value.from` (string, required)
    Date and time value.
    Example: 2024-01-01T10:00:00.000000Z

  - `filters.created_at.value.to` (string, required)
    Date and time value.
    Example: 2024-01-01T10:00:00.000000Z

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. Omitted when no pages remain.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `items` (array)
    List of invoices for the current page.

  - `items.id` (string, required)
    Unique invoice identifier.
    Example: inv_01KPWT0K1PQWEYYRT7J1H3NC85

  - `items.created_at` (string, required)
    Date and time when the invoice was created.
    Example: 2025-12-24T11:45:00.000000Z

  - `items.updated_at` (string, required)
    Date and time when the invoice was updated.
    Example: 2025-12-24T11:47:00.000000Z

  - `items.status` (string, required)
    Current invoice status.
The list of enum values may be extended without notice.
    Enum: "DRAFT", "OPEN", "PAID", "VOIDED", "DUNNING", "UNPAID"

  - `items.total_amount` (integer, required)
    Total invoice amount in minor units.
    Example: 990

  - `items.amount_due` (integer)
    Amount still owed on the invoice, reflecting any adjustments to the total amount.
    Example: 900

  - `items.currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: USD

  - `items.line_items` (array, required)
    Line items applied to the invoice.
    Example: [{"product_price_id":"e6f26db1-f633-4723-ab08-50ddee7bc648","description":"Great product","amount":990,"currency":"USD","amount_details":{"subtotal":1000,"discount":100,"taxable":900,"tax":90},"quanti…

  - `items.line_items.product_price_id` (string)
    Identifier of the associated product price.
    Example: e6f26db1-f633-4723-ab08-50ddee7bc648

  - `items.line_items.product_id` (string)
    Identifier of the associated product.
    Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

  - `items.line_items.description` (string)
    Line item description.
    Example: Great product

  - `items.line_items.amount` (integer, required)
    Line item amount in minor units.
    Example: 990

  - `items.line_items.currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: USD

  - `items.line_items.amount_details` (object, required)
    Represents line item amount details.
    Example: {"subtotal":1000,"discount":100,"taxable":900,"tax":90}

  - `items.line_items.amount_details.subtotal` (integer, required)
    Subtotal amount in minor units before discounts and taxes.
    Example: 1000

  - `items.line_items.amount_details.discount` (integer, required)
    Discount amount in minor units.
    Example: 100

  - `items.line_items.amount_details.taxable` (integer)
    Taxable amount in minor units.
    Example: 900

  - `items.line_items.amount_details.tax` (integer)
    Tax amount in minor units.
    Example: 90

  - `items.line_items.quantity` (integer, required)
    Number of product units.
    Example: 1

  - `items.line_items.tax` (object)
    Tax details for the line item.

  - `items.line_items.tax.category_id` (string)
    Identifier of the tax category.
    Example: taxc_01JJVD830C789HBQVTVCWJ6AK2

  - `items.line_items.tax.mode` (string)
    Tax calculation mode.
    Enum: "EXCLUSIVE", "INCLUSIVE"

  - `items.line_items.tax.rate` (number)
    Tax rate as a percentage.
    Example: 10

  - `items.customer` (object, required)
    Represents customer snapshot details for invoice.
    Example: {"id":"cust_01KMG2ABYPF6XS5DMJQ817C429","first_name":"John","last_name":"Doe","email":"customer@example.com","phone":"+1234567890","address":{"city":"Anytown","country":"USA","line1":"123 Main St","li…

  - `items.customer.id` (string, required)
    Unique customer identifier.
    Example: cust_01KMG2ABYPF6XS5DMJQ817C429

  - `items.customer.first_name` (string)
    Customer first name.
    Example: John

  - `items.customer.last_name` (string)
    Customer last name.
    Example: Doe

  - `items.customer.email` (string)
    Customer email.
    Example: customer@example.com

  - `items.customer.phone` (string)
    Customer phone number.
    Example: +1234567890

  - `items.customer.address` (object)
    Customer address.

  - `items.customer.address.city` (string)
    City name.
    Example: Anytown

  - `items.customer.address.country` (string)
    Country according to the ISO-3166 alpha-3 country code.
    Example: USA

  - `items.customer.address.line1` (string)
    Address line 1.
    Example: 123 Main St

  - `items.customer.address.line2` (string)
    Address line 2.
    Example: Suite 456

  - `items.customer.address.state` (string)
    State or province.
    Example: CA

  - `items.customer.address.postal_code` (string)
    Postal or ZIP code.
    Example: 12345

  - `items.customer.tax` (object, required)
    Provides customer tax information.

  - `items.customer.tax.taxability` (string, required)
    Indicates if the customer is subject to tax.
The list of enum values may be extended without notice.
    Enum: "EXEMPT", "TAXABLE"

  - `items.subscription_id` (string)
    Identifier of the associated subscription.
    Example: subs_01HYDYBRKN16B8X3BR9WP78ZR7

  - `items.billing_reason` (string)
    Reason why the invoice was created.
The list of enum values may be extended without notice.
    Enum: "MANUAL", "SUBSCRIPTION_CREATE", "SUBSCRIPTION_CYCLE", "SUBSCRIPTION_UPDATE"

  - `items.due_at` (string)
    Date and time when the invoice is due.
    Example: 2026-01-24T11:45:00.000000Z

  - `items.amount_details` (object, required)
    Represents invoice amount details.
    Example: {"subtotal":1000,"discount":100,"taxable":900,"tax":90,"balance_applied":90}

  - `items.amount_details.subtotal` (integer, required)
    Subtotal amount in minor units before discounts and taxes.
    Example: 1000

  - `items.amount_details.discount` (integer, required)
    Discount amount in minor units.
    Example: 100

  - `items.amount_details.taxable` (integer)
    Taxable amount in minor units.
    Example: 900

  - `items.amount_details.tax` (integer)
    Tax amount in minor units.
    Example: 90

  - `items.amount_details.balance_applied` (integer)
    Customer balance amount applied to the invoice in minor units.
    Example: 90

  - `items.amount_details.balance_credited` (integer)
    Amount credited back to the customer balance in minor units.
    Example: 90

  - `items.discounts` (array)
    Discounts applied to the invoice.
    Example: [{"coupon_id":"0291b87b-deac-4eb4-8732-2a70d247a171","coupon_code":"WINTER25","calculation_type":"PERCENTAGE","calculation_value":25}]

  - `items.discounts.coupon_id` (string)
    Unique identifier of the associated coupon.
    Example: 0291b87b-deac-4eb4-8732-2a70d247a171

  - `items.discounts.coupon_code` (string)
    Code of the associated coupon.
    Example: WINTER25

  - `items.discounts.calculation_type` (string)
    Discount calculation type.
The list of enum values may be extended without notice.
    Enum: "PERCENTAGE", "AMOUNT"

  - `items.discounts.calculation_value` (number)
    Discount calculation value. Percent for `PERCENTAGE`, minor units for `AMOUNT`.
    Example: 25

  - `items.notes` (string)
    Additional notes for the invoice.
    Example: Base pack

  - `items.merchant_reference` (string)
    Merchant-defined reference for the invoice.
    Example: INV-2026-00042

  - `items.pdf_url` (string)
    URL to download the invoice PDF.
    Example: https://billing.solidgate.com/invoices/Mjc3MzppbnZfMDFLWEcxWVJLS0Q1UVZRS0Y0MlNRWkg3QzI6MDpveVVjc2RKTjFkZUpSU1FNZE5WX1NR/pdf

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. Omitted when no pages remain.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: One or more fields failed validation due to constraints

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.

## Response 401:

  - `401` (unknown)
    Unauthenticated

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: Credentials are invalid or missing

## Response 403:

  - `403` (unknown)
    Unauthorized

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: Permission denied

## Response 429:

  - `429` (unknown)
    Too many requests

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: Rate limit exhausted

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: 2024-12-31T23:59:59.000000Z

