---
title: "Filter bills"
method: POST
path: "/bills/filter"
tags: ["Bills"]
---

# Filter bills

`POST /bills/filter`

Search for AP bills using filter criteria.

## Common Filters

- By carrier: `{ "filter": { "carrierId": { "equalTo": "uuid" } } }`
- By vendor: `{ "filter": { "vendorId": { "equalTo": "uuid" } } }`
- Awaiting approval: `{ "filter": { "status": { "equalTo": "IN_REVIEW" } } }`
- By shipment: `{ "filter": { "shipmentId": { "equalTo": "uuid" } } }`
- Overdue: `{ "filter": { "overdue": true } }`

## Request body

- BillFilterRequest
  - `filter` BillFilter
    - `id` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `loadCarrierId` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `vendedServiceId` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `carrierId` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `vendorId` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `loadId` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `shipmentId` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `status` BillStatusFilter
      - `equalTo` 'AWAITING_INVOICE' | 'IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID' — Current status of the bill (AP invoice). - `AWAITING_INVOICE`: Waiting for carrier/vendor to submit invoice - `IN_REVIEW`: Invoice received, under review - `APPROVED_TO_PAY`: Approved and ready for payment - `PAID`: Fully paid
      - `notEqualTo` 'AWAITING_INVOICE' | 'IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID' — Current status of the bill (AP invoice). - `AWAITING_INVOICE`: Waiting for carrier/vendor to submit invoice - `IN_REVIEW`: Invoice received, under review - `APPROVED_TO_PAY`: Approved and ready for payment - `PAID`: Fully paid
      - `in` BillStatus[]
      - `notIn` BillStatus[]
    - `entityType` BillEntityTypeFilter
      - `equalTo` 'CARRIER' | 'VENDOR' — Type of entity the bill is for. - `CARRIER`: Bill for a carrier (LoadCarrier) - `VENDOR`: Bill for a vendor service (VendedService)
      - `in` BillEntityType[]
    - `invoiceDate` DatetimeFilter — Filter options for datetime fields
      - `equalTo` string, date-time — Exact match
      - `notEqualTo` string, date-time — Not equal to
      - `lessThan` string, date-time — Before this datetime
      - `lessThanOrEqualTo` string, date-time — On or before this datetime
      - `greaterThan` string, date-time — After this datetime
      - `greaterThanOrEqualTo` string, date-time — On or after this datetime
      - `isNull` boolean — Field is null (true) or not null (false)
    - `dueDate` DatetimeFilter — Filter options for datetime fields
      - `equalTo` string, date-time — Exact match
      - `notEqualTo` string, date-time — Not equal to
      - `lessThan` string, date-time — Before this datetime
      - `lessThanOrEqualTo` string, date-time — On or before this datetime
      - `greaterThan` string, date-time — After this datetime
      - `greaterThanOrEqualTo` string, date-time — On or after this datetime
      - `isNull` boolean — Field is null (true) or not null (false)
    - `amount` FloatFilter — Filter options for float/number fields
      - `equalTo` number, float — Exact match
      - `notEqualTo` number, float — Not equal to
      - `lessThan` number, float — Less than
      - `lessThanOrEqualTo` number, float — Less than or equal to
      - `greaterThan` number, float — Greater than
      - `greaterThanOrEqualTo` number, float — Greater than or equal to
      - `isNull` boolean — Field is null (true) or not null (false)
    - `overdue` boolean — Filter to overdue bills only
    - `createdAt` DatetimeFilter — Filter options for datetime fields
      - `equalTo` string, date-time — Exact match
      - `notEqualTo` string, date-time — Not equal to
      - `lessThan` string, date-time — Before this datetime
      - `lessThanOrEqualTo` string, date-time — On or before this datetime
      - `greaterThan` string, date-time — After this datetime
      - `greaterThanOrEqualTo` string, date-time — On or after this datetime
      - `isNull` boolean — Field is null (true) or not null (false)
    - `and` BillFilter[]
    - `or` BillFilter[]
    - `not` BillFilter — recursive
  - `pageSize` integer
  - `cursor` string

## Response `200`

Bills matching filter criteria

