---
title: "Get Invoices By Filter"
method: POST
path: "/invoice/filter"
---

# Get Invoices By Filter

`POST /invoice/filter`

## Request

- Base URL: `https://dc-region.zuperpro.com/api`
- URL: `https://dc-region.zuperpro.com/api/invoice/filter`
- Auth: API key in header `x-api-key`

Rule-engine-based list endpoint — an alternative to the simple `filter.*` query params on the plain list endpoint, for building complex AND/OR filter conditions. Get the field key enum for filter_rules from the corresponding Meta Filter endpoint. `fields_to_select` is restricted to a fixed allowlist of fields: `invoice_uid`, `invoice_no`, `prefix`, `associations`, `reference_no`, `invoice_title`, `estimate`, `job`, `customer`, `customer_name`, `service_contract`, `invoice_date`, `invoice_date_dt`, `amount_paid`, `amount_due`, `due_date`, `due_date_dt`, `total`, `tags`, `invoice_status`, `custom_fields`, `custom_field_internal_object`, `is_deleted`, `is_active`, `is_paid`, `created_by`, `created_at`, `updated_at`, `external_id`, `external_status`, `paid_date`, `time_to_pay`, `payment_history`, `business_unit`. Supports cursor pagination — pass `cursor_pagination: true` (or any of `cursor`/`prev_cursor`/`last_page`) to switch response modes.

## Request body

- object
  - `page` integer
  - `limit` integer: Max 1000 — larger values are rejected.
  - `sort` 'ASC' | 'DESC'
  - `sort_by` 'invoice_date' | 'due_date' | 'invoice_no' | 'created_at' | 'updated_at' | 'total' | 'amount_paid' | 'amount_due'
  - `filter_rules` object[]: Rule-engine filter conditions, ANDed/ORed per filter_rule_operator. `type` must match the type this module's Meta Filter endpoint declares for that `key` (`fieldDataKey`) — sending the wrong `type` is rejected. Some shared keys require `module: "INVOICE"` since the query engine branches on it directly.
    - `key` 'invoice_no' | 'reference_no' | 'invoice_date' | 'paid_date' | 'due_date' | 'estimate_uid' | 'customer_uid' | 'invoice_status' | 'total' | 'is_paid' | 'created_at' | 'bu_uid' | 'active_campaign_uid' | 'keyword': Get the full current list from this module's Meta Filter endpoint.
    - `operator` 'EQUAL_TO' | 'NOT_EQUAL_TO' | 'CONTAINS' | 'NOT_CONTAINS' | 'GREATER_THAN' | 'LESS_THAN' | 'BETWEEN' | 'IS_EMPTY' | 'IS_NOT_EMPTY'
    - `value` unknown
    - `type` 'default_field' | 'nested_field' | 'custom_field'
    - `module` string
  - `filter_rule_operator` 'AND' | 'OR'
  - `fields_to_select` string: Sparse fieldset selector.
  - `preferred_timezone` string
  - `cursor` string
  - `prev_cursor` string
  - `cursor_pagination` boolean: Switches the response to the cursor-paginated shape.
  - `last_page` boolean

## Response `200`

200

- object
  - `type` 'success'
  - `data` object[]: Invoice documents — same shape as GET /invoice.
  - `total_records` integer
  - `current_page` integer: 0 in cursor-paginated mode.
  - `total_pages` integer: 0 in cursor-paginated mode.
  - `paging` object, nullable: Populated only in cursor-paginated mode.
    - `next` string, nullable
    - `previous` string, nullable
    - `has_more` boolean

## Other responses

- `400`: 400

## Changes

- **2026-11-03** `3c21bc232e16`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zuper/apis/zuper-pro-api/changes/invoice/filter/post.md)

---

[API](https://skmtc.dev/zuper/apis/zuper-pro-api.md) - [All operations](https://skmtc.dev/zuper/apis/zuper-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zuper/apis/zuper-pro-api/revisions/3c21bc232e16?raw)