Filter invoices

POST/v2/api/store/{team_slug}/v2/invoice/filter

v2Operation ID v2_public_invoice_filter

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_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team

Request body

application/json, optional.

count_onlyboolean
Return only the count in pagination.
- Default false
filtersarray of objects
Fields of each item (3)
- keystringrequired
  - 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"
- operatorstringrequired
  - One of: "eq", "neq", "gte", "lte", "in", "nin"
- valuestring | number | boolean | arrayrequired
pageinteger
- Default 1
- Minimum 1
sortarray of objects
Only the first entry is used. Default: created_at desc.
Fields of each item (2)
- directionstringrequired
  - One of: "asc", "desc"
- keystringrequired
  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"
witharray of strings
Add each invoice's lines.
- Each item is one of: "items"

Response

200Successful response.

dataarray of objectsrequired
Fields of each item (42)
- auto_invoice_managedboolean
  YoPrint keeps this invoice in step with the order (Auto Invoice).
- bill_to_statusstring
  How Bill To compares with the order's.
  - One of: "okay", "empty", "diff_from_order", "diff_from_customer"
- billing_addressobject | null
  An address.
  Child fields (10)
  - address1string | null
  - address2string | null
  - citystring | null
  - countrystring | null
  - country_codestring | null
  - idstring
    The address.
  - labelstring | null
  - postcodestring | null
  - statestring | null
  - state_codestring | null
- billing_address_idstring | null
  Bill To.
- calc_deposit_totalinteger | number | string | null
  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.
- cart_item_subtotaldecimal pair
  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 Money and quantities.
- created_atstring (date-time)
- credit_card_surchargedecimal pair
  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 Money and quantities.
- customerobject | null
  The customer (the full customer record).
  Child fields (2)
  - idstring
    The customer.
  - namestring
- deposit_duestring (date-time) | null
  From the order. ISO 8601 with offset, or null.
- deposit_requiredboolean | integer | null
  From the order.
- discount_subtotaldecimal pair
  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 Money and quantities.
- external_typestring | null
- from_legacyboolean
- full_amount_duestring (date-time) | null
  From the order. ISO 8601 with offset, or null.
- idstring
  The invoice.
- is_externalboolean
- is_paidboolean
  Paid amount covers the total (also true for a zero total).
- is_validboolean
  False when the invoice needs fixing: no lines, lines without a tax line, or a customer that differs from the order's.
- issue_datestring (date-time) | null
  Issue date. ISO 8601 with offset, or null.
- lock_versioninteger
- orderobject
  The sales order or quote in the v2 order shape: its header fields, with status and assigned_users, but no items.
  Child fields (2)
  - idstring
    The order.
  - scoped_idstring | null
- order_idstring
  The sales order or quote it bills.
- order_object_typestring | null
  sales_order or quote.
- order_quoteboolean
  The order is a quote.
- order_scoped_idstring | null
  The order number.
- paid_amountinteger | number | string | null
  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.
- pdf_urlarray of objects
  PDF links.
  Fields of each item (3)
  - labelstring
  - object_typestring
  - urlstring
    A download link with its own long-lived access token: don't publish it.
- scoped_idstring | null
  The invoice number.
- ship_to_statusstring
  - One of: "okay", "empty", "diff_from_order", "diff_from_customer"
- shipment_subtotaldecimal pair
  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 Money and quantities.
- shipment_tax_subtotaldecimal pair
  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 Money and quantities.
- shipping_addressobject | null
  An address.
  - Same fields as data[].billing_address.
- shipping_address_idstring | null
  Ship To.
- tax_subtotaldecimal pair
  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 Money and quantities.
- totaldecimal pair
  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 Money and quantities.
- versioninteger
- calc_delivery_totalinteger | number | string | nulldeprecated
  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.
- calc_discountinteger | number | string | nulldeprecated
  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.
- calc_subtotalinteger | number | string | nulldeprecated
  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.
- calc_taxinteger | number | string | nulldeprecated
  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.
- calc_totalinteger | number | string | nulldeprecated
  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.
statusintegerrequired
successbooleanrequired
paginationobject
Child fields (6)
- countintegerrequired
- currentPageintegerrequired
- linksobject | array of anyrequired
  Links to the neighbouring pages: previous and next, each present only when that page exists. An empty list, [], when there is only one page.
  Child fields (2)
  - nextstring (uri)
    The next page.
  - previousstring (uri)
    The previous page.
- perPageintegerrequired
- totalintegerrequired
- totalPagesintegerrequired

Errors

401The API key is missing or wrong (unauthenticated).
403You 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.
404Not 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.
422The 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.

GETGet an invoice/v2/api/store/{team_slug}/v2/invoice/{unique_key}
GETList invoices (v1)/v1/api/store/{team_slug}/invoice
POSTDownload invoices as one PDF/v1/api/store/{team_slug}/invoice/export_pdf

Example request

curl

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"      }    ]  }'

Example response 200

{
  "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
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com