- object
  - `data` Bill[], required
    - `id` string, uuid, required
    - `friendlyId` string, required — Human-readable bill ID
    - `key` string, nullable — Client-defined key
    - `entityType` 'CARRIER' | 'VENDOR', required — Type of entity the bill is for. - `CARRIER`: Bill for a carrier (LoadCarrier) - `VENDOR`: Bill for a vendor service (VendedService)
    - `loadCarrierId` string, uuid, nullable — Associated load carrier ID (if carrier bill)
    - `vendedServiceId` string, uuid, nullable — Associated vended service ID (if vendor bill)
    - `carrier` CarrierReference — Enhanced reference to a carrier resource (returned in responses). Includes full carrier details in addition to id/key. Note: Does NOT include nested references (contacts, etc.) to prevent recursion. Maximum nesting depth: 1 level.
      - `id` string, uuid, required — Carrier UUID
      - `key` string, nullable — Client-defined reference ID if set
      - `name` string, required — Carrier company name
      - `phoneNumber` string, nullable — Primary phone number
      - `email` string, email, nullable — Primary email address
      - `createdAt` string, date-time, required — When the carrier was created
      - `updatedAt` string, date-time, required — When the carrier was last updated
      - `deletedAt` string, date-time, nullable — When the carrier was soft deleted (null if active)
    - `vendor` VendorReference — Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.
      - `id` string, uuid, required — Vendor UUID
      - `key` string, nullable — Client-defined reference ID if set
      - `friendlyId` string, required — Human-readable vendor identifier
      - `name` string, required — Vendor legal name
      - `email` string, email, nullable — Primary email address
      - `phone` string, nullable — Primary phone number
      - `status` string, nullable — Vendor status
      - `currency` string, nullable — Preferred currency code (ISO 4217)
      - `createdAt` string, date-time, required — When the vendor was created
      - `updatedAt` string, date-time, required — When the vendor was last updated
    - `loadId` string, uuid, nullable
    - `loadKey` string, nullable
    - `shipmentId` string, uuid, nullable
    - `shipmentKey` string, nullable
    - `status` 'AWAITING_INVOICE' | 'IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID', required — Current status of the bill (AP invoice). - `AWAITING_INVOICE`: Waiting for carrier/vendor to submit invoice - `IN_REVIEW`: Invoice received, under review - `APPROVED_TO_PAY`: Approved and ready for payment - `PAID`: Fully paid
    - `invoiceDate` string, date, nullable — Date of carrier/vendor invoice
    - `dueDate` string, date, nullable — Payment due date
    - `amount` number, required — Bill amount
    - `currency` string, nullable — Currency code
    - `reference` string, nullable — Carrier/vendor invoice reference number
    - `amountPaid` number — Total payments received
    - `amountOwed` number — Outstanding balance
    - `payments` BillPaymentApplied[] — Payments applied to this bill
      - `id` string, uuid
      - `paymentGroupId` string, uuid
      - `amount` number — Amount applied to this bill
      - `paymentDate` string, date
      - `reference` string, nullable — Check number, transaction ID, etc.
    - `paymentTerm` PaymentTermReference — Enhanced reference to a payment term resource (returned in responses). Includes full payment term details in addition to id/key.
      - `id` string, uuid, required — Payment term UUID
      - `key` string, nullable — Client-defined reference ID if set
      - `name` string, required — Payment term name
      - `description` string, nullable — Payment term description or notes
      - `days` integer, nullable — Number of days until payment is due
      - `quickPayFee` number, float, nullable — Quick pay fee percentage (e.g., 0.05 for 5%)
      - `apOnly` boolean, nullable — Whether this payment term is for accounts payable only
      - `doNotUse` boolean, nullable — Flag to prevent using this payment term for new transactions
      - `createdAt` string, date-time, required — When the payment term was created
      - `updatedAt` string, date-time, required — When the payment term was last updated
      - `deletedAt` string, date-time, nullable — When the payment term was soft deleted (null if active)
    - `carrierFactor` CarrierFactorReference — Enhanced reference to a carrier factor (factoring company). Includes full carrier factor details in addition to id/key.
      - `id` string, uuid, required — Carrier factor UUID
      - `key` string, nullable — Client-defined reference ID if set
      - `companyName` string, required — Factoring company legal name
      - `email` string, email, nullable — Primary email address
      - `phoneNumber` string, nullable — Primary phone number
      - `currency` string, nullable — Preferred currency code (ISO 4217)
      - `createdAt` string, date-time, required — When the carrier factor was created
      - `updatedAt` string, date-time, required — When the carrier factor was last updated
    - `factorJobId` string, nullable — External factoring job ID
    - `factorStatus` string, nullable — Current factoring status
    - `qboId` string, nullable — QuickBooks Online bill ID
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, nullable
  - `pagination` PaginationInfo, required
    - `pageSize` integer, required — Number of items per page
    - `hasNextPage` boolean, required — Whether there are more pages
    - `hasPreviousPage` boolean — Whether there are previous pages
    - `endCursor` string, nullable — Cursor for the next page (null if no next page)

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `422` — Validation error - invalid field values

---

[API](https://skmtc.dev/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.dev/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/revisions/7af4e91459ca/schema)