# Payment

## Overview

Payments record money flowing in from customers or out to suppliers. They update accounting records by reducing receivables when customers pay or reducing payables when you pay suppliers. Payments are applied to specific invoices to track which bills have been paid and which amounts remain outstanding.

Customer payments represent money received from customers. When a customer sends payment, you record the amount, payment method (check, credit card, wire transfer, etc.), and reference information like check numbers. The payment is then applied to one or more customer invoices. A single payment might cover multiple invoices, or multiple payments might be needed to fully pay one large invoice. The system tracks these applications so you always know exactly what's been paid.

Supplier payments represent money paid to suppliers for bills. The workflow is similar to customer payments but in reverse - you record the payment details and apply the amount to one or more supplier bills. This reduces your accounts payable balance and provides documentation for cash outflows.

The payment application process is flexible. You can apply a full payment to a single invoice, split one payment across multiple invoices, or make partial payments that don't fully satisfy an invoice. As payments are applied, invoice balances are reduced automatically. This application tracking is essential for accurate accounts receivable and accounts payable management.

Payment records capture important details for reconciliation. The payment date, amount, and reference information (like check numbers or transaction IDs) help match payments to bank deposits or check clearing. Payment method information supports cash management and accounting categorization, as credit card payments might involve processing fees while check payments require different handling.

From a financial perspective, payments create general ledger entries that move money from accounts receivable or accounts payable to cash accounts. Customer payments debit cash and credit accounts receivable. Supplier payments debit accounts payable and credit cash. These entries, combined with the invoice entries, form a complete financial picture of sales, purchases, and cash flows.

### GraphQL API

The `payment` collection provides access to payment data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

**Query Name:** `paymentViewConnection`

**Available Features:**

- Cursor-based pagination (first/last/after/before)
- 15 filter options
- 24 sortable fields
- 2 relations to other collections

## Query Examples

### Basic Query

The `payment` collection is accessed via the `paymentViewConnection` query, which returns a Relay-style connection with pagination support.

