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.

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

Pagination

Use cursor-based pagination to retrieve large datasets:

# 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 (see Filters section for all available options):

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

Sorting

Sort results by one or more fields:

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

Relations

Query related data (see Relations section for all available relations):

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).

For a comprehensive guide to using aggregations, see the Aggregation Concept Guide.

Query Structure

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

Common Parameters:

operator - Aggregation function: sum, mean, min, max
transform - Mathematical transformation: abs
dateRange - Filter to specific date range
facilityUrlList - Filter to specific facilities

GroupBy Dimensions

Group metrics by these dimensions:

Dimension	Description
`customer`	customer for invoice
`supplier`	supplier for invoice

All dimensions accept a formatter parameter: "html", "none", "abbreviated", "blank-zero".

Examples

Example 1: Billing Analysis by Period

Analyze invoice metrics by invoice date:

query {
  invoiceViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      groupBy {
        invoiceDate
      }
      metrics {
        invoiceCount: count
        totalBilled: total(operator: sum)
        avgInvoiceAmount: total(operator: mean)
      }
    }
  }
}

Fields

This collection has 47 fields:

44 simple fields
3 enum fields (with predefined values)
0 parameterized fields (accept query options)

Note on Field Formatting: All scalar fields support the formatter argument to control output format. Available options: "html", "none", "abbreviated", "blank-zero". Some fields have a default formatter (shown below). See the Formatting guide for details.

Note on Sorting: Field sortability may vary depending on the UI context and query parameters used. Some parameter options explicitly disable sorting (marked with (!!) not sortable).

Simple Fields

These fields return values directly without additional options.

`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. For example, an invoice dated July 22, 2010 with Net 15 terms would have a due date of August 6, 2010. This field helps businesses track payment deadlines and identify overdue invoices, and can be sorted or filtered when viewing invoice lists to manage accounts receivable and payable.

Label: Due date
Sortable: Yes

`hasAttachment`

Indicates whether the invoice has at least one file attachment. This field is computed by filtering the invoice's contentList for items with a content type of 'ATTACHMENT', and returns true if any attachments are found. In the user interface, this is displayed as an attachment icon when attachments are present. This field is primarily used as a visual indicator in invoice lists and reports, and is not sortable since it's a computed value. The field distinguishes between attachments and other content types that may be associated with an invoice.

Label: Has attachment
Type: ##iconWithTooltip
Sortable: No

`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.

The invoice date is stored as an ISO 8601 timestamp (e.g., '2013-05-05T20:00:00') and is displayed to users in a localized date format (e.g., '5/5/2013'). This field is set when an invoice is created and represents the official date of the invoice document.

The invoice date serves multiple important purposes: it is used as the starting point for calculating the due date (by adding payment terms days), it can be used for sorting and filtering invoices in reports and lists, and it appears on printed invoice documents and in master variables for templates. The field is applicable to all invoice types including purchase invoices (PURCHASE_INVOICE), sales invoices (SALES_INVOICE), and supplier credits (SUPPLIER_CREDIT).

When creating new invoices through bulk import or data entry, the invoice date can be specified in various formats and will be normalized to the system's timestamp format. It is a required field for invoice creation and cannot be left empty.

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. This differs from the internal system ID (the numeric part of the URL path) and can contain alphanumeric characters, hyphens, and suffixes. For invoices linked to orders, the ID is often auto-generated following a pattern based on the order ID, with sequential suffixes (e.g., "891-1", "891-2") when multiple invoices are created for the same order. When importing from external systems like QuickBooks Online, the system attempts to use the document number from the external system as the invoice ID, falling back to auto-generated patterns with letter suffixes (e.g., "892-1A", "892-1B") if conflicts occur.

Label: Invoice ID
Sortable: Yes
Default Formatter: html

Example Query:

{
  invoice(invoiceUrl: "example-url") {
    invoiceId    # Uses default formatter: html
    invoiceIdRaw: invoiceId(formatter: "none")  # Get raw value
  }
}

