# 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 invoice status for `EQ`, or a comma-separated list of statuses for `IN`. Allowed values - `DRAFT`, `OPEN`, `PAID`, `VOIDED`, `DUNNING`, `UNPAID`.
    Example: OPEN,PAID

  - `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)
    Identifier of the customer who owns the invoices.
    Example: cust_01KMG2ABYPF6XS5DMJQ817C429

  - `filters.customer_email` (object)
    Operator and value for customer email filter.

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

  - `filters.customer_email.value` (string, required)
    Email of the customer the invoice was issued to. Exact, case-sensitive match.
    Example: jane.doe@example.com

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

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

  - `filters.subscription_id.value` (string, required)
    Identifier of the associated subscription.
    Example: subs_01HYDYBRKN16B8X3BR9WP78ZR7

  - `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: 12345

  - `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