# Filter invoices

Search for AR invoices using filter criteria.

## Common Filters

- By customer: { "filter": { "customerId": { "equalTo": "uuid" } } }
- Unpaid: { "filter": { "status": { "in": ["AWAITING_PAYMENT", "PARTIALLY_PAID"] } } }
- Overdue: { "filter": { "overdue": true } }
- By shipment: { "filter": { "shipmentId": { "equalTo": "uuid" } } }

Endpoint: POST /invoices/filter
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `filter` (object)

  - `filter.id` (object)
    Filter options for UUID fields (all operations)

  - `filter.id.equalTo` (string)
    Exact match

  - `filter.id.notEqualTo` (string)
    Not equal to

  - `filter.id.in` (array)
    Matches any UUID in the array

  - `filter.id.notIn` (array)
    Does not match any UUID in the array

  - `filter.id.isNull` (boolean)
    Field is null (true) or not null (false)

  - `filter.orderId` (object)
    Filter options for UUID fields (all operations)

  - `filter.shipmentId` (object)
    Filter options for UUID fields (all operations)

  - `filter.customerId` (object)
    Filter options for UUID fields (all operations)

  - `filter.status` (object)

  - `filter.status.equalTo` (string)
    Current status of the invoice.
- DRAFT: Invoice record exists but not finalized
- AWAITING_PAYMENT: Invoice finalized, awaiting payment
- PARTIALLY_PAID: Some payments received, balance remains
- PAID: Fully paid
- VOIDED: Invoice cancelled/voided
    Enum: "DRAFT", "AWAITING_PAYMENT", "PARTIALLY_PAID", "PAID", "VOIDED"

  - `filter.status.notEqualTo` (string)
    Current status of the invoice.
- DRAFT: Invoice record exists but not finalized
- AWAITING_PAYMENT: Invoice finalized, awaiting payment
- PARTIALLY_PAID: Some payments received, balance remains
- PAID: Fully paid
- VOIDED: Invoice cancelled/voided
    Enum: "DRAFT", "AWAITING_PAYMENT", "PARTIALLY_PAID", "PAID", "VOIDED"

  - `filter.status.in` (array)
    Enum: "DRAFT", "AWAITING_PAYMENT", "PARTIALLY_PAID", "PAID", "VOIDED"

  - `filter.status.notIn` (array)
    Enum: "DRAFT", "AWAITING_PAYMENT", "PARTIALLY_PAID", "PAID", "VOIDED"

  - `filter.invoiceDate` (object)
    Filter options for datetime fields

  - `filter.invoiceDate.lessThan` (string)
    Before this datetime

  - `filter.invoiceDate.lessThanOrEqualTo` (string)
    On or before this datetime

  - `filter.invoiceDate.greaterThan` (string)
    After this datetime

  - `filter.invoiceDate.greaterThanOrEqualTo` (string)
    On or after this datetime

  - `filter.dueDate` (object)
    Filter options for datetime fields

  - `filter.amount` (object)
    Filter options for float/number fields

  - `filter.amount.lessThan` (number)
    Less than

  - `filter.amount.lessThanOrEqualTo` (number)
    Less than or equal to

  - `filter.amount.greaterThan` (number)
    Greater than

  - `filter.amount.greaterThanOrEqualTo` (number)
    Greater than or equal to

  - `filter.amountOwed` (object)
    Filter options for float/number fields

  - `filter.overdue` (boolean)
    Filter to overdue invoices only

  - `filter.factored` (boolean)
    Filter to factored invoices only

  - `filter.createdAt` (object)
    Filter options for datetime fields

  - `filter.and` (array)

  - `filter.or` (array)

  - `filter.not` (object)

  - `pageSize` (integer)

  - `cursor` (string)

## Response 200 fields (application/json):

  - `data` (array, required)

  - `data.id` (string, required)
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `data.friendlyId` (string, required)
    Human-readable invoice ID
    Example: "INV-00001"

  - `data.key` (string,null)
    Client-defined key

  - `data.orderId` (string)
    Associated order ID

  - `data.orderKey` (string,null)
    Order friendly ID

  - `data.shipmentId` (string)
    Associated shipment ID

  - `data.shipmentKey` (string,null)
    Shipment friendly ID

  - `data.customer` (object)
    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.

  - `data.customer.id` (string, required)
    Customer UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `data.customer.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CUSTOMER-ACME"

  - `data.customer.name` (string, required)
    Customer company name
    Example: "Acme Manufacturing Corp"

  - `data.customer.friendlyId` (string, required)
    Human-readable customer identifier
    Example: "A123456"

  - `data.customer.status` (string, required)
    Customer status
    Enum: "PROSPECT", "ACTIVE", "INACTIVE", "CHURNED"

  - `data.customer.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `data.customer.website` (string,null)
    Customer website URL
    Example: "https://acme-manufacturing.com"

  - `data.customer.createdAt` (string, required)
    When the customer was created
    Example: "2025-01-15T10:00:00Z"

  - `data.customer.updatedAt` (string, required)
    When the customer was last updated
    Example: "2025-01-15T14:30:00Z"

  - `data.customer.deletedAt` (string,null)
    When the customer was soft deleted (null if active)

  - `data.status` (string, required)
    Current status of the invoice.