`invoiceTitle`

A human-readable display name for an invoice that combines the invoice type label, invoice ID, and the associated party name. The format is "{Invoice Type} {Invoice ID}: {Party Name}". For sales invoices and sales receipts, the party name is the customer; for bills and supplier credits, it's the supplier. If no party is associated, the title shows "No customer" or "No supplier" as appropriate. For example, "Invoice 894-1: Big Parks", "Bill 891-1: Alpha Fireworks", or "Sales receipt 894-2: No customer". When displayed in HTML format with outstanding balance information, it may include the balance in parentheses.

Label: Invoice title
Sortable: Yes
Default Formatter: html

Example Query:

{
  invoice(invoiceUrl: "example-url") {
    invoiceTitle    # Uses default formatter: html
    invoiceTitleRaw: invoiceTitle(formatter: "none")  # Get raw value
  }
}

`invoiceUrl`

The unique identifier and primary key for invoice records in the system. This URL path is automatically generated by the server and uniquely identifies each invoice record in the database.

This field is used throughout the application for:

Lookups: Finding invoice records and their related attributes
Relationships: Linking invoices to orders (via primaryOrderUrl), payments (via primaryInvoiceUrl), and other entities
Item lists: Associating invoice items to their parent invoice through the invoiceItemList
Filtering and querying: Used in GraphQL queries and dataset filters to specify which invoice records to retrieve
Data imports: Referenced when importing or modifying invoice data to identify existing records

The invoiceUrl is distinct from the user-visible invoice ID (stored in invoiceIdUser). While the invoice ID is displayed to users and can be customized, the invoiceUrl is an immutable system identifier that remains constant throughout the invoice's lifecycle.

IMPORTANT: Treat URL values as opaque strings supplied by the server. Do not attempt to parse, interpret, or construct URL values manually:

ID values embedded in URLs may differ from entity ID values
The URL structure is an internal implementation detail subject to change
Manually constructing URLs can lead to bugs and system errors
Always use URL values exactly as provided by the API

Label: Invoice Url
Sortable: Yes

`miscDiscountsAndFees`

The sum of all discount and fee adjustment items on the invoice that are not associated with a specific discount and fee preset. This includes manually added adjustments and adjustments imported from integrations that don't specify a preset. Items with an assigned preset (identified by a productPromoUrl) are tracked separately and excluded from this total. The field combines both taxable and non-taxable miscellaneous discounts and fees.

Label: Misc discounts and fees
Sortable: No

`miscExternalTax`

The sum of invoice items with tax type "External tax" (EXT_TAX) that are not associated with a specific promotion. This represents externally calculated taxes entered manually or imported from external systems, excluding system-managed taxes calculated by tax authorities. The "misc" designation indicates these are ad-hoc external tax adjustments not tied to named discount/fee promotions (items without a productPromoUrl).

Label: Misc external tax
Sortable: No

`miscNonTaxableDiscountsAndFees`

The sum of all nontaxable discounts and fees on the invoice that are not associated with a product promotion. This field captures miscellaneous invoice adjustments such as manual discounts, fees, or other adjustments that have been marked as nontaxable (taxEnumId = 'NON_TAXABLE') and have an invoice item type of 'INV_PROMOTION_ADJ', but specifically excludes adjustments linked to a product promotion (productPromoUrl). Common examples include miscellaneous adjustments, handling fees, or other ad-hoc charges that should not be subject to tax and are not tied to a specific promotional campaign.

Label: Misc nontaxable discounts and fees
Sortable: No

`miscTaxableDiscountsAndFees`

The sum of all miscellaneous taxable discounts and fees on the invoice. These are invoice adjustments that are not associated with a specific product promotion and have a tax classification other than nontaxable or external tax. Taxable discounts and fees are included when calculating the taxable subtotal and affect the amount of sales tax applied to the invoice. This field excludes promotion-related adjustments that are tied to specific products.

Label: Misc taxable discounts and fees
Sortable: No

`netSales`

