# Filter invoices

```http
POST https://secure.yoprint.com/v2/api/store/{team_slug}/v2/invoice/filter
```

- API version: v2
- Operation ID: `v2_public_invoice_filter`
- Section: Invoices and payments › [Invoices](https://developer.yoprint.com/reference/invoices.md)
- Web page: https://developer.yoprint.com/reference/invoices/v2-invoice-filter/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Returns one page of your team's invoices that match the filters, newest first unless you sort. Invoices of sales orders and of quotes are both included (filter on `quote`); invoices of deleted, draft or unsaved orders are not.

Each filter needs `key`, `operator` and `value`, and every filter must match. A filter that breaks the table is a 422 whose message is the bare rule name `validation.filter_rule`.

| `key` | `operator` | `value` |
| --- | --- | --- |
| `payment_status` | `eq` | `paid` (paid amount at least the total, total above 0), `unpaid` (total above the paid amount, total above 0), or `overdue` (unpaid, the order has a full payment due date set, and that date is before today in UTC). Invoices with a zero total or orders without a due date never match `overdue`. |
| `quote` | `eq` | `true` for invoices of quotes, `false` for invoices of sales orders. |
| `order_status_id` | `in`, `nin` | Sales order status hash ids. |
| `order_customer_id` | `in`, `nin` | Customer hash ids. |
| `external_type` | `in`, `nin` | `shopify`, `native`. |
| `order_issue_date`, `order_cust_due_date`, `order_ship_due_date`, `deposit_due`, `full_amount_due` | `eq`, `gte`, `lte` | A whole number of days from today in UTC: 0 today, 7 a week ahead, -7 a week ago. Compared by date. |
| `created_at` | `gte`, `lte` | Days from today, as above, but compared with the creation time: `gte` N includes that day, `lte` N stops at its first second, and `eq` matches almost nothing. |

`sort` is an array, but only its first entry is used. The page size is the team's list page size setting (50 unless changed); send `page` for later pages. `count_only: true` returns just `pagination` with empty `data`; `with: ["items"]` adds each invoice's lines.

This list covers invoices made in the current invoice system.

## Permission

Needs Manage Sales Orders at "view all" (every invoice) or "view assigned" (invoices of orders you created or are assigned to). Otherwise 403 "You do not have permission to view this resource".

## Business rules

- Dates are whole days from today in UTC, never absolute dates; `bt` isn't accepted. The order date keys compare whole days and include day N. `created_at` is compared with the creation time: `gte N` starts at 00:00 UTC of day N and `lte N` stops at 00:00 UTC of day N.
- The `quote` filter only supports the `eq` operator. The backend ignores the operator and checks only `value`, so sending `neq` behaves identically to `eq`. Always use `eq` with `true` (for quotes) or `false` (for sales orders).

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.

## Request body

Content type `application/json`, optional.

Fields:

- `count_only` (boolean, optional): Return only the count in `pagination`. Default `false`.
- `filters` (array of objects, optional)
  - Each item:
    - `key` (string, required): One of: `"payment_status"`, `"quote"`, `"order_status_id"`, `"order_customer_id"`, `"external_type"`, `"order_issue_date"`, `"order_cust_due_date"`, `"order_ship_due_date"`, `"deposit_due"`, `"full_amount_due"`, `"created_at"`.
    - `operator` (string, required): One of: `"eq"`, `"neq"`, `"gte"`, `"lte"`, `"in"`, `"nin"`.
    - `value` (string | number | boolean | array, required)
- `page` (integer, optional): Default `1`. Minimum 1.
- `sort` (array of objects, optional): Only the first entry is used. Default: `created_at` `desc`.
  - Each item:
    - `direction` (string, required): One of: `"asc"`, `"desc"`.
    - `key` (string, required): `scoped_id` sorts as text. One of: `"order_id"`, `"scoped_id"`, `"created_at"`, `"order_issue_date"`, `"full_amount_due"`, `"deposit_due"`, `"order_cust_due_date"`, `"order_ship_due_date"`, `"order_status_id"`.
- `with` (array of strings, optional): Add each invoice's lines. One of: `"items"`.

### Example request

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/filter' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": [
      {
        "key": "payment_status",
        "operator": "eq",
        "value": "unpaid"
      },
      {
        "key": "quote",
        "operator": "eq",
        "value": false
      },
      {
        "key": "full_amount_due",
        "operator": "lte",
        "value": 0
      }
    ],
    "page": 1,
    "sort": [
      {
        "direction": "asc",
        "key": "full_amount_due"
      }
    ]
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (array of objects, required)
  - Each item:
    - `auto_invoice_managed` (boolean, optional): YoPrint keeps this invoice in step with the order (Auto Invoice).
    - `bill_to_status` (string, optional): How Bill To compares with the order's. One of: `"okay"`, `"empty"`, `"diff_from_order"`, `"diff_from_customer"`.
    - `billing_address` (object | null, optional): An address.
      - `address1` (string | null, optional)
      - `address2` (string | null, optional)
      - `city` (string | null, optional)
      - `country` (string | null, optional)
      - `country_code` (string | null, optional)
      - `id` (string, optional): The address.
      - `label` (string | null, optional)
      - `postcode` (string | null, optional)
      - `state` (string | null, optional)
      - `state_code` (string | null, optional)
    - `billing_address_id` (string | null, optional): Bill To.
    - `calc_deposit_total` (integer | number | string | null, optional): The order's deposit amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
    - `cart_item_subtotal` (decimal pair, optional): Billed sales order lines and shipping fees (price × quantity); `shipment_subtotal` is the shipping part of it. `total` = `cart_item_subtotal` − `discount_subtotal` + `tax_subtotal` (+ `credit_card_surcharge`). At the stored scale (4 decimal places). A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `created_at` (string (date-time), optional)
    - `credit_card_surcharge` (decimal pair, optional): A card surcharge added by a card payment; zero when there is none. Always sent. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `customer` (object | null, optional): The customer (the full customer record).
      - `id` (string, optional): The customer.
      - `name` (string, optional)
    - `deposit_due` (string (date-time) | null, optional): From the order. ISO 8601 with offset, or null.
    - `deposit_required` (boolean | integer | null, optional): From the order.
    - `discount_subtotal` (decimal pair, optional): Discounts. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `external_type` (string | null, optional)
    - `from_legacy` (boolean, optional)
    - `full_amount_due` (string (date-time) | null, optional): From the order. ISO 8601 with offset, or null.
    - `id` (string, optional): The invoice.
    - `is_external` (boolean, optional)
    - `is_paid` (boolean, optional): Paid amount covers the total (also true for a zero total).
    - `is_valid` (boolean, optional): False when the invoice needs fixing: no lines, lines without a tax line, or a customer that differs from the order's.
    - `issue_date` (string (date-time) | null, optional): Issue date. ISO 8601 with offset, or null.
    - `lock_version` (integer, optional)
    - `order` (object, optional): The sales order or quote in the v2 order shape: its header fields, with `status` and `assigned_users`, but no `items`.
      - `id` (string, optional): The order.
      - `scoped_id` (string | null, optional)
    - `order_id` (string, optional): The sales order or quote it bills.
    - `order_object_type` (string | null, optional): `sales_order` or `quote`.
    - `order_quote` (boolean, optional): The order is a quote.
    - `order_scoped_id` (string | null, optional): The order number.
    - `paid_amount` (integer | number | string | null, optional): Allocated payments. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
    - `pdf_url` (array of objects, optional): PDF links.
      - Each item:
        - `label` (string, optional)
        - `object_type` (string, optional)
        - `url` (string, optional): A download link with its own long-lived access token: don't publish it.
    - `scoped_id` (string | null, optional): The invoice number.
    - `ship_to_status` (string, optional): One of: `"okay"`, `"empty"`, `"diff_from_order"`, `"diff_from_customer"`.
    - `shipment_subtotal` (decimal pair, optional): Shipping fees (already in `cart_item_subtotal`). A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `shipment_tax_subtotal` (decimal pair, optional): The tax on shipping (included in `tax_subtotal`). A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `shipping_address` (object | null, optional): An address. Same fields as `data[].billing_address` above.
    - `shipping_address_id` (string | null, optional): Ship To.
    - `tax_subtotal` (decimal pair, optional): Tax. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `total` (decimal pair, optional): The invoice total. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `version` (integer, optional)
    - `calc_delivery_total` (integer | number | string | null, optional, deprecated): **Deprecated:** use `shipment_subtotal`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
    - `calc_discount` (integer | number | string | null, optional, deprecated): **Deprecated:** use `discount_subtotal`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
    - `calc_subtotal` (integer | number | string | null, optional, deprecated): **Deprecated:** use `cart_item_subtotal`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
    - `calc_tax` (integer | number | string | null, optional, deprecated): **Deprecated:** use `tax_subtotal`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
    - `calc_total` (integer | number | string | null, optional, deprecated): **Deprecated:** use `total`, the same amount. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
