---
title: "Filter payments"
method: POST
path: "/payments/filter"
tags: ["Payments"]
---

# Filter payments

`POST /payments/filter`

Search for AR payments using filter criteria.

## Common Filters

- By customer: `{ "filter": { "customerId": { "equalTo": "uuid" } } }`
- By invoice: `{ "filter": { "invoiceId": { "equalTo": "uuid" } } }`
- By date range: `{ "filter": { "paymentDate": { "greaterThanOrEqualTo": "2025-01-01" } } }`
- By method: `{ "filter": { "paymentMethodType": { "equalTo": "check" } } }`

## Request body

- PaymentFilterRequest
  - `filter` PaymentFilter
    - `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)
    - `customerId` 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)
    - `invoiceId` 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)
    - `paymentDate` 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)
    - `paymentMethodType` PaymentsPaymentMethodTypeFilter
      - `equalTo` 'ACH_WIRE' | 'ZELLE' | 'VENMO' | 'CHECK' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'CREDIT_CARD' — Payment method type. - `ACH_WIRE`: ACH or wire transfer - `ZELLE`: Zelle payment - `VENMO`: Venmo payment - `CHECK`: Paper check - `EFT_DIRECT_DEPOSIT`: EFT direct deposit - `E_TRANSFER`: Electronic transfer - `CREDIT_CARD`: Credit card payment
      - `notEqualTo` 'ACH_WIRE' | 'ZELLE' | 'VENMO' | 'CHECK' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'CREDIT_CARD' — Payment method type. - `ACH_WIRE`: ACH or wire transfer - `ZELLE`: Zelle payment - `VENMO`: Venmo payment - `CHECK`: Paper check - `EFT_DIRECT_DEPOSIT`: EFT direct deposit - `E_TRANSFER`: Electronic transfer - `CREDIT_CARD`: Credit card payment
      - `in` PaymentsPaymentMethodType[]
    - `totalAmount` 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)
    - `reference` StringFilter — Filter options for string fields
      - `equalTo` string — Exact match
      - `notEqualTo` string — Not equal to
      - `in` string[] — Matches any value in the array
      - `notIn` string[] — Does not match any value in the array
      - `includes` string — Contains substring (case-insensitive)
      - `notIncludes` string — Does not contain substring (case-insensitive)
      - `startsWith` string — Starts with prefix (case-insensitive)
      - `notStartsWith` string — Does not start with prefix (case-insensitive)
      - `endsWith` string — Ends with suffix (case-insensitive)
      - `notEndsWith` string — Does not end with suffix (case-insensitive)
      - `isNull` boolean — Field is null (true) or not null (false)
    - `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` PaymentFilter[]
    - `or` PaymentFilter[]
    - `not` PaymentFilter — recursive
  - `pageSize` integer
  - `cursor` string

## Response `200`

Payments matching filter criteria

- object
  - `data` Payment[], required
    - `id` string, uuid, required
    - `key` string, nullable — Human-readable payment key
    - `customer` CustomerReference — Enhanced reference to a customer resource (returned in responses). Includes full customer details in addition to id/key. Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion. Maximum nesting depth: 1 level.
      - `id` string, uuid, required — Customer UUID
      - `key` string, nullable — Client-defined reference ID if set
      - `name` string, required — Customer company name
      - `friendlyId` string, required — Human-readable customer identifier
      - `status` 'NEW' | 'CONTACTED' | 'QUALIFIED' | 'QUOTED' | 'NURTURING' | 'PENDING' | 'ACTIVE' | 'INACTIVE' | 'BLOCKED' | 'CLOSED', required — Customer status
      - `phoneNumber` string, nullable — Primary phone number
      - `website` string, nullable — Customer website URL
      - `createdAt` string, date-time, required — When the customer was created
      - `updatedAt` string, date-time, required — When the customer was last updated
      - `deletedAt` string, date-time, nullable — When the customer was soft deleted (null if active)
    - `paymentDate` string, date, required — Date payment was received
    - `paymentMethodType` 'ACH_WIRE' | 'ZELLE' | 'VENMO' | 'CHECK' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'CREDIT_CARD' — Payment method type. - `ACH_WIRE`: ACH or wire transfer - `ZELLE`: Zelle payment - `VENMO`: Venmo payment - `CHECK`: Paper check - `EFT_DIRECT_DEPOSIT`: EFT direct deposit - `E_TRANSFER`: Electronic transfer - `CREDIT_CARD`: Credit card payment
    - `reference` string, nullable — Check number, transaction ID, etc.
    - `notes` string, nullable — Payment notes
    - `currency` string, nullable — Currency code
    - `totalAmount` number, required — Total payment amount
    - `applications` PaymentApplication[] — Invoices this payment is applied to
      - `id` string, uuid, required
      - `invoiceId` string, uuid, required
      - `invoiceFriendlyId` string, nullable
      - `invoiceAmount` number, nullable — Total invoice amount
      - `invoiceOpenBalance` number, nullable — Invoice balance before this payment
      - `amount` number, required — Amount applied to this invoice
    - `creditApplications` PaymentCreditApplication[] — Credits applied in this payment
      - `id` string, uuid
      - `creditMemoId` string, uuid
      - `creditMemoReference` string, nullable
      - `amount` number — Credit amount applied in this payment
    - `overpaymentAmount` number, nullable — Amount in excess of invoice totals
    - `overpaymentCreditMemoId` string, uuid, nullable — Credit memo created from overpayment
    - `shipmentIds` string[] — Related shipment IDs
    - `shipmentKeys` string[] — Related shipment friendly IDs
    - `qboId` string, nullable — QuickBooks Online payment 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)