The total invoice amount after applying discounts and fees but before taxes. Calculated as the sum of the subtotal (product line items only) plus all discount and fee adjustments. This represents the net revenue from the sale, excluding any tax amounts. In financial reporting, netSales is used to analyze sales performance and can differ from the total when discounts reduce or fees increase the base subtotal. For example, an invoice with a subtotal of $12.00 and a $-3.00 discount would have netSales of $9.00.

Label: Net amount
Sortable: No

`outstandingBalance`

The remaining unpaid amount on an invoice, calculated as the invoice total minus the total amount paid through payments. For cancelled invoices, the outstanding balance is always zero regardless of the actual amounts. This field is commonly used for tracking which invoices still require payment, sorting invoices by how much is owed, and displaying balance information in invoice lists and summaries.

Label: Outstanding balance
Sortable: Yes

`paymentDates`

A computed list of payment dates for all completed payments associated with the invoice. This field extracts the payment date from each related payment that has a status of PAYMENT_COMPLETED, filters out any incomplete payments, sorts the dates chronologically, and displays them as a comma-separated list. The field is derived from the invoice's payment URL list and provides a quick view of when payments were actually completed for the invoice.

Label: Payment dates
Sortable: Yes

`payToAdditionalLines`

Additional address lines for the payment location address on the invoice. This field corresponds to the address2 field of the supplier's payment location postal address and can contain supplementary address information such as apartment numbers, suite numbers, building names, or other address details that don't fit in the primary street address field. The field supports multi-line text entries (separated by newlines) to accommodate complex address formats.

Label: Pay to additional lines
Sortable: Yes

`payToAddress`

The complete formatted mailing address where payment should be sent for an invoice. This field combines all address components (recipient name, street address, city, state/region, postal code, country, and additional address lines) into a single formatted string, with components separated by commas when displayed inline or line breaks when formatted for display.

The address is determined by retrieving the postal address associated with the supplier party for the invoice, specifically looking for a contact mechanism with the "PAYMENT_LOCATION" purpose. For purchase invoices, this retrieves the supplier's designated payment address. If the invoice has an associated supplier role, that party's payment location address is used; otherwise, it falls back to the supplier from the invoice's primary order if available.

This is a computed read-only field that formats the address according to standard postal conventions: recipient name on the first line, street address, city/state/postal code/country on one line, and any additional address lines. The field is commonly used on printed invoices, payment remittance forms, and accounts payable reports to ensure payments are sent to the correct location.

Label: Pay to address
Sortable: Yes

`payToCity`

The city portion of the payment remittance address where payments for this invoice should be sent. For purchase invoices, this is extracted from the supplier's payment location contact information (identified by PAYMENT_LOCATION contact mechanism purpose). The city field is part of the complete "pay to" address that appears on printed bills and payment documents, helping vendors know where to direct payment correspondence.

Label: Pay to city
Sortable: Yes

`payToCountry`

Country component of the payment location address for the invoice supplier. This field stores the country geographic identifier from the supplier's designated payment location address. The value is retrieved from the supplier's contact information, first looking for an address specifically marked with the PAYMENT_LOCATION purpose, then falling back to a GENERAL_LOCATION address, or finally using the first available postal address if no specific payment address is defined. The country value corresponds to geographic enumeration codes and can be displayed in different formats including full country names or ISO 3166 alpha-2 codes.

Label: Pay to country
Sortable: Yes

`payToDirections`

Free-form directions text associated with the payment location address for the invoice. This field stores navigation or location instructions (such as "I80 to Lexington") that help locate the physical payment address. The directions are extracted from the supplier's payment location address record and are separate from the formatted address components like street, city, and postal code.

Label: Pay to directions
Sortable: Yes

`payToName`

The name associated with the payment location address for a purchase invoice (bill or supplier credit). This field is extracted from the toName property of the supplier's payment location contact mechanism.

For purchase invoices, the system retrieves the payment address by looking up the supplier's contact information and selecting the address marked with the PAYMENT_LOCATION purpose type. If no payment location is specified, the system falls back to a general location address, or if that's not available, uses the first address on file for the supplier.