- `status` (integer, required)
- `success` (boolean, required)
- `pagination` (object, optional)
  - `count` (integer, required)
  - `currentPage` (integer, required)
  - `links` (object | array of any, required): Links to the neighbouring pages: `previous` and `next`, each present only when that page exists. An empty list, `[]`, when there is only one page.
    - `next` (string (uri), optional): The next page.
    - `previous` (string (uri), optional): The previous page.
  - `perPage` (integer, required)
  - `total` (integer, required)
  - `totalPages` (integer, required)

Example response:

```json
{
  "data": [
    {
      "auto_invoice_managed": false,
      "bill_to_status": "okay",
      "billing_address": {
        "address1": "100 Example Street",
        "address2": null,
        "city": "Austin",
        "country": "United States",
        "country_code": "US",
        "id": "117KfwwfreX15N",
        "label": "Main office",
        "postcode": "78701",
        "state": "Texas",
        "state_code": "TX"
      },
      "billing_address_id": "117KfwwfreX15N",
      "calc_deposit_total": 169880,
      "cart_item_subtotal": {
        "dp": 4,
        "value": 3150000
      },
      "created_at": "2026-11-03T15:00:00+00:00",
      "credit_card_surcharge": {
        "dp": 4,
        "value": 0
      },
      "customer": {
        "id": "ifAHmADekGZ6id",
        "name": "Northwind Apparel"
      },
      "deposit_due": "2026-11-05T00:00:00+00:00",
      "deposit_required": true,
      "discount_subtotal": {
        "dp": 4,
        "value": 0
      },
      "external_type": null,
      "from_legacy": false,
      "full_amount_due": "2026-11-20T00:00:00+00:00",
      "id": "cBRpSf5nw6upt5",
      "is_external": false,
      "is_paid": false,
      "is_valid": true,
      "issue_date": "2026-11-03T00:00:00+00:00",
      "lock_version": 1730000000000000,
      "order": {
        "id": "sFbALVSYD55eXe",
        "scoped_id": "SO1001"
      },
      "order_id": "sFbALVSYD55eXe",
      "order_object_type": "sales_order",
      "order_quote": false,
      "order_scoped_id": "SO1001",
      "paid_amount": 100000,
      "pdf_url": [
        {
          "description": "Invoice pdf",
          "label": "Invoice",
          "object_type": "invoice",
          "url": "https://example.com/pdf/invoice.pdf"
        }
      ],
      "scoped_id": "1001",
      "ship_to_status": "okay",
      "shipment_subtotal": {
        "dp": 4,
        "value": 150000
      },
      "shipment_tax_subtotal": {
        "dp": 4,
        "value": 0
      },
      "shipping_address": {
        "address1": "100 Example Street",
        "address2": null,
        "city": "Austin",
        "country": "United States",
        "country_code": "US",
        "id": "117KfwwfreX15N",
        "label": "Main office",
        "postcode": "78701",
        "state": "Texas",
        "state_code": "TX"
      },
      "shipping_address_id": "117KfwwfreX15N",
      "tax_subtotal": {
        "dp": 4,
        "value": 247500
      },
      "total": {
        "dp": 4,
        "value": 3397500
      },
      "version": 2
    }
  ],
  "pagination": {
    "count": 1,
    "currentPage": 1,
    "links": [],
    "perPage": 50,
    "total": 1,
    "totalPages": 1
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
  - When: Your role can't view sales orders. Fix: Ask the team owner for Manage Sales Orders view access.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: A filter breaks the table (`validation.filter_rule`) or a sort key isn't listed (`validation.filter_sort_rule`). Fix: Check each filter and sort entry against the table.

## Related

- [Get an invoice](https://developer.yoprint.com/reference/invoices/v2-invoice-show.md): `GET /v2/api/store/{team_slug}/v2/invoice/{unique_key}`
- [List invoices (v1)](https://developer.yoprint.com/reference/invoices/v1-invoice-index.md): `GET /v1/api/store/{team_slug}/invoice`
- [Download invoices as one PDF](https://developer.yoprint.com/reference/invoices/v1-invoice-export-pdf.md): `POST /v1/api/store/{team_slug}/invoice/export_pdf`