# Invoice

## Overview
Invoices represent the financial billing for goods or services, updating accounting records without affecting physical inventory. They record what customers owe you (sales invoices), what you owe suppliers (bills), or adjustments to those amounts (credit memos). Invoices are the bridge between physical operations and financial records.

Sales invoices bill customers for sales. They're typically created from sale shipments after goods have shipped, ensuring you only invoice for what actually left the warehouse. An invoice can also be created from a sales order for deposit billing or pre-billing scenarios. Invoices contain different types of line items: product items that specify a product, quantity, and unit price, as well as separate line items for adjustments (discounts or fees) and taxes that apply to the overall invoice total. The system calculates subtotals from product items, applies invoice-level adjustments and taxes, and arrives at a total amount due.

Bills record supplier invoices for purchases. When you receive goods and later get the supplier's invoice, you create a bill in Finale to record the financial obligation. Bills can be created from purchase shipments or purchase orders, matching the supplier's invoice to what you actually received. This ensures you're billed correctly and have documentation for the accounting team.

Credit memos and supplier credits are negative invoices that represent refunds or credits. A customer return might generate a credit memo reducing what the customer owes. A damaged shipment from a supplier might result in a supplier credit reducing what you owe them. These adjustments are tracked separately from the original invoices for clear audit trails.

The invoice workflow centers on posting. Draft invoices can be edited freely as you build them. When posted, the invoice becomes locked and creates general ledger entries - debiting accounts receivable and crediting revenue for sales invoices, or debiting inventory/expenses and crediting accounts payable for bills. Posted invoices can only be voided (creating reversing entries) rather than deleted, maintaining accounting integrity.

Invoices track payment application. As customer payments are received or supplier payments are made, they're applied to invoices to reduce the outstanding balance. The system tracks total amounts due, amounts paid, and remaining balances. You can see at a glance that an invoice is "partially paid" or "paid in full," essential for cash management and collections.

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

**Query Name:**`invoiceViewConnection`

**Available Features:**

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

## Query Examples
### Basic Query
The `invoice` collection is accessed via the `invoiceViewConnection` query, which returns a Relay-style connection with pagination support.

```graphql
query {
  invoiceViewConnection(first: 10) {
    edges {
      node {
        dueDate
        invoiceDate
        invoiceId
        invoiceTitle
        invoiceUrl
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

### Pagination
Use cursor-based pagination to retrieve large datasets:

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

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

### Filtering
Apply filters to narrow results:

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

### Sorting
Sort results by one or more fields:

```graphql
query {
  invoiceViewConnection(
    first: 10
    sort: [{ field: "dueDate", mode: "desc" }]
  ) {
    edges {
      node {
        invoiceId
        dueDate
      }
    }
  }
}
```

### Relations
Query related data:

```graphql
query {
  invoiceViewConnection(first: 10) {
    edges {
      node {
        invoiceId
        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 (like category, date, status).

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

### Available Metrics
This collection provides 4 metrics that can be aggregated:

| Metric | Parameters | Description |
| --- | --- | --- |
| `totalPaid` | `transform`, `operator` | totalPaid for invoice |
| `outstandingBalance` | `transform`, `operator` | outstandingBalance for invoice |
| `total` | `transform`, `operator` | Total amount |
| `count` | None | Count of items in the result set |

### GroupBy Dimensions
Group metrics by these dimensions:

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

### Simple Fields
This collection has 47 fields:

- 44 simple fields
- 3 enum fields (with predefined values)

#### `dueDate`
The date by which payment for the invoice is expected, calculated by adding the number of days specified in the payment terms to the invoice date. Payment terms like Net 15, Net 30, or Net 45 determine how many days after the invoice date payment becomes due.

**Label:** Due date

**Sortable:** Yes

#### `invoiceDate`
The date when the invoice was issued or created. This is a core timestamp field that identifies when the invoice transaction occurred in the business.

**Label:** Invoice date
**Sortable:** Yes

#### `invoiceId`
User-visible identifier for the invoice, displayed throughout the UI and used for referencing invoices in reports, titles, and integrations.

**Label:** Invoice ID
**Sortable:** Yes

#### `invoiceTitle`
A human-readable display name for an invoice that combines the invoice type label, invoice ID, and the associated party name.

**Label:** Invoice title
**Sortable:** Yes

#### `invoiceUrl`
The unique identifier and primary key for invoice records in the system.

**Label:** Invoice Url
**Sortable:** Yes

#### `outstandingBalance`
The remaining unpaid amount on an invoice, calculated as the invoice total minus the total amount paid through payments.

**Label:** Outstanding balance
**Sortable:** Yes

#### `total`
The complete invoice amount including the subtotal, all taxes, and all discounts and fees.

**Label:** Total
**Sortable:** Yes

#### `status`
The current state of the invoice in its lifecycle.

**Label:** Status
**Sortable:** Yes

**Possible Values:**
- `INVOICE_IN_PROCESS` - Draft
- `INVOICE_APPROVED` - Posted
- `INVOICE_CANCELLED` - Voided

#### `type`
The category of invoice, which determines the nature of the transaction and the parties involved.

**Label:** Type
**Sortable:** Yes

**Possible Values:**
- `SALES_INVOICE` - Invoice
- `PURCHASE_INVOICE` - Bill
- `SUPPLIER_CREDIT` - Supplier credit

## 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

### order
- **Related Collection:** [order](https://developer.finaleinventory.com/reference/graphql-order)
- **Label:** Order

### recordCreatedUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Record created user

### recordLastUpdatedUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Record last updated user

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

**Filter Type:** Date range

### dueDate
- **Label:** Due date
- **Type:** dateRangeWithFutureInput
- **Enabled:** Yes

**Filter Type:** Date range

### invoiceDate
- **Label:** Invoice date
- **Type:** dateRangeWithFutureInput
- **Enabled:** Yes

**Filter Type:** Date range

### paymentsStatusSummary
- **Label:** Payments status summary
- **Type:** List|String
- **Enabled:** Yes
- **Options:**
  - Canceled
  - Exceptions
  - N/A
  - No payment due
  - Overpaid
  - Paid
  - Partially paid
  - Unpaid

### recordCreated
- **Label:** Record created
- **Type:** dateRangeInput
- **Enabled:** Yes

**Filter Type:** Date range

### recordLastUpdated
- **Label:** Record last updated
- **Type:** dateRangeInput
- **Enabled:** Yes

**Filter Type:** Date range

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

**Filter Type:** Search text

### status
- **Label:** Status
- **Type:** List|String
- **Enabled:** Yes
- **Options:**
  - Draft
  - Posted
  - Voided

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

**Filter Type:** Reference to `party` collection

### type
- **Label:** Type
- **Type:** List|String
- **Enabled:** Yes
- **Options:**
  - Bill
  - Invoice
  - Supplier credit