In test cases, this field is shown to be empty when the address has street and city information but no explicit toName value stored. This distinguishes it from other address components like street address, city, and postal code, which come from different properties of the same payment location contact mechanism.

Label: Pay to name
Sortable: Yes

`payToPostalCode`

The postal code (ZIP code) portion of the payment address where payments for this invoice should be sent. For bills (purchase invoices), this is derived from the supplier's payment location contact information. This field is part of a complete payment address that includes street address, city, state/region, and country, providing the full mailing location for sending payments to the supplier.

Label: Pay to postal code
Sortable: Yes

`payToStateRegion`

The state or region portion of the payment address for the invoice. For purchase invoices, this represents the state/region where payments should be sent to the supplier, derived from the supplier's payment location contact information. This field is part of the complete payment address that includes street address, city, postal code, and country.

Label: Pay to state / region
Sortable: Yes

`payToStreetAddress`

The street address line where payment should be sent for this invoice. This field is part of the payment location address associated with the supplier on the invoice. For purchase invoices, this represents the supplier's designated payment address (marked with the PAYMENT_LOCATION contact mechanism purpose), which may differ from their general or shipping addresses. The field corresponds to the first address line (address1) of the supplier's payment location postal address.

Label: Pay to street address
Sortable: Yes

`privateNotes`

Internal notes are free-form text notes intended for internal use only, not visible to customers or suppliers. This field supports multi-line text with newlines, which are escaped and formatted as HTML when displayed. The field is labeled "Internal notes" in the user interface to distinguish it from public notes.

These notes can be used for recording internal information such as special delivery instructions ("Please ask for Carla when delivering"), internal reminders, or other confidential information ("secret note") that should not appear on customer-facing documents.

When syncing transactions to accounting systems like QuickBooks, there is a configuration option to control whether private notes are included in the transaction memo. The default behavior excludes private notes for invoices (syncNotesExcludeInvoice), though they can be included for all transactions if desired (syncNotesGenerated).

Label: Internal notes
Sortable: Yes
Default Formatter: html

Example Query:

{
  invoice(invoiceUrl: "example-url") {
    privateNotes    # Uses default formatter: html
    privateNotesRaw: privateNotes(formatter: "none")  # Get raw value
  }
}

`publicNotes`

A text field for notes that are visible to customers or suppliers on printed invoice documents. This field appears on invoice PDFs, bills, and supplier credit documents with labels like "Invoice Notes," "Bill notes," or "Supplier credit notes." Unlike the privateNotes field which is for internal use only, publicNotes contains information meant to be shared with external parties, such as special instructions, custom requests, or customer-facing messages. The field supports multiline text with HTML formatting and newline conversion for proper display on documents.

Label: Public notes
Sortable: Yes
Default Formatter: html

Example Query:

{
  invoice(invoiceUrl: "example-url") {
    publicNotes    # Uses default formatter: html
    publicNotesRaw: publicNotes(formatter: "none")  # Get raw value
  }
}

`recordCreated`

The recordCreated field represents the timestamp when the invoice record was created, extracted from the first entry in the invoice's statusIdHistoryList array. It uses the txStamp subkey from the first status history entry (via _.first) and is formatted as a timestamp. The field is implemented through the statusIdHistoryListTimestampMixin which looks up the transaction timestamp from the status history, returns Number.POSITIVE_INFINITY when no value is found, and supports sorting via a C++ sort function that accesses statusIdHistoryList['##begin', '', 'txStamp'].

Label: Record created
Sortable: Yes

`recordLastUpdated`

The date when the invoice record was last modified in the system. This field is automatically updated whenever any changes are made to the invoice, such as editing invoice details, adding or modifying line items, updating the status, or adjusting payment information. This allows users to track when an invoice was most recently changed, which is useful for auditing purposes and understanding the timeline of invoice modifications.

Label: Record last updated
Sortable: Yes