- DRAFT: Invoice record exists but not finalized
- AWAITING_PAYMENT: Invoice finalized, awaiting payment
- PARTIALLY_PAID: Some payments received, balance remains
- PAID: Fully paid
- VOIDED: Invoice cancelled/voided
    Enum: "DRAFT", "AWAITING_PAYMENT", "PARTIALLY_PAID", "PAID", "VOIDED"

  - `data.invoiceDate` (string, required)
    Date invoice was issued

  - `data.dueDate` (string,null)
    Payment due date

  - `data.amount` (number, required)
    Total invoice amount

  - `data.currency` (string,null)
    Currency code (USD, CAD)
    Example: "USD"

  - `data.reference` (string,null)
    External reference number

  - `data.amountPaid` (number)
    Total payments received

  - `data.amountOwed` (number)
    Outstanding balance

  - `data.creditsApplied` (number,null)
    Total credits applied

  - `data.paymentTerm` (object)
    Enhanced reference to a payment term resource (returned in responses).
Includes full payment term details in addition to id/key.

  - `data.paymentTerm.id` (string, required)
    Payment term UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `data.paymentTerm.name` (string, required)
    Payment term name
    Example: "Net 30"

  - `data.paymentTerm.description` (string,null)
    Payment term description or notes
    Example: "Payment due 30 days from invoice date"

  - `data.paymentTerm.days` (integer,null)
    Number of days until payment is due
    Example: 30

  - `data.paymentTerm.quickPayFee` (number,null)
    Quick pay fee percentage (e.g., 0.05 for 5%)
    Example: 0.05

  - `data.paymentTerm.apOnly` (boolean,null)
    Whether this payment term is for accounts payable only

  - `data.paymentTerm.doNotUse` (boolean,null)
    Flag to prevent using this payment term for new transactions

  - `data.paymentTerm.createdAt` (string, required)
    When the payment term was created
    Example: "2025-01-15T10:00:00Z"

  - `data.paymentTerm.updatedAt` (string, required)
    When the payment term was last updated
    Example: "2025-01-15T14:30:00Z"

  - `data.paymentTerm.deletedAt` (string,null)
    When the payment term was soft deleted (null if active)

  - `data.payments` (array)
    Payments applied to this invoice

  - `data.payments.paymentGroupId` (string)

  - `data.payments.amount` (number)
    Amount applied to this invoice

  - `data.payments.paymentDate` (string)

  - `data.payments.reference` (string,null)
    Check number, transaction ID, etc.

  - `data.payments.paymentMethodType` (string,null)
    Payment method (check, ach_wire, etc.)

  - `data.credits` (array)
    Credits applied to this invoice

  - `data.credits.creditMemoId` (string)

  - `data.credits.creditMemoReference` (string,null)

  - `data.credits.amount` (number)
    Credit amount applied

  - `data.credits.appliedAt` (string)

  - `data.factorName` (string)
    Factoring provider for invoice financing.
- DENIM: Denim factoring
- HAULPAY: HaulPay factoring
    Enum: "DENIM", "HAULPAY"

  - `data.factorJobId` (string,null)
    External factoring job ID

  - `data.factorStatus` (string,null)
    Current factoring status

  - `data.qboId` (string,null)
    QuickBooks Online invoice ID

  - `data.documentId` (string,null)
    Generated invoice PDF document ID

  - `data.documentUrl` (string,null)
    Download URL for invoice PDF

  - `data.createdAt` (string, required)

  - `data.updatedAt` (string,null)

  - `pagination` (object, required)

  - `pagination.pageSize` (integer, required)
    Number of items per page
    Example: 50

  - `pagination.hasNextPage` (boolean, required)
    Whether there are more pages
    Example: true

  - `pagination.hasPreviousPage` (boolean)
    Whether there are previous pages

  - `pagination.endCursor` (string,null)
    Cursor for the next page (null if no next page)
    Example: "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message