> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt > Use this file to discover all available pages before exploring further. # Search invoices > Search your invoices, both subscription and standalone. Filters combine with AND, and at least one must be provided (`ordering` alone is not enough). Empty arrays are treated as omitted. To list a customer's standalone invoices, send `customer_id` with an explicit `subscription_id: null`. **Statuses** are the raw invoice statuses the response's `status` field reports. Voided invoices are included in results by default; they are excluded only when a `statuses` filter is provided that does not include `VOIDED`. **Dates.** All `*_date_min` / `*_date_max` bounds are inclusive and interpreted in your account's timezone (`_min` expands to start of day, `_max` to end of day). `issued_date` filters on the invoice's billing-run date and `paid_date` on when it was fully paid. A `due_date` range filters on the due date only — it does not implicitly exclude paid invoices; combine with `statuses` to narrow. **Days past due** is the number of whole days between the due date and now. Invoices with no outstanding balance (fully paid, or nothing due) have no days-past-due value and never match a `days_past_due` filter. For AR-aging queries combine with `"statuses": ["PAST_DUE"]`. **Amounts** are integer minor currency units (e.g. cents). `amount_due` is the remaining unpaid amount; `paid_amount` is the total paid so far, including partial payments. **`search_term`** matches invoice numbers, customer names, invoice UUIDs, and amounts. **Ordering** takes a single field name with an optional `-` prefix for descending: `issued_at`, `due_at`, or `amount_due` (remaining amount). Defaults to newest first. Pagination is handled via query params (limit, offset). ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml post /invoices/search openapi: 3.0.3 info: title: Salesbricks REST API version: 2.0.0 description: API reference for external integrations servers: - url: https://api.salesbricks.com/api/v2 description: Production - url: https://api.staging.salesbricks.com/api/v2 description: Staging security: - ApiKeyAuth: [] tags: - name: Subscriptions description: >- Operations related to subscription management, including creation, updates, and retrieving subscription details. Subscriptions can be upgraded to add / remove add-ons by using the POST /subscriptions/{subscription_id}/upgrade endpoint and can be recasted for replacing the current agreement using the POST /subscriptions/{subscription_id}/recast endpoint - name: Customers description: >- Operations related to customer management, including creation, updates, and managing customer person objects. - name: Invoices description: Operations related to subscription's invoicing details. - name: Plans description: >- Operations related to listing and getting plan details including bricks in the plan. - name: Payment Methods description: Operations related to subscription's payment method. paths: /invoices/search: post: tags: - Invoices summary: Search invoices description: > Search your invoices, both subscription and standalone. Filters combine with AND, and at least one must be provided (`ordering` alone is not enough). Empty arrays are treated as omitted. To list a customer's standalone invoices, send `customer_id` with an explicit `subscription_id: null`. **Statuses** are the raw invoice statuses the response's `status` field reports. Voided invoices are included in results by default; they are excluded only when a `statuses` filter is provided that does not include `VOIDED`. **Dates.** All `*_date_min` / `*_date_max` bounds are inclusive and interpreted in your account's timezone (`_min` expands to start of day, `_max` to end of day). `issued_date` filters on the invoice's billing-run date and `paid_date` on when it was fully paid. A `due_date` range filters on the due date only — it does not implicitly exclude paid invoices; combine with `statuses` to narrow. **Days past due** is the number of whole days between the due date and now. Invoices with no outstanding balance (fully paid, or nothing due) have no days-past-due value and never match a `days_past_due` filter. For AR-aging queries combine with `"statuses": ["PAST_DUE"]`. **Amounts** are integer minor currency units (e.g. cents). `amount_due` is the remaining unpaid amount; `paid_amount` is the total paid so far, including partial payments. **`search_term`** matches invoice numbers, customer names, invoice UUIDs, and amounts. **Ordering** takes a single field name with an optional `-` prefix for descending: `issued_at`, `due_at`, or `amount_due` (remaining amount). Defaults to newest first. Pagination is handled via query params (limit, offset). operationId: searchInvoices parameters: - name: limit required: false in: query description: Number of results to return per page. schema: type: integer - name: offset required: false in: query description: The initial index from which to return the results. schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/InvoiceSearchInput' examples: Past-dueInvoicesForACustomer: value: customer_id: 11111111-2222-3333-4444-555555555555 statuses: - PAST_DUE ordering: '-due_at' summary: Past-due invoices for a customer UnpaidInvoicesDueThisQuarter: value: statuses: - DUE - OUTSTANDING - UNPAID - PAST_DUE - PARTIALLY_PAID due_date_min: '2026-01-01' due_date_max: '2026-03-31' summary: Unpaid invoices due this quarter ARAging:30+DaysPastDueOver$100: value: statuses: - PAST_DUE days_past_due_min: 30 amount_due_min: 10000 ordering: '-amount_due' summary: 'AR aging: 30+ days past due over $100' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/InvoiceSearchInput' multipart/form-data: schema: $ref: '#/components/schemas/InvoiceSearchInput' responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedInvoiceList' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' components: schemas: InvoiceSearchInput: type: object description: Mixin for validating a seller-supplied `metadata` input. properties: invoice_numbers: type: array items: type: string description: Filter invoices by invoice number (e.g. '6c12021a-4') invoice_ids: type: array items: type: string format: uuid description: Filter invoices by invoice ID customer_id: type: string format: uuid description: Filter invoices by customer ID subscription_id: type: string format: uuid nullable: true description: >- Filter invoices by subscription ID. Pass null to match invoices with no subscription. Omit to apply no subscription filter. statuses: type: array items: enum: - MUTED - SCHEDULED - DRAFT - OUTSTANDING - DUE - PAST_DUE - PAID - PARTIALLY_PAID - ADJUSTED - CREDITED - UNPAID - PAUSED - VOIDED type: string description: |- * `MUTED` - Muted * `SCHEDULED` - Scheduled * `DRAFT` - Draft * `OUTSTANDING` - Outstanding * `DUE` - Due * `PAST_DUE` - Past due * `PAID` - Paid * `PARTIALLY_PAID` - Partially Paid * `ADJUSTED` - Adjusted * `CREDITED` - Credited * `UNPAID` - Unpaid * `PAUSED` - Paused * `VOIDED` - Voided x-spec-enum-id: 67bd66efb8e391e6 description: > Filter invoices by status. Current status of the invoice. One of: - `MUTED` — Invoice will not be sent. Muted invoices come from migration cut-overs or from muting invoices in the product settings. - `SCHEDULED` — Scheduled to be issued on a future date. - `OUTSTANDING` — Issued and awaiting payment. - `DUE` — Payment is due. - `PAST_DUE` — Payment is past its due date. - `PAID` — Fully paid. - `PARTIALLY_PAID` — Partially paid, with a remaining balance. - `ADJUSTED` — Adjusted after issuance. - `CREDITED` — Settled by applying credit. - `UNPAID` — Unpaid. - `PAUSED` — Collection is paused. - `VOIDED` — Voided and no longer collectible. currencies: type: array items: enum: - USD - EUR - GBP - AUD - CAD - INR type: string description: |- * `USD` - United States Dollar * `EUR` - Euros * `GBP` - Great British Pound * `AUD` - Australian Dollar * `CAD` - Canadian Dollar * `INR` - Indian Rupee x-spec-enum-id: fde863feba7c4cf4 description: Filter invoices by currency (e.g. USD, EUR) metadata: type: object additionalProperties: {} description: >- Filter invoices by metadata. All supplied key/value pairs must be present on the invoice. due_date_min: type: string format: date description: >- Earliest due date (inclusive, start of day in your account's timezone). Filters on due date only — paid invoices are not implicitly excluded; combine with statuses to narrow. due_date_max: type: string format: date description: Latest due date (inclusive, end of day in your account's timezone). issued_date_min: type: string format: date description: >- Earliest invoice date (inclusive, start of day in your account's timezone). Filters on the invoice's billing-run date — the date the invoice was generated. issued_date_max: type: string format: date description: >- Latest invoice date (inclusive, end of day in your account's timezone). paid_date_min: type: string format: date description: >- Earliest fully-paid date (inclusive, start of day in your account's timezone). paid_date_max: type: string format: date description: >- Latest fully-paid date (inclusive, end of day in your account's timezone). days_past_due_min: type: integer minimum: 0 description: >- Minimum days between the due date and now (inclusive). Invoices with no outstanding balance have no days-past-due value and never match this filter. days_past_due_max: type: integer minimum: 0 description: Maximum days between the due date and now (inclusive). amount_due_min: type: integer description: Minimum remaining unpaid amount in minor currency units (inclusive). amount_due_max: type: integer description: Maximum remaining unpaid amount in minor currency units (inclusive). paid_amount_min: type: integer description: >- Minimum total paid amount (including partial payments) in minor currency units (inclusive). paid_amount_max: type: integer description: >- Maximum total paid amount (including partial payments) in minor currency units (inclusive). search_term: type: string description: >- Free-text search across invoice numbers, customer names, invoice UUIDs, and amounts. ordering: enum: - issued_at - '-issued_at' - due_at - '-due_at' - amount_due - '-amount_due' type: string x-spec-enum-id: 3e8c481f57f0bb02 description: >- Order results by field, prefixed with '-' for descending. 'amount_due' is the remaining amount. Defaults to newest first. * `issued_at` - issued_at * `-issued_at` - -issued_at * `due_at` - due_at * `-due_at` - -due_at * `amount_due` - amount_due * `-amount_due` - -amount_due PaginatedInvoiceList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=400&limit=100 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=200&limit=100 results: type: array items: $ref: '#/components/schemas/Invoice' ErrorResponse: type: object description: >- Standardizes API error responses with a consistent structure containing error code and message. properties: error: $ref: '#/components/schemas/Error' required: - error Invoice: type: object properties: invoice_id: type: string format: uuid description: >- Unique identifier for the invoice. If the id is null, this is an estimate subscription_id: type: string format: uuid description: >- ID of the subscription this invoice belongs to. Null for standalone (one-off) invoices. customer_id: type: string format: uuid description: ID of the customer who will pay this invoice customer_name: type: string description: Name of the customer who will pay this invoice invoice_number: type: string description: >- Short form identifier for the invoice. If the invoice_number is null, this is an estimate time_zone: type: string description: Invoice timezone due_at: type: string format: date-time description: The date on which this invoice is expected to be paid by. bill_at: type: string format: date-time description: >- The date on which this invoice will be issued and potentially charged. issued_at: type: string format: date-time description: The date on which this invoice was issued. status: type: string description: > Current status of the invoice. One of: - `MUTED` — Invoice will not be sent. Muted invoices come from migration cut-overs or from muting invoices in the product settings. - `SCHEDULED` — Scheduled to be issued on a future date. - `OUTSTANDING` — Issued and awaiting payment. - `DUE` — Payment is due. - `PAST_DUE` — Payment is past its due date. - `PAID` — Fully paid. - `PARTIALLY_PAID` — Partially paid, with a remaining balance. - `ADJUSTED` — Adjusted after issuance. - `CREDITED` — Settled by applying credit. - `UNPAID` — Unpaid. - `PAUSED` — Collection is paused. - `VOIDED` — Voided and no longer collectible. fully_paid_at: type: string format: date-time description: The date on which this invoice was fully paid. grand_total: type: integer description: >- Total amount due for this invoice. Invoices that have not been generated yet (e.g. `SCHEDULED`) report the total expected at the time they were created. That figure does NOT include usage metered since — a usage invoice whose meters have not been priced reports 0. Pass `?calculate_expected_usage=true` to re-price against the order and include estimated usage instead; it is slower, so it is off by default on list endpoints. remaining_amount: type: integer description: Remaining amount for this invoice. currency: type: string description: The currency in which the invoice is denominated (e.g., USD, EUR). is_renewal_estimate: type: boolean description: >- This is an estimate for a renewal that has not yet closed, but is expected to. payments: type: array items: $ref: '#/components/schemas/Payment' description: All payments made against this invoice, newest first. attachments: type: array items: {} description: >- Current attachments for this invoice as a flat array. Each item includes 'target' field indicating invoice or subscription level. Sorted by unified order. line_items: type: array items: $ref: '#/components/schemas/InvoiceLineItemOutput' description: Line item breakdown for this invoice metadata: description: Optional metadata stored against the invoice. required: - bill_at - currency - customer_id - due_at - fully_paid_at - grand_total - invoice_id - invoice_number - is_renewal_estimate - issued_at - remaining_amount - status - subscription_id Error: type: object description: >- Represents individual error details with a standardized code and descriptive message. properties: code: enum: - ERR_NOT_FOUND - ERR_BAD_REQUEST - ERR_SERVER_ERROR type: string x-spec-enum-id: dc5a5d6feae1b697 description: >- Error code indicating the type of error: NOT_FOUND for missing resources, BAD_REQUEST for invalid input, SERVER_ERROR for internal server issues * `ERR_NOT_FOUND` - ERR_NOT_FOUND * `ERR_BAD_REQUEST` - ERR_BAD_REQUEST * `ERR_SERVER_ERROR` - ERR_SERVER_ERROR message: type: string error_id: type: string format: uuid description: >- Correlation handle for SERVER_ERROR responses — quote this when contacting support; it joins to the structured server log line for the failure. Not present on 4xx responses. required: - code - message Payment: type: object properties: payment_id: type: string format: uuid readOnly: true description: Unique identifier for the payment invoice_number: type: string nullable: true readOnly: true description: >- The invoice number this payment was made against, snapshotted from the invoice version current when the payment was recorded — it does not change when the invoice is later regenerated, so it may differ from the invoice's top-level `invoice_number`. Falls back to the invoice's current number when no version is linked. Join payments to invoices by ID, not by number. invoice_version_id: type: string format: uuid readOnly: true nullable: true description: >- Identifier of the invoice version this payment was made against — the version current when the payment was recorded. Null only when the invoice has no versions (it was never generated). paid_amount: type: integer readOnly: true nullable: true description: The amount paid paid_at: type: string format: date-time readOnly: true nullable: true description: the date at which this payment was paid currency: type: string readOnly: true description: The currency in which the payment is denominated (e.g., USD, EUR) error: type: string readOnly: true nullable: true description: Any errors that occured during this payment processing required: - currency - error - invoice_number - invoice_version_id - paid_amount - paid_at - payment_id InvoiceLineItemOutput: type: object properties: brick_name: type: string description: Name of the brick brick_id: type: string nullable: true description: Unique identifier of the brick quantity: type: integer description: Quantity of units tax: type: integer description: Tax amount in minor currency units grand_total: type: integer description: Grand total in minor currency units starts_at: type: string format: date-time nullable: true description: Start of the period this line item covers ends_at: type: string format: date-time nullable: true description: End of the period this line item covers required: - brick_id - brick_name - ends_at - grand_total - quantity - starts_at - tax securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-SALESBRICKS-KEY description: API key for authentication ```` ## Related topics - [MCP](/integrations/mcp.md) - [Search customers](/api-reference/customers/search-customers.md) - [List all customer invoices](/api-reference/invoices/list-all-customer-invoices.md)