`referenceNumber`

A custom reference number or identifier that can be assigned to an invoice for tracking and organizational purposes. This field allows users to enter their own numbering scheme or reference code to identify the invoice, separate from the system-generated invoice ID. It can be used to match invoices with external systems, purchase orders, or internal accounting references.

Label: Reference number
Sortable: Yes

`statusExtended`

A human-readable formatted version of the invoice's current status. This field translates the internal status code into a user-friendly text representation that displays in the interface, making it easier for users to understand the invoice's state at a glance without needing to interpret status codes.

Label: Status extended
Sortable: Yes

`subtotal`

The sum of all product line item amounts on the invoice, calculated by adding up the extended price (quantity times unit price) for each product item. This represents the total value of goods or products before applying any adjustments like discounts, fees, or taxes. The subtotal excludes non-product items and miscellaneous charges, focusing solely on the core product value of the invoice.

Label: Subtotal
Sortable: No

`syncStatus`

The synchronization status of the invoice with connected external accounting or e-commerce systems. This field displays the current sync state for each connection, such as "Synced" when successfully synchronized, "Excluded from syncing" when intentionally not synced, or empty when no sync relationship exists. When an invoice is connected to multiple systems, the field shows the status for each connection separately, formatted as "System Name: Status" and separated by semicolons.

Label: Sync status
Sortable: Yes

`syncStatusConnection`

Further information is not available.

Label: Sync status connection ID
Sortable: Yes

`syncStatusFromConnection`

The integration or connection name from which the invoice was synced. This field identifies the specific external system (such as QuickBooks Online, ShipStation, or other connected platforms) that served as the source when the invoice data was synchronized into Finale. It works in conjunction with related sync status fields to provide a complete picture of the invoice's integration history, helping users understand which connected system originated or last updated the invoice data.

Label: Synced from connection ID
Sortable: Yes

`syncStatusToConnection`

Identifies the external accounting system connection that this invoice is being synchronized to (outbound sync). When an invoice is sent from Finale to an external system like QuickBooks Online, this field indicates which connection is receiving the invoice data. The field contains a formatted identifier that includes the connection type and connection ID. This is distinct from syncStatusFromConnection, which tracks inbound synchronization where invoice data originates from an external system.

Label: Synced to connection ID
Sortable: Yes

`taxableSubtotal`

The portion of the invoice that is subject to tax calculation. This includes the subtotal of all product line items plus any discounts or fees that are themselves taxable. Non-taxable discounts and fees are excluded from this amount. This field is used to determine the base amount on which taxes should be calculated.

Label: Taxable subtotal
Sortable: No

`terms`

The payment terms that apply to the invoice, such as "Net 30" or "Due on receipt". If the invoice does not have terms directly specified, the system falls back to the terms from the associated order. This field is not applicable for supplier credits.

Label: Terms
Sortable: Yes

`title`

A formatted display label combining the invoice type (either "Invoice" for sales invoices or "Bill" for purchase invoices), the user-facing invoice ID, and the invoice date. For example, a sales invoice might display as "Invoice 123 · 5/5/2013" while a purchase invoice would show "Bill 456 · 6/15/2014". This title is used throughout the interface to identify and reference specific invoices in a human-readable format.

Label: Title
Sortable: Yes

`total`

The complete invoice amount including the subtotal, all taxes, and all discounts and fees. This is the final amount owed on the invoice before any payments are applied. For bills (supplier invoices), this represents the bill total, and for supplier credits, this represents the credit total. The field is used for sorting invoices, displaying in reports and pivot tables, and calculating summary metrics across multiple invoices.

Label: Total
Sortable: Yes

`totalDiscountsAndFees`

The combined total of all discounts and fees applied to the invoice. This includes both taxable and non-taxable discounts and fees, such as miscellaneous adjustments, but excludes tax amounts. Discounts are typically shown as negative amounts while fees are positive amounts, and this field represents their net total.

Label: Total discounts and fees
Sortable: No

`totalExternalTax`