```graphql
query {
  paymentViewConnection(first: 10) {
    edges {
      node {
        amount
        creditAccount
        date
        debitAccount
        method
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

### Pagination

Use cursor-based pagination to retrieve large datasets:

```graphql
# First page
query {
  paymentViewConnection(first: 50) {
    edges {
      node { paymentId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  paymentViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { paymentId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

### Filtering

Apply filters to narrow results:

```graphql
query {
  paymentViewConnection(
    first: 10
    connectionRelationErrorDates: { begin: "2024-01-01", end: "2024-12-31" }
  ) {
    edges {
      node { paymentId }
    }
  }
}
```

### Sorting

Sort results by one or more fields:

```graphql
query {
  paymentViewConnection(
    first: 10
    sort: [{ field: "amount", mode: "desc" }]
  ) {
    edges {
      node {
        paymentId
        amount
      }
    }
  }
}
```

### Relations

Query related data:

```graphql
query {
  paymentViewConnection(first: 10) {
    edges {
      node {
        paymentId
        customer {
          name
          partyUrl
        }
      }
    }
  }
}
```

## Summary and Aggregation

This collection supports data aggregation and dimensional analysis through the `summary` field. You can calculate metrics (like totals, averages, counts) and group them by dimensions.

### Query Structure

```graphql
paymentViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    groupBy {
      # Group by dimensions (see table below)
    }
    metrics {
      # Calculated metrics (see table below)
    }
  }
}
```

### Available Metrics

This collection provides 1 metric that can be aggregated:

| Metric | Parameters | Description |
| --- | --- | --- |
| `count` | None | Count of items in the result set |

### GroupBy Dimensions

Group metrics by these dimensions:

| Dimension | Description |
| --- | --- |
| `customer` | customer for payment |
| `supplier` | supplier for payment |

### Examples

#### Example 1: Basic Aggregation

```graphql
query {
  paymentViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      groupBy {
        # Add dimensions here
      }
      metrics {
        totalCount: count
      }
    }
  }
}
```

## Fields

This collection has 23 fields:

- 21 simple fields
- 2 enum fields (with predefined values)
- 0 parameterized fields (accept query options)

### Simple Fields

#### `amount`
The total monetary value of the payment. This amount can be distributed across multiple invoices through invoice assignments, and the sum of assigned amounts must not exceed the payment total.

**Label:** Amount

**Sortable:** Yes

#### `creditAccount`
The general ledger account to be credited for this payment transaction.

**Label:** Credit account

**Sortable:** Yes

#### `date`
The date when the payment was made or received.

**Label:** Date

**Sortable:** Yes

#### `debitAccount`
The general ledger account to be debited for this payment transaction.

**Label:** Debit account

**Sortable:** Yes

#### `hasAttachment`
Indicates whether the payment has an associated file attachment.

**Label:** Has attachment

**Type:** `##iconWithTooltip`

**Sortable:** No

#### `method`
The method used to make the payment.

**Label:** Method

**Sortable:** Yes

#### `paymentId`
The unique identifier for the payment record.

**Label:** Payment ID

**Sortable:** Yes

#### `paymentUrl`
The unique identifier for the payment record (URL).

**Label:** Payment Url

**Sortable:** Yes

#### `privateNotes`
Internal notes visible only to staff members.

**Label:** Internal notes

**Sortable:** Yes

#### `publicNotes`
Public notes that can be shared with customers.

**Label:** Public notes

**Sortable:** Yes

#### `recordCreated`
The date and time when the payment record was created.

**Label:** Record created

**Sortable:** Yes

#### `recordLastUpdated`
The date and time when the payment record was last modified.

**Label:** Record last updated

**Sortable:** Yes

#### `referenceNumber`
An optional reference number for the payment.

**Label:** Reference number

**Sortable:** Yes

#### `statusExtended`
A readable formatted version of the payment status.

**Label:** Status extended

**Sortable:** Yes

#### `syncStatus`
The synchronization status of the payment with external systems.

**Label:** Sync status

**Sortable:** Yes

#### `syncStatusConnection`
Displays the connection IDs for all sync operations related to the payment.

**Label:** Sync status connection ID

**Sortable:** Yes

#### `syncStatusFrom`
The synchronization status for payments imported from external systems.

**Label:** Synced from

**Sortable:** Yes

#### `syncStatusFromConnection`
Displays the connection IDs for inbound sync operations.

**Label:** Synced from connection ID

**Sortable:** Yes

#### `syncStatusTo`
The synchronization status for payments exported from Finale.

**Label:** Synced to

**Sortable:** Yes

#### `syncStatusToConnection`
Displays the connection IDs for outbound sync operations.

**Label:** Synced to connection ID

**Sortable:** Yes

#### `title`
A computed display title for the payment.

**Label:** Title

**Sortable:** Yes

### Enum Fields

#### `status`
The current status of the payment.

**Label:** Status

**Sortable:** Yes

**Possible Values:**
- `PAYMENT_DRAFT`
- `PAYMENT_COMPLETED`
- `PAYMENT_CANCELLED`

#### `type`
**Label:** Type

**Sortable:** Yes

**Possible Values:**
- `PURCHASE_PAYMENT`
- `SALES_PAYMENT`

## Relations

### customer
- **Related Collection:** [party](https://developer.finaleinventory.com/reference/graphql-party)
- **Label:** Customer

### connectionRelation
- **Related Collection:** [connectionRelation](https://developer.finaleinventory.com/reference/graphql-connection-relation)
- **Label:** Integration

## Filters
### connectionRelationErrorDates
- **Label:** Latest error date
- **Type:** dateRangeInput
- **Enabled:** Yes

**Filter Type:** Date range

**Input Structure:**
```typescript
{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}
```

### connectionRelationSyncStatuses
- **Label:** Sync status
- **Type:** List|String
- **Enabled:** Yes
- **Options:**
  - Excluded from syncing
  - Has error
  - Not synced
  - Partially synced
  - Synced

### creditAccount
- **Label:** Credit account
- **Type:** List|String
- **Enabled:** Yes

### customer
- **Label:** Customer
- **Type:** List|PartyUrlCustomerString
- **Enabled:** Yes

### date
- **Label:** Date
- **Type:** dateRangeInput
- **Enabled:** Yes

### debitAccount
- **Label:** Debit account
- **Type:** List|String
- **Enabled:** Yes

### method
- **Label:** Method
- **Type:** List|String
- **Enabled:** Yes

### paymentUrl
- **Label:** Payment
- **Type:** List|PaymentUrlString
- **Enabled:** Yes

### recordCreated
- **Label:** Created
- **Type:** dateRangeInput
- **Enabled:** Yes

### recordLastUpdated
- **Label:** Last updated
- **Type:** dateRangeInput
- **Enabled:** Yes

### search
- **Label:** Not specified
- **Type:** SearchString
- **Enabled:** Yes

### searchCustom
- **Label:** Not specified
- **Type:** searchCustomFilter
- **Enabled:** Yes

### status
- **Label:** Status
- **Type:** List|String
- **Enabled:** Yes

### supplier
- **Label:** Supplier
- **Type:** List|PartyUrlSupplierString
- **Enabled:** Yes

### type
- **Label:** Type
- **Type:** List|String
- **Enabled:** Yes