The total amount of external tax applied to the invoice. External tax represents tax amounts that are calculated or managed outside of the system and then recorded on the invoice, as opposed to taxes calculated internally by the system. This field sums all invoice line items that are classified as promotion adjustments with an external tax designation. External taxes appear on invoices alongside other line items such as products, discounts, fees, and shipping charges.

Label: Total external tax
Sortable: No

`totalNonTaxableDiscountsAndFees`

The total value of all discounts and fees applied to the invoice that are not subject to sales tax. This field represents the portion of the invoice's total discounts and fees that are classified as non-taxable, as opposed to taxable discounts and fees. The sum of totalNonTaxableDiscountsAndFees and totalTaxableDiscountsAndFees equals totalDiscountsAndFees on the invoice.

Label: Total nontaxable discounts and fees
Sortable: No

`totalPaid`

The total amount of all payments that have been applied to this invoice. This value is used to calculate the outstanding balance by subtracting it from the invoice total. For credit invoices, this represents the total amount that has been applied rather than paid.

Label: Total paid
Sortable: Yes

`totalTax`

The sum of all tax amounts from invoice items where the item type is classified as a tax. This field represents the total tax liability associated with the invoice, calculated by filtering and aggregating all tax-type line items on the invoice.

Label: Total tax
Sortable: No

`totalTaxableDiscountsAndFees`

The sum of all discounts and fees on the invoice that are subject to sales tax. This represents adjustments to the invoice amount where tax should be calculated on the adjusted amount. Unlike non-taxable discounts and fees which are tax-exempt, these amounts are included in the taxable base when computing the invoice's total tax. This field works in conjunction with totalNonTaxableDiscountsAndFees and totalTaxDiscountsAndFees to provide a complete breakdown of how discounts and fees affect the invoice's tax calculation.

Label: Total taxable discounts and fees
Sortable: No

`totalTaxDiscountsAndFees`

The total amount of discounts and fees on the invoice that are subject to tax. This field represents the taxable portion of all discounts and fees applied to the invoice, as opposed to non-taxable discounts and fees. This value is used in calculating the invoice's taxable subtotal and final tax amounts.

Label: Total tax, discounts and fees
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

`paymentsStatusSummary`

Provides a summary of the payment status for an invoice, bill, or supplier credit. The field indicates whether the document has been paid, partially paid, unpaid, or overpaid by comparing the total amount due against payments received.

For invoices and bills, the possible statuses include: Unpaid (no payments received), Partially paid (some payments received but outstanding balance remains), Paid (fully paid with no balance), Overpaid (payments exceed the total amount), No payment due (zero balance invoice), Canceled (invoice is voided), Exceptions (payment processing issues), and N/A (draft invoice not yet posted).

For supplier credits, the field tracks credit application status instead of payments, with values like: Unapplied (credit not yet applied), Partially applied (some credit used), Applied (fully applied), Overapplied (credit exceeds balance), No available credits (zero credit remaining), and the same Canceled, Exceptions, and N/A states.

This field is commonly used to filter invoice lists to show only unpaid or partially paid documents that require attention. The status is automatically calculated based on the outstanding balance and payment records, and updates whenever payments are applied or modified.

Label: Payments status summary
Sortable: Yes
Default Formatter: html

Possible Values:

##paymentsUnpaid - Unpaid
##paymentsPartial - Partially paid
##paymentsFull - Paid
##paymentsOverpaid - Overpaid
##paymentsNoDue - No payment due
##paymentsCanceled - Canceled
##paymentsExceptions - Exceptions
##paymentsDraft - N/A

Example Query:

{
  invoice(invoiceUrl: "example-url") {
    paymentsStatusSummary    # Uses default formatter: html
    paymentsStatusSummaryRaw: paymentsStatusSummary(formatter: "none")  # Get raw value
  }
}

`status`

The current state of the invoice in its lifecycle. Invoices can be in draft status (in process), posted status (approved or completed), or cancelled status. The status determines whether the invoice is editable - invoices are only editable when in draft status and when their associated purchase or sale order is also editable. Once an invoice is completed or approved, it becomes read-only and can only be modified if reverted back to draft status. Cancelled invoices represent voided or abandoned invoices that are no longer active.

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. The three main types are sales invoices for amounts owed to your business by customers, purchase invoices for amounts your business owes to suppliers, and supplier credits for amounts your suppliers owe back to you. This classification affects how the invoice appears in reports, which custom fields are available, and the business logic applied to the transaction.

Label: Type
Sortable: Yes

Possible Values:

SALES_INVOICE - Invoice
PURCHASE_INVOICE - Bill
SUPPLIER_CREDIT - Supplier credit

Relations

customer

Related Collection: party
Label: Customer

Example Query:

query {
  invoiceViewConnection(first: 10) {
    edges {
      node {
        customer {
          name
          partyUrl
        }
      }
    }
  }
}

connectionRelation

Related Collection: connectionRelation
Label: Integration

Example Query:

query {
  invoiceViewConnection(first: 10) {
    edges {
      node {
        connectionRelation {
          syncStatuses
          errorDetails
        }
      }
    }
  }
}

order

Related Collection: order
Label: Order

Example Query:

query {
  invoiceViewConnection(first: 10) {
    edges {
      node {
        order {
          orderId
          orderUrl
        }
      }
    }
  }
}

recordCreatedUser

Related Collection: userLogin
Label: Record created user

Example Query:

query {
  invoiceViewConnection(first: 10) {
    edges {
      node {
        recordCreatedUser {
          name
          userLoginUrl
        }
      }
    }
  }
}

recordLastUpdatedUser

Related Collection: userLogin
Label: Record last updated user

Example Query:

query {
  invoiceViewConnection(first: 10) {
    edges {
      node {
        recordLastUpdatedUser {
          name
          userLoginUrl
        }
      }
    }
  }
}

Filters

connectionRelationErrorDates

Label: Latest error date
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

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

connectionRelationSyncStatuses

Label: Sync status
Type: List|String
Enabled: Yes
Options:
- Excluded from syncing (##crStatusSkipped)
- Has error (##crStatusError)
- Not synced (##crStatusNotPushed)
- Partially synced (##crStatusPartiallySynced)
- Synced (##crStatusPushed)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiInvoice") {
    dataSets(name: "invoice") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    connectionRelationSyncStatuses: ["##crStatusNotPushed", "##crStatusPushed"]
  ) {
    edges {
      node {
        invoiceId
        connectionRelationSyncStatuses
      }
    }
  }
}

dueDate

Label: Due date
Type: dateRangeWithFutureInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

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

invoiceDate

Label: Invoice date
Type: dateRangeWithFutureInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

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

invoiceUrl

Label: Invoice
Type: List|InvoiceUrlString
Enabled: Yes

Filter Type: Reference to invoice collection

This filter accepts values from the invoiceViewConnection query. To get available values:

query {
  invoiceViewConnection(
    first: 100
  ) {
    edges {
      node {
        invoiceUrl    # Use this value in the filter
        invoiceId
      }
    }
  }
}

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    invoiceUrl: ["INVOICE_URL_VALUE"]
  ) {
    edges {
      node {
        invoiceId
        invoice {
          invoiceId
        }
      }
    }
  }
}

orderCustomer

Label: Customer
Type: List|PartyUrlCustomerString
Enabled: Yes

Filter Type: Reference to party collection

Note: Filters to customers only

This filter accepts values from the partyViewConnection query. To get available values:

query {
  partyViewConnection(
    first: 100
    role: ["CUSTOMER"]
    status: "PARTY_ENABLED"
  ) {
    edges {
      node {
        partyUrl    # Use this value in the filter
        name
      }
    }
  }
}

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    orderCustomer: ["PARTY_URL_VALUE"]
  ) {
    edges {
      node {
        invoiceId
        party {
          name
        }
      }
    }
  }
}

orderSaleSource

Label: Source
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    orderSaleSource: "Amazon demo"
  ) {
    edges {
      node {
        invoiceId
        orderSaleSource
      }
    }
  }
}

paymentsStatusSummary

Label: Payments status summary
Type: List|String
Enabled: Yes
Options:
- Canceled (##paymentsCanceled)
- Exceptions (##paymentsExceptions)
- N/A (##paymentsDraft)
- No payment due (##paymentsNoDue)
- Overpaid (##paymentsOverpaid)
- Paid (##paymentsFull)
- Partially paid (##paymentsPartial)
- Unpaid (##paymentsUnpaid)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiInvoice") {
    dataSets(name: "invoice") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    paymentsStatusSummary: ["##paymentsUnpaid", "##paymentsPartial"]
  ) {
    edges {
      node {
        invoiceId
        paymentsStatusSummary
      }
    }
  }
}

recordCreated

Label: Record created
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

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

recordLastUpdated

Label: Record last updated
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

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

search

Label: Not specified
Type: SearchString
Enabled: Yes

Filter Type: Search text

This filter performs a text search across multiple fields.

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    search: "search term"
  ) {
    edges {
      node {
        invoiceId
      }
    }
  }
}

searchCustom

Label: Not specified
Type: searchCustomFilter
Enabled: Yes

Filter Type: Advanced search with result expansion

See the Advanced Search guide for complete documentation on how this filter works.

Collection-Specific Examples:

Example 1: Basic search:

query {
  invoiceViewConnection(
    first: 10
    searchCustom: {
      terms: "red widget"
    }
  ) {
    edges {
      node {
        invoiceId
      }
    }
  }
}

Example 2: Include additional fields in search:

# Searches defaults PLUS custom fields
query {
  invoiceViewConnection(
    first: 10
    searchCustom: {
      terms: "acme"
      include: ["customField1", "customField2"]
    }
  ) {
    edges {
      node {
        invoiceId
      }
    }
  }
}

Example 3: Expand results to include related records:

# For each match, also return the related record
query {
  invoiceViewConnection(
    first: 10
    searchCustom: {
      terms: "urgent"
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        invoiceId
      }
    }
  }
}

Example 4: Combine include and extend:

# Search in defaults + additional fields, then expand to related records
query {
  invoiceViewConnection(
    first: 10
    searchCustom: {
      terms: "acme corp"
      include: ["customField1"]
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        invoiceId
      }
    }
  }
}

status

Label: Status
Type: List|String
Enabled: Yes
Options:
- Draft (INVOICE_IN_PROCESS)
- Posted (INVOICE_APPROVED)
- Voided (INVOICE_CANCELLED)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiInvoice") {
    dataSets(name: "invoice") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    status: ["INVOICE_IN_PROCESS", "INVOICE_APPROVED"]
  ) {
    edges {
      node {
        invoiceId
        status
      }
    }
  }
}

supplier

Label: Supplier
Type: List|PartyUrlSupplierString
Enabled: Yes

Filter Type: Reference to party collection

Note: Filters to suppliers only

This filter accepts values from the partyViewConnection query. To get available values:

query {
  partyViewConnection(
    first: 100
    role: ["SUPPLIER"]
    status: "PARTY_ENABLED"
  ) {
    edges {
      node {
        partyUrl    # Use this value in the filter
        name
      }
    }
  }
}

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    supplier: ["PARTY_URL_VALUE"]
  ) {
    edges {
      node {
        invoiceId
        party {
          name
        }
      }
    }
  }
}

type

Label: Type
Type: List|String
Enabled: Yes
Options:
- Bill (PURCHASE_INVOICE)
- Invoice (SALES_INVOICE)
- Supplier credit (SUPPLIER_CREDIT)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiInvoice") {
    dataSets(name: "invoice") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  invoiceViewConnection(
    first: 10
    type: ["SALES_INVOICE", "PURCHASE_INVOICE"]
  ) {
    edges {
      node {
        invoiceId
        type
      }
    }
  }
}