Order

Overview

Orders represent your company's plans for future work - what you intend to sell, purchase, or transfer. They are planning documents that don't affect inventory or accounting until they're fulfilled through actual transactions. This separation between planning and execution gives you flexibility to modify orders before committing to irreversible actions.

Sales orders capture customer purchase requests, including what products they want, shipping addresses, pricing, and expected delivery dates. They track the entire lifecycle from initial order entry through fulfillment and invoicing. The system calculates status summaries showing how much has been shipped, invoiced, and paid, giving you instant visibility into order progress. Financial projections like estimated gross margin help you understand profitability before shipment.

Purchase orders represent your company's requests to buy products from suppliers. They specify what products to order, quantities, expected delivery dates, and destination facilities. As goods arrive and supplier invoices are received, the purchase order tracks bill status, receipt status, and payment status, helping you manage supplier relationships and cash flow.

Transfer orders plan the movement of inventory between your own warehouse locations. They coordinate the shipment from an origin facility and receipt at a destination facility, tracking the in-transit period when goods are moving between locations but haven't yet arrived.

Fulfillment orders bridge the gap between sales orders and physical shipments. They represent exactly how a sales order will be fulfilled, handling complexities like split shipments across multiple dates, multi-warehouse fulfillment where products ship from different locations, or virtual kitting where a sold bundle is automatically broken into components during picking. A single sales order might create multiple fulfillment orders if some items ship immediately while others are backordered.

Orders support rich status tracking. They progress through draft, committed, and completed stages. The GraphQL API provides calculated status summaries that aggregate related shipments, invoices, and payments, so you can quickly see that an order is "partially shipped" or "fully invoiced but unpaid" without manually checking each related record. These summaries are essential for customer service, operations management, and financial oversight.

Understanding Prefixed Field Patterns

Many order fields use prefixes to distinguish between values calculated on the order document itself versus values derived from related entities. This pattern helps you identify discrepancies between planned and actual values.

Fields prefixed with invoice, shipment, or payment represent calculations based on related transactions:

Order-level fields (e.g., total, totalTax) represent the original planned values on the order document
Invoice-prefixed fields (e.g., invoiceTotal, invoiceTotalTax) are calculated by summing values across all related invoices
Shipment-prefixed fields represent aggregated values from related shipments
Payment-prefixed fields represent payment activity against the order

This distinction allows you to compare what was originally ordered against what was actually billed or shipped. For example, totalTax shows the tax originally calculated for the order, while invoiceTotalTax shows the actual tax billed across all invoices. Differences between these values can indicate adjustments, partial invoicing, or discrepancies that need attention.

GraphQL API

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

Query Name: orderViewConnection

Available Features:

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

Query Examples

Basic Query

The order collection is accessed via the orderViewConnection query, which returns a Relay-style connection with pagination support.

query {
  orderViewConnection(first: 10) {
    edges {
      node {
        batchId
        billsStatusSummary
        billToEmailAddress
        customerPo
        dueDate
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

# First page
query {
  orderViewConnection(first: 50) {
    edges {
      node { batchId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

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

Filtering

Apply filters to narrow results (see Filters section for all available options):

query {
  orderViewConnection(
    first: 10
    batchUrl: "/finaleengineer/api/batch/100000"
  ) {
    edges {
      node { batchId }
    }
  }
}

Sorting

Sort results by one or more fields:

query {
  orderViewConnection(
    first: 10
    sort: [{ field: "batchId", mode: "desc" }]
  ) {
    edges {
      node {
        batchId
              }
    }
  }
}

Relations

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

query {
  orderViewConnection(first: 10) {
    edges {
      node {
        batchId
        billTo {
          name
          formatted
        }
      }
    }
  }
}

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

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

Available Metrics

This collection provides 12 metrics that can be aggregated:

Metric	Parameters	Description
`orderDate`	`transform`, `operator`	orderDate for order
`subtotal`	`transform`, `operator`	Subtotal amount (before taxes and fees)
`taxableSubtotal`	`transform`, `operator`	taxableSubtotal for order
`total`	`transform`, `operator`	Total amount
`netSales`	`transform`, `operator`	netSales for order
`totalUnits`	`transform`, `operator`, `productUrlList`	Total number of units
`totalTaxDiscountsAndFees`	`transform`, `operator`	totalTaxDiscountsAndFees for order
`totalAverageCost`	`transform`, `operator`	totalAverageCost for order
`grossIncome`	`transform`, `operator`	grossIncome for order
`grossMargin`	`transform`, `operator`	Gross margin amount
`shipmentPendingValue`	`transform`, `operator`	shipmentPendingValue for order
`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
`orderDate`	Date when order was placed
`receiveDate`	receiveDate for order
`shipDate`	shipDate for order
`status`	Status value
`type`	type for order
`fulfillment`	fulfillment for order
`shippingService`	shippingService for order
`saleSource`	saleSource for order
`customer`	customer for order
`customerPartyId`	customerPartyId for order
`eligibleToShip`	eligibleToShip for order
`supplier`	supplier for order
`supplierPartyId`	supplierPartyId for order
`origin`	origin for order
`destination`	destination for order
`processingSublocation`	processingSublocation for order
`terms`	terms for order
`dueDate`	dueDate for order
`priceLevel`	priceLevel for order
`billToStateRegion`	billToStateRegion for order
`billToCountry`	billToCountry for order
`billToCountryIso3166Alpha2`	billToCountryIso3166Alpha2 for order
`shipToStateRegion`	shipToStateRegion for order
`shipToCountry`	shipToCountry for order
`shipToCountryIso3166Alpha2`	shipToCountryIso3166Alpha2 for order
`shipFromStateRegion`	shipFromStateRegion for order
`shipFromCountry`	shipFromCountry for order
`shipFromCountryIso3166Alpha2`	shipFromCountryIso3166Alpha2 for order

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

Examples

Example 1: Revenue Analysis by Date

Calculate order metrics grouped by order date:

query {
  orderViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      groupBy {
        orderDate
      }
      metrics {
        orderCount: count
        totalRevenue: total(operator: sum)
        avgOrderValue: total(operator: mean)
      }
    }
  }
}

Example 2: Order Analysis by Status

Analyze order totals grouped by order status:

query {
  orderViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      groupBy {
        status
      }
      metrics {
        orderCount: count
        totalAmount: total(operator: sum)
      }
    }
  }
}

Fields

This collection has 81 fields:

73 simple fields
7 enum fields (with predefined values)
1 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.

`batchId`

A user-defined identifier that associates an order with a batch. When an order is created with a batchId, the system automatically creates or finds the corresponding batch entity and establishes the relationship between the order and batch.

The batchId serves as a convenient way to group multiple orders together by specifying the same identifier when creating orders. This is commonly used for bulk order operations where multiple orders need to be processed as a group. For example, when creating multiple orders with batchId 'mybatch123', all those orders will be associated with the same batch entity.

The field can be edited directly, allowing orders to be reassigned to different batches or removed from batches by setting it to null. When the batchId is modified without a corresponding batchUrl, the system looks up or creates the batch based on the provided identifier. If a batchUrl is provided, it takes precedence and the batchId is derived from that batch.

Label: Batch ID
GraphQL Type: Text
Sortable: Yes

`batchUrl`

A reference link to the batch that groups this order with other related orders for processing purposes. Orders can be organized into batches to facilitate bulk operations, tracking, or workflow management. When an order is created, it can be assigned to a specific batch by providing the batch URL, and all orders within the same batch will share this reference. This field may be null if the order has not been assigned to any batch.

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: Batch Url
Sortable: No
Status: ❌ Disabled

`billToEmailAddress`

The email address where billing communications and invoices should be sent for this order. For sales orders, this is the customer's billing email address associated with their trading partner role. For other order types, it defaults to the primary organization's billing email. The system looks for a designated billing email contact method, falling back to the default work email if no specific billing email is configured.

Label: Bill to email address
Sortable: No

`customerPo`

The customer's purchase order number or reference code for this order. This field allows businesses to track and reference the purchase order number provided by their customer when placing the order, which is commonly used for order matching, invoicing, and customer service purposes.

Label: Customer PO
Sortable: No

`dueDate`

The date by which payment or fulfillment of the order is expected. This field is available for sales orders, purchase orders, and transfer orders, and typically works in conjunction with the payment terms specified on the order.

Date Field (Day Only): This field contains only day information with no time component. Unlike timestamp fields which contain both date and time in UTC, date fields represent a calendar day for business purposes.

Order Lifecycle: This user-entered date represents when the order should be completed. It helps with prioritization and resource scheduling. The meaning varies by order type: for sales orders, when delivery to customer should complete; for purchase orders, when you expect to receive goods and payment is due; for transfer orders, when the transfer should complete.

Order Type Applicability: This field can be used across all order types (sales, purchase, transfer) but is optional. Its interpretation depends on the business context and order type.

Label: Due date
GraphQL Type: Date
Sortable: No

`externalOrderId`

The unique identifier assigned to the order by an external integration system (e.g., Amazon, ShipStation, ShippingEasy). This field is extracted from integration-specific user field data stored on the order, where external systems track their own order identifiers alongside Finale's internal order ID. The value is computed by parsing the integration user field data (attributes starting with "integration_") and extracting the second space-delimited token from the attribute value.

Common examples include Amazon Order IDs (like "123-4567890-1234567"), ShipStation Order IDs (numeric values), and ShippingEasy Order IDs. When an order originates from or is synced with an external platform, the integration connection stores its tracking information in user fields, and this field exposes the external system's order identifier for reporting and reconciliation purposes.

The field is null for orders that have not been synced with any integration connection. For ShipStation connections specifically, the raw numeric value is formatted differently in the externalOrderIdFormatted field to display in ShipStation's hexadecimal format.

Label: External order id
Sortable: No

`externalOrderIdFormatted`

A formatted version of the external order identifier from integrated systems. This field presents the external order ID in a display-friendly format, which may include additional formatting such as prefixes, separators, or standardized structure compared to the raw externalOrderId field. Used when displaying order information to users where a more readable presentation of the external system's order number is needed.

Label: External order id formatted
Sortable: No

`fulfillment`

A user-defined text field that identifies the fulfillment method or carrier service for an order. This field stores values like "Customer pick-up", "Stamps.com - USPS First Class Mail", "Amazon Fulfillment", or "USPS Priority Mail" to indicate how the order will be fulfilled or shipped.

The fulfillment field is used across different order types including sales orders, transfer orders, and fulfillment orders. When importing orders from external systems, this field is automatically populated from the shipping method information (for example, BigCommerce's shipping_method field maps directly to this field). The field supports custom values and maintains a list of previously used options that can be selected when creating or editing orders. It differs from the requested shipping service field in that fulfillment typically represents the carrier or fulfillment method, while shipping service represents the specific service level.

Label: Fulfillment
GraphQL Type: OptionList
Sortable: Yes

`grossIncome`

The profit or income generated from a sales order, calculated as the difference between the sale price and the cost. This field is typically zero for purchase orders since they represent expenses rather than income. Gross income appears in order summary reports and analytics alongside related financial metrics like gross margin and invoice totals.

Label: Gross income (estimated)
Sortable: Yes

`grossMargin`

The profit margin on a sales order, expressed as a percentage. This field calculates the difference between the selling price and cost of goods, divided by the selling price, showing what percentage of revenue remains as gross profit. For example, a gross margin of 50% means that half of the sales revenue is profit after accounting for product costs. This metric helps evaluate the profitability of individual orders and can be aggregated across multiple orders to analyze overall sales performance. The field returns null for purchase orders.

Label: Gross margin (estimated)
Sortable: Yes

`hasAttachment`

Indicates whether the order has one or more file attachments associated with it. This field displays as an attachment icon in the user interface when files have been attached to the order record. The field is commonly used to quickly identify orders that have supporting documentation, such as purchase orders, packing slips, or other relevant files uploaded by users.

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

`invoiceMiscDiscountsAndFees`

The total of miscellaneous discounts and fees from all invoices associated with the order. This aggregates both taxable and non-taxable miscellaneous adjustments applied at the invoice level, providing a complete view of additional charges or discounts beyond the standard line item amounts.

Label: Invoice misc discounts and fees
Sortable: No

`invoiceMiscExternalTax`

The total amount of external tax charged on miscellaneous charges within the invoiced portion of the order. External tax refers to tax that is calculated and managed outside of the system, typically by third-party tax calculation services or external systems. This field specifically captures external tax applied to miscellaneous fees and charges, as distinct from external tax on product sales or other invoice components.

Label: Invoice misc external tax
Sortable: No

`invoiceMiscNonTaxableDiscountsAndFees`

The total value of miscellaneous non-taxable discounts, fees, and adjustments on the order's associated invoices. This includes invoice line items marked as non-taxable adjustments, such as freight charges, handling fees, restocking fees, or special discounts that are not subject to tax calculation. The field sums all adjustment items with a non-taxable designation, and these amounts are included in the invoice total but excluded from the taxable subtotal used for tax calculations.

Label: Invoice misc nontaxable discounts and fees
Sortable: No

`invoiceMiscTaxableDiscountsAndFees`

The total of miscellaneous taxable discounts and fees from all invoices associated with the order. This field aggregates any additional charges or reductions that are subject to tax calculation, excluding line item discounts and fees. Negative values represent discounts, while positive values represent fees. This amount is included in the taxable subtotal calculation for the order's invoices.

Label: Invoice misc taxable discounts and fees
Sortable: No

`invoiceNetSales`

The total net sales amount from invoices associated with this order. This represents the invoice subtotal before applying discounts, fees, and taxes. In reporting and analytics, this field is labeled as "Invoice net amount" and allows users to analyze the base sales value of invoiced orders, separate from adjustments and tax calculations that make up the final invoice total.

Label: Invoice net amount
Sortable: No

`invoicesSummary`

A summary of the invoices associated with the order, displaying the status and date of posted invoices. If the order has a single posted invoice, this field shows "Posted" followed by the invoice date (e.g., "Posted 12/20/2014"). If the invoice has no date, it displays only "Posted". If the order has multiple posted invoices, this field displays "Multiple invoices". If no invoices are posted, the field is empty.

Label: Invoices summary
Sortable: No

`invoiceSubtotal`

The total amount of all product line items on an invoice before any taxes, discounts, fees, or other adjustments are applied. This represents the base merchandise value calculated by multiplying the unit price by quantity for each product item. It serves as the starting point for calculating the invoice total, with subsequent additions or deductions for promotions, discounts, and taxes applied on top of this subtotal.

Label: Invoice subtotal
Sortable: No

`invoiceTaxableSubtotal`

The portion of the invoice subtotal that is subject to tax calculation. This amount includes all taxable line items and taxable discounts or fees, but excludes non-taxable items such as freight or other non-taxable adjustments. The taxable subtotal is used as the basis for calculating sales tax on the invoice.

Label: Invoice taxable subtotal
Sortable: No

`invoiceTotal`

The total invoice amount for the order, calculated by summing the totals across all related invoice records. This field represents what has actually been billed, as opposed to what was originally planned on the order.

Derived from Related Invoices: This field is calculated by aggregating values from all invoices associated with the order. It reflects actual billing activity rather than the original order plan. This is part of the invoice-prefixed field pattern described in the overview - fields with the "invoice" prefix represent calculations based on related transactions rather than the order document itself.

Comparison with total: The total field represents the amount as originally planned on the order document. While total shows what was ordered, this invoiceTotal field shows what was actually invoiced. These values may differ due to:

Partial invoicing (only some items billed so far)
Adjustments made on invoices that differ from the order
Discrepancies between what was ordered and what was actually billed

Use for Financial Reporting: For revenue recognition and financial reporting, use this field as it represents actual billing. For planning and quoting, use the total field. Comparing these two values helps identify discrepancies between planned and actual billing that may need attention.

Label: Invoice total
Sortable: No

`invoiceTotalDiscountsAndFees`

The total amount of all discounts and fees applied to the invoice associated with this order. This represents the combined total of both taxable and non-taxable discounts and fees. A positive value indicates net fees charged, while a negative value indicates net discounts applied. This field is used in reporting and analytics to understand the overall impact of discounts and fees on invoice totals.

Label: Invoice total discounts and fees
Sortable: No

`invoiceTotalExternalTax`

The total amount of tax on the order's invoices that comes from external sources rather than being calculated internally by the system. External tax is typically entered manually or imported from third-party tax calculation services, as opposed to tax that is automatically computed based on configured tax rates and authorities. This field aggregates all external tax adjustments across the order's invoices, appearing separately from internally calculated tax in order totals.

Label: Invoice total external tax
Sortable: No

`invoiceTotalNonTaxableDiscountsAndFees`

The total amount of all discounts and fees applied to the order that are marked as non-taxable. These are adjustments that affect the order total but do not have sales tax applied to them. This is calculated by summing all order adjustments where the tax enumeration is set to NON_TAXABLE and the adjustment is classified as a discount or fee.

Label: Invoice total nontaxable discounts and fees
Sortable: No

`invoiceTotalTax`

The total amount of tax applied to an invoice associated with the order. This field sums all tax charges on the invoice and is displayed as a currency value. It represents the tax portion that contributes to the overall invoice total.

Label: Invoice total tax
Sortable: No

`invoiceTotalTaxableDiscountsAndFees`

The total amount of discounts and fees applied to invoiced items on the order that are subject to tax. This field separates taxable discounts and fees from non-taxable ones, allowing the system to correctly calculate tax on the adjusted invoice amounts. For example, if an invoice has a $2 delivery fee that is taxable, that amount would be included in this total. This value contributes to the invoice's taxable subtotal calculation and ultimately affects the total tax due on the order.

Label: Invoice total taxable discounts and fees
Sortable: No

`lastSynced`

The timestamp when the order was last synchronized with an external integration or connection. This field tracks when the order data was most recently pushed to or pulled from connected third-party systems such as e-commerce platforms, shipping services, or other business applications. This helps users determine the currency of order information across integrated systems and identify when an order may need to be re-synced if changes were made.

Label: Last synced
Sortable: Yes

`lastSyncedFrom`

The timestamp indicating when the order was last synchronized from an external system into Finale. This field is displayed on order detail screens when integration connections are present, appearing alongside the sync status to show when data was most recently pulled from connected platforms like QuickBooks Online. It helps users track the recency of synchronized order information coming into the system.

Label: Last synced from
Sortable: Yes

`lastSyncedTo`

The timestamp when this order was last successfully synchronized to an external system or integration. This field is displayed on order detail screens when integration support is enabled, such as when syncing orders to QuickBooks or Amazon FBA inbound plans. It helps users track when order data was most recently pushed to connected external systems.

Label: Last synced to
Sortable: Yes

`miscDiscountsAndFees`

The total amount of miscellaneous discounts and fees applied at the order level, excluding line item-level adjustments. This includes both taxable and non-taxable discounts and fees that apply to the entire order rather than individual items. The value is calculated from the order's adjustment list and represents the sum of all miscellaneous order-level pricing adjustments.

Label: Misc discounts and fees
Sortable: No

`miscExternalTax`

The total amount of external tax charges on the order that are not associated with any specific promotion. This field relates to Finale's external tax system, which is the most common tax approach. In the external tax system, tax amounts are calculated by third-party systems (like Shopify or Amazon) and stored in Finale as additional line items, with no item-level tax calculations performed within Finale.

This field sums all external tax adjustments on the order that do not have a product promotion linked to them, representing miscellaneous external tax charges applied to the order.

Label: Misc external tax
Sortable: No

`miscNonTaxableDiscountsAndFees`

The total amount of miscellaneous discounts and fees applied to the order that are designated as non-taxable. This field captures adjustments such as student discounts or other promotional discounts and fees that have been marked with a non-taxable status, meaning they are not subject to sales tax calculations. This amount is tracked separately from taxable discounts and fees to ensure accurate tax reporting and compliance.

Label: Misc nontaxable discounts and fees
Sortable: No

`miscTaxableDiscountsAndFees`

The total amount of miscellaneous discounts and fees on the order that are subject to tax. This separates out the taxable portion from the total miscellaneous discounts and fees, working in conjunction with miscNonTaxableDiscountsAndFees to categorize these charges based on their tax treatment. This field is used in order financial calculations to properly compute taxable amounts and overall order totals.

Label: Misc taxable discounts and fees
Sortable: No

`netSales`

The net sales amount for the order, representing the subtotal plus any taxable and non-taxable discounts and fees, but excluding tax amounts. This is the total sales value before tax is applied, and differs from the order total when tax is included. The field is labeled as "Net amount" in the user interface and can be used for sorting orders and calculating aggregate metrics.

Label: Net amount
Sortable: Yes

`orderCancellationReason`

The reason why an order was cancelled, selected from predefined options such as No Inventory, Buyer Cancelled, General Adjustment, Shipment Address Undeliverable, Customer Exchange, Pricing Error, or Duplicate Order. This field is populated when an order is cancelled to track and categorize the business reason for the cancellation, helping with reporting and understanding why orders don't complete successfully.

Label: Order cancellation reason
Sortable: No

`orderDate`

The date when the order was placed or created. This field is used to track when orders occurred, filter orders by date ranges, sort orders chronologically, and calculate time-based metrics such as reorder periods and sales trends.

Date Field (Day Only): This field contains only day information with no time component. Unlike timestamp fields (such as recordCreatedTimestamp, recordLastUpdatedTimestamp) which contain both date and time in UTC, date fields represent a calendar day for business purposes.

Order Lifecycle: This is typically a user-entered or system-generated date that marks the start of the order lifecycle. For sales orders, this represents when the customer placed the order. For purchase orders, this represents when you placed the order with the supplier. This date is often used for reporting, sorting, and filtering orders by time period.

Order Type Applicability: This field applies to all order types (sales, purchase, transfer) and is typically required.

Label: Order date
GraphQL Type: Date
Sortable: Yes

`orderId`

The unique identifier for an order that is displayed to users. This is the human-readable order number that users reference when discussing or searching for specific orders, such as '891' or '892'. The orderId is used to look up order information and can be used for filtering and searching orders across the system.

Label: Order ID
Sortable: Yes
Default Formatter: html

Example Query:

{
  order(orderUrl: "example-url") {
    orderId    # Uses default formatter: html
    orderIdRaw: orderId(formatter: "none")  # Get raw value
  }
}

`orderUrl`

The unique identifier for this specific order resource. This URL is automatically generated by the server and serves as the primary key for retrieving the order's details and referencing the order in related records such as batches, fulfillments, invoices, and order history.

⚠️ CRITICAL: URLs Are Opaque - Do Not Parse or Construct

Treat URL values as opaque strings provided by the API. Do not parse, interpret, or manually construct URLs:

URL structure is not a stable API contract - the internal format may change without notice in future versions

ID values in URLs may differ from entity ID values displayed to users

Parsing URLs will break when implementation details change

Always use URL values exactly as returned by the API - never attempt to build them from component parts

Violating this principle creates brittle integrations that will fail when the system evolves. URLs are identifiers, not data structures to be decomposed.

The URL format typically includes the accountPathComponent (identifying which Finale account), the API base path, and the order's internal identifier (e.g., /accountName/api/order/12345). However, you must never rely on this format remaining stable.

Label: Order Url
Sortable: No

`priceLevel`

The pricing tier or discount category applied to the order, such as "Wholesale", "Direct ship", or "10% Local discount". This field indicates what pricing structure should be used when calculating prices for items on this order. The price level is typically determined by the customer relationship, sales channel, or specific promotional arrangements, and can be used to group and analyze orders by their pricing structure.

Label: Price level
GraphQL Type: OptionList
Sortable: No

`privateNotes`

Internal notes about the order that are visible only to staff and not shown to customers. These notes are used by team members to communicate important information about order fulfillment, such as special handling instructions, customer requests made via phone or email, inventory concerns, or other internal reminders. Unlike public notes which may be shared with customers, private notes contain information meant exclusively for internal use.

Label: Internal notes
GraphQL Type: Text
Sortable: No
Default Formatter: html

Example Query:

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

`publicNotes`

Notes about the order that are visible to external parties, such as customers or shipping carriers. Unlike private notes which are for internal use only, public notes can be shared outside the organization and may be included in customer-facing documents or transmitted to third-party integrations like ShipStation.

Label: Public notes
GraphQL Type: Text
Sortable: No
Default Formatter: html

Example Query:

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

`receiveDate`

The estimated date when goods from a purchase order or transfer order are expected to be received at the destination facility. This field helps businesses track and manage incoming inventory timelines for orders. For purchase orders, it represents when the ordered products are expected to arrive from the supplier. For transfer orders, it indicates when inventory is expected to reach the destination location. The field can be null if no receive date has been set, and is primarily used for purchase orders and transfer orders rather than sales orders.

Label: Estimated receive date
GraphQL Type: Date
Sortable: Yes

`recordCreated`

The timestamp when the order record was first created in the system. This represents the date and time when the order was initially entered into the database, capturing the moment of the order's creation regardless of subsequent modifications or status changes.

Label: Record created
Sortable: Yes

`recordLastUpdated`

The date and time when the order record was last modified or updated in the system. This field displays in a readable format such as "Dec 19 2018 7:19:02 am" and can be formatted in different timezones. Users can filter and sort orders based on when they were last updated to track recent changes or modifications to order information.

Label: Record last updated
Sortable: Yes

`referenceNumber`

A user-defined identifier or external system identifier used to track and reference the order. This field commonly stores order numbers from integrated sales channels or e-commerce platforms, such as marketplace order IDs or Point of Sale system reference numbers. It allows businesses to maintain consistency between their external systems and Finale records, and can be used for searching, reporting, and reconciling orders across different platforms.

Label: Reference number
Sortable: No

`saleSource`

The sales channel or marketplace where the order originated, such as Amazon, Etsy, or other selling platforms. This field can be automatically populated from the customer's default sale source setting when the order is created, and can be used to track which sales channels generate revenue. The sale source may be configured with specific accounting rules for different order types, allowing financial reporting to be segmented by sales channel.

Label: Source
GraphQL Type: OptionList
Sortable: Yes

`shipDate`

The planned or expected date when the order should be shipped. For sales orders, this represents when products should leave your facility to meet customer expectations. For purchase orders, this represents when the supplier is expected to ship the goods to you.

Date Field (Day Only): This field contains only day information with no time component. Unlike timestamp fields which contain both date and time in UTC, date fields represent a calendar day for business purposes.

Order Lifecycle: This is typically a user-entered date representing the expected or planned ship date. It helps with scheduling and prioritizing fulfillment. The actual ship date is recorded on the shipment record when items physically ship. This field is important for coordinating warehouse operations and managing customer expectations.

Order Type Applicability: This field applies to sales orders and purchase orders. For transfer orders, this date represents when items should leave the origin facility.

Label: Estimated ship date
GraphQL Type: Date
Sortable: Yes

`shipFromEmailAddress`

The email address associated with the location or party from which the order is being shipped. For purchase orders, this is the trading partner's (vendor's) email address. For sales orders, this is typically the primary warehouse or fulfillment center's contact email address. This field is used for shipment communications and notifications related to outbound deliveries.

Label: Ship from email address
Sortable: No

`shipmentPendingValue`

The total value of purchase order items that have not yet been received through shipments. This field calculates the monetary value of the quantity difference between what was ordered and what has been received. For example, if a purchase order contains 5 units at $1.51 each but only 2 units have been received via shipment, the shipment pending value would be $4.53 (3 units × $1.51). This field is typically used on locked purchase orders to track the dollar amount of outstanding inventory expected to arrive.

Label: Shipment pending value
Sortable: Yes

`shipmentsSummary`

A human-readable summary of the shipment status for the order. For orders with no shipments, this field is empty. For orders with a single shipment that has not yet shipped, it displays the estimated ship date (for example, "Estimated ship date: 8/12/2010"). For orders with a single completed shipment, it shows when the order shipped (for example, "Shipped 8/14/2010"). For orders with multiple shipments, it displays "Multiple shipments" to indicate the order has been split across multiple shipments.

Label: Shipments summary
Sortable: No

`shippingService`

The shipping method or service level requested for the order, such as "Next day" or other carrier service options. This field captures the customer's or seller's preference for how the order should be shipped, which may differ from the actual shipping service used on individual shipments. The field can be left blank when no specific shipping service is requested.

Label: Requested shipping
GraphQL Type: OptionList
Sortable: Yes

`shipToEmailAddress`

The email address of the party receiving the shipment. For sales orders, this is the trading partner's (customer's) email address retrieved from their contact information. For other order types, it defaults to the primary organization's email address. This field is used for shipping notifications and delivery communications related to the order.

Label: Ship to email address
Sortable: No

`stdAccountingCost`

The total standard cost for all items on the order, calculated by multiplying each product's user-entered standard cost by the ordered quantity.

⚠️ Important: Order Costs Are Estimates

Orders are planning documents that do not post transactions to inventory or accounting. Actual costs are not finalized until shipment. Cost values on orders are estimates that may change between order placement and fulfillment as purchases are received, costs are adjusted, or inventory levels change. For final, accurate costs, refer to the shipment and COGS values recorded at the time items actually ship.

Not Recommended: Standard cost is a user-entered field on the product that does not use Finale's internal accounting system. It is simply multiplied by quantity to get a cost estimate. This approach does not reflect actual inventory costs or accounting transactions.

Better Alternatives: Use totalAverageCost (recommended) or totalCogs instead. These values are automatically updated by Finale's accounting system as purchases are received and sales/adjustments occur, providing accurate cost information based on actual inventory movements. See those fields for more information on the recommended cost calculation methods.

Label: Order Std Accounting Cost
Sortable: No

`subtotal`

The sum of all line item amounts on the order, calculated by multiplying the quantity times the unit price for each order item. This represents the base order amount before any adjustments, discounts, fees, or taxes are applied. For purchase orders, this reflects the total cost of items ordered from the supplier. For sales orders, this represents the total sales value of items sold to the customer before additional charges or deductions.

Label: Subtotal
Sortable: Yes

`syncStatus`

Indicates whether the order should be synchronized to or from an external integration platform such as Amazon, Magento, or ShipStation. When set, this field triggers the order to be sent to an integration (To) or marks it as having been received from an integration (From). Users can select from available sync options like "To ShipStation" or "From Amazon" to initiate order synchronization with connected external systems. The field prevents duplicate syncing by blocking attempts to sync an order that already has an active sync or has already been synced to the same integration.

Label: Sync status
Sortable: No

`syncStatusConnection`

The connection associated with the current synchronization status of the order. This field identifies which external integration or connection is responsible for the order's current sync state, working in conjunction with the syncStatus field to track integration activity. The field helps users understand which connected system (such as an e-commerce platform, marketplace, or accounting software) is currently managing or has most recently updated the order's synchronization status.

Label: Sync status connection ID
Sortable: No

`syncStatusFrom`

Further information is not available.

Label: Synced from
Sortable: No

`syncStatusFromConnection`

The identifier of the external connection from which this order was synced into the system. This field works together with syncStatusFrom to track when orders are imported from external systems or integrations, identifying which specific connection was used to bring the order data in.

Label: Synced from connection ID
Sortable: No

`syncStatusTo`

Indicates the external system or integration connection where this order is being synchronized to. This field is used to track which third-party platform (such as Amazon, ShipStation, QuickBooks Online, or Magento) the order will be sent to for fulfillment, accounting, or other business processes. The value references a specific integration connection configured in the system. For example, an order might be marked as syncing "To ShipStation (CAN)" to indicate it will be sent to that shipping platform for fulfillment processing.

Label: Synced to
Sortable: No

`syncStatusToConnection`

The external integration or connection that an order is being synced to. This field identifies the specific connection (such as Amazon, ShipStation, or Magento) when the order's sync direction is outbound. For example, when syncing an order to a ShipStation connection, this field contains the connection identifier. This works together with the sync status to track which external system the order data is being sent to for integration purposes.

Label: Synced to connection ID
Sortable: No

`taxableSubtotal`

The portion of the order total that is subject to tax calculation. This includes the subtotal of all product items plus any discounts or fees that are marked as taxable. Non-taxable discounts and fees are excluded from this amount. This field is used as the basis for calculating sales tax on the order.

Label: Taxable subtotal
Sortable: Yes

`terms`

The payment terms that define when payment is due for the order. Common examples include net 15 (payment due within 15 days), net 30 (payment due within 30 days), or cash on delivery. This field specifies the agreed-upon timeline between the business and the customer or supplier for settling the order balance.

Label: Terms
GraphQL Type: OptionList
Sortable: No

`title`

A formatted display label for the order, typically showing the order ID along with additional contextual information. By default, the title displays just the order ID, but can include the order date separated by a middot character, such as "1234 · 2/2/2018". For purchase orders, the title may include supplier information in the format "1234 ::: Alpha Fireworks". For sales orders, it may show customer information like "1234 / Big Parks". The title can also display special states like "New quote 1234" for quotes that haven't been finalized. The format is customizable through templates to include party names, custom fields, and other order attributes, providing users with a quick, readable identifier for the order in lists and reports.

Label: Title
Sortable: No

`total`

The complete order amount including the subtotal plus all taxes, discounts, and fees. This is the final amount for the order after all adjustments have been applied.

Calculated on Order Document: This field represents the total as originally planned and recorded on the order document itself. It is calculated from the order's line items, taxes, and adjustments at the time the order was created or last updated.

Comparison with invoiceTotal: The invoiceTotal field represents the actual billed amount calculated by summing all related invoice values. While total shows what was originally ordered, invoiceTotal shows what was actually invoiced. These values may differ due to partial invoicing, adjustments made on invoices, or discrepancies between the order and what was actually billed.

Use for Financial Reporting: For planning and quoting, use this field. For actual revenue recognition and financial reporting on what was billed, use invoiceTotal. Comparing these two values helps identify discrepancies that need attention.

Label: Total
Sortable: Yes

`totalAverageCost`

The total average cost for all items on the order, representing the sum of average costs across all order line items.

⚠️ Important: Order Costs Are Estimates

Orders are planning documents that do not post transactions to inventory or accounting. Actual costs are not finalized until shipment. This average cost value represents the current estimate based on today's inventory costs, but the final cost assigned to the order will be determined at the shipment date, not the order date. Costs may change between order placement and fulfillment as purchases are received, costs are adjusted, or inventory levels change. For final, accurate costs, refer to the COGS value recorded when items actually ship.

Recommended Cost Method: Average cost is automatically updated by Finale's accounting system as purchases are received and sales/adjustments happen. This provides an accurate, continuously-updated cost basis that reflects actual inventory movements and accounting transactions. Average cost uses a weighted average calculation based on all purchase receipts and is the recommended approach for cost tracking.

How It Differs from Other Cost Fields:

Standard Cost (stdAccountingCost): User-entered field, not connected to accounting system, not recommended
COGS (totalCogs): Actual cost at time of shipment, only available after items ship
Average Cost (this field): Current accounting-based cost estimate, recommended for pre-shipment analysis

Use this field for profitability analysis and margin calculations when evaluating orders before shipment.

Label: Total COGS (estimated)
Sortable: Yes

`totalCogs`

The total cost of goods sold for items that have been shipped on this order. This represents the actual cost incurred for shipped inventory, calculated automatically at the time of shipment.

⚠️ Important: Order Costs Are Estimates Until Shipment

Orders are planning documents that do not post transactions to inventory or accounting. COGS is only available after items ship. Until shipment occurs, order cost fields show estimates. The actual cost assigned to the order is determined at the shipment date, not the order date. This COGS value represents the final, accurate cost recorded when items physically shipped, using the average cost at that specific moment. This is the authoritative cost for financial reporting and profitability analysis.

Generated at Shipment Time: COGS is automatically calculated when items ship, using the average cost at that specific moment. This is the final, accurate cost for accounting purposes. The cost may differ from the estimated cost at order time if purchases or adjustments occurred between order placement and shipment.

How It Differs from Other Cost Fields:

Standard Cost (stdAccountingCost): User-entered field, not connected to accounting system, not recommended
Average Cost (totalAverageCost): Current accounting-based estimate, available before shipment
COGS (this field): Final actual cost at shipment time, only available after items ship

Recommended: Use COGS for final profitability analysis and financial reporting. This is the most accurate cost value, but is only available after shipment has occurred. For pre-shipment cost estimates, use totalAverageCost.

Label: Total COGS (shipped)
Sortable: No

`totalDiscountsAndFees`

The total monetary value of all discounts and fees applied to the order, combining both taxable and non-taxable adjustments. This field provides a comprehensive view of order-level adjustments that affect the final order total, whether those adjustments reduce the price (discounts) or increase it (fees). It serves as an aggregate amount that includes values that may be further categorized in related fields such as taxable discounts and fees, non-taxable discounts and fees, and tax-specific discounts and fees.

Label: Total discounts and fees
Sortable: No

`totalExternalTax`

The sum of all tax charges on the order that were calculated by an external tax service or system, rather than by the internal tax calculation engine. This is the most common tax approach used in Finale, as most users calculate sales tax on their shopping carts (like Shopify or Amazon) before orders reach Finale.

External taxes are stored as additional line items with no item-level tax calculations performed by Finale. The tax amounts are provided by the external system and recorded as-is. External taxes are identified by having a tax type of 'EXT_TAX' and no internal tax authority reference. This total includes all externally-calculated tax adjustments applied to the order, regardless of whether they are associated with specific promotions or are general miscellaneous taxes.

Label: Total external tax
Sortable: No

`totalNonTaxableDiscountsAndFees`

The sum of all discounts and fees on the order that are not subject to tax. This field isolates the non-taxable portion of the order's total discounts and fees, complementing the totalTaxableDiscountsAndFees field. Together, these two fields comprise the totalDiscountsAndFees amount on the order.

Label: Total nontaxable discounts and fees
Sortable: No

`totalTax`

The total amount of tax charged on the order. This includes all applicable sales taxes, use taxes, and other tax types that apply to the taxable items in the order.

Finale handles tax calculations in two ways:

Internal Tax System: Users specify tax rates in Finale, and the system calculates tax per item and per order. This approach is less commonly used.

External Tax System (most common): Tax amounts come from third-party systems like Shopify, Amazon, or other sales channels. The external system calculates tax, and Finale stores it as an additional line item. In this approach, Finale does not perform item-level tax calculations - it simply records the tax amounts provided by the external system. For external taxes, see the totalExternalTax and miscExternalTax fields.

The total tax is calculated separately from the subtotal and is added along with discounts and fees to determine the final order total.

Label: Total tax
Sortable: No

`totalTaxableDiscountsAndFees`

The total amount of discounts and fees applied to the order that are subject to sales tax. This represents order-level adjustments (such as shipping fees, handling charges, or promotional discounts) that should be included in the taxable base when calculating tax. Adjustments marked as non-taxable are excluded from this total. This field is used to determine the taxable subtotal of the order before tax is applied.

Label: Total taxable discounts and fees
Sortable: No

`totalTaxDiscountsAndFees`

The combined total of all taxes, discounts, and fees applied to the order. This field aggregates all adjustments that modify the order's subtotal to arrive at the final total amount. The value can be positive when taxes and fees outweigh discounts, or negative when discounts exceed taxes and fees. This field is displayed as "Tax/Dis/Fee" in order views and provides a quick summary of all adjustments before reaching the final order total.

Label: Total tax, discounts and fees
Sortable: No

`trackingSummary`

A summary of all shipment tracking information associated with the order, displaying each shipment's name, carrier, and tracking number in a readable format. For example, if an order has been shipped via multiple shipments, this field would display something like "Shipment 1: USPS: 123, Shipment 2: FedEx: 456". This provides users with a quick overview of how an order has been shipped and the tracking numbers they can use to monitor delivery progress.

Label: Tracking summary
Sortable: No

`transferOrderSearchLabel`

A formatted, human-readable label for transfer orders that combines key identifying information for easy searching and display. The label includes the order ID, order date, origin location, and destination location, separated by bullets for readability. This provides users with a quick, comprehensive summary of a transfer order at a glance, showing where inventory is being moved from and to, when the transfer was created, and its unique identifier.

Label: Transfer order search label
Sortable: Yes

Enum Fields

These fields return one of a predefined set of values.

`billsStatusSummary`

A summary of the billing status for an order, indicating how much of the order has been invoiced. This field shows whether the order is fully billed, partially billed, or has no bills posted yet. It is commonly used in formulas and reports to track billing progress, such as identifying orders that are fully received but fully billed, or to filter orders by their billing completion status.

Label: Bills status summary
Sortable: No

Possible Values:

##nonePosted - No bill posted
##postedPartial - Partially billed
##postedFull - Fully billed
##postedExceptions - Billed w/ exceptions
##otherError - Other error

`eligibleToShip`

The shipping eligibility status of an order, indicating whether the order is ready to ship and identifying any issues preventing shipment. This field categorizes orders into statuses such as "Eligible" (ready to ship), "Backordered" (items not in stock), "Uncommitted" (inventory not allocated), "Fully packed" (already packed for shipping), "Fully shipped" (already shipped), "No origin" (no origin facility assigned), and "Incomplete" (missing required order information). Users can filter and group orders by this field to prioritize fulfillment activities and identify orders that need attention before they can be shipped.

Label: Fulfillment status
Sortable: No

Possible Values:

ORDER_ELIGIBLE - Eligible
ORDER_BACKORDERED - Backordered
ORDER_UNCOMMITTED - Uncommitted
ORDER_SHIPPED - Fully shipped
ORDER_PACKED - Fully packed
ORDER_NO_ORIGIN - No origin
ORDER_INCOMPLETE - Incomplete
ORDER_RECEIVED - Fully received
OTHER_ERROR - Other error

`invoicesStatusSummary`

A read-only derived field that summarizes the invoicing status by examining all invoices associated with the order. This field is automatically calculated and cannot be set directly - it reflects the actual state of related invoices.

The system calculates this status by comparing what was ordered against what has been invoiced:

No invoice posted: Nothing invoiced yet
Partially invoiced: Some value invoiced
Fully invoiced: Complete value invoiced
Invoiced w/ exceptions: Over/under invoiced compared to the order

This status provides a quick overview of billing progress and is essential for financial oversight. Unlike the order's status field (which is user/API-controlled), this field is derived from the actual invoice records and updates automatically as invoices are created and posted. It works alongside shipmentsStatusSummary to give you complete visibility into order fulfillment and billing.

Label: Invoices status summary
Sortable: No

Possible Values:

##nonePosted - No invoice posted
##postedPartial - Partially invoiced
##postedFull - Fully invoiced
##postedExceptions - Invoiced w/ exceptions
##otherError - Other error

`paymentsStatusSummary`

A summary indicator of the payment status associated with the order, providing a quick overview of whether payments are complete, pending, overpaid, or canceled. This field helps users quickly understand the payment state of an order without needing to examine individual payment records. The field displays status values such as payments overpaid, payments canceled, or payments draft, allowing users to identify orders that may require payment follow-up or reconciliation.

Label: Payments status summary
Sortable: No
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:

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

`shipmentsStatusSummary`

A read-only derived field that summarizes the shipping/receiving status by examining all shipments associated with the order. This field is automatically calculated and cannot be set directly - it reflects the actual state of related shipments.

The system calculates this status by comparing what was ordered against what has been packed, shipped, or received:

Not packed or shipped: No shipment activity
Partially packed: Some items packed, not all
Fully packed: Everything packed, nothing shipped yet
Partially shipped: Some items shipped
Fully shipped: Everything has shipped
In transit: Shipped but not received (for purchases/transfers)
Partially received: Some items received
Fully received: Everything received
Received w/ exceptions: Shipped more or less than ordered

This status is essential for operations management, helping you identify orders that need fulfillment action. Unlike the order's status field (which is user/API-controlled), this field is derived from the actual shipment records and updates automatically as shipments are processed.

Label: Shipments status summary
Sortable: No

Possible Values:

##nonePackedShipped - Not packed or shipped
##packedPartial - Partially packed
##packedFull - Fully packed
##packedExceptions - Packed w/ exceptions
##shippedPartial - Partially shipped
##shippedFull - Fully shipped
##shippedExceptions - Shipped w/ exceptions
##shippedNotReceived - In transit
##noneReceived - Not received
##receivedPartial - Partially received
##receivedFull - Fully received
##receivedExceptions - Received w/ exceptions
##otherError - Other error

`status`

The current lifecycle state of the order. This field operates as a state machine that controls what actions can be taken on the order.

Status Progression:

Draft (ORDER_CREATED): Orders can be freely modified. Use this state for quotes or orders still being configured.
Committed (ORDER_LOCKED): Orders are locked and ready for execution. Key fields cannot be modified to prevent changes during fulfillment.
Completed (ORDER_COMPLETED): All work related to the order has been done. No further modifications allowed.
Cancelled (ORDER_CANCELLED): Order was abandoned. Cannot create shipments or invoices.

Modifying Orders: Only orders in Draft status can be freely edited. To modify a Committed or Completed order, you must move it back to Draft status first. This safeguard prevents accidental changes during fulfillment or after completion.

Distinguished from Derived Status Fields: The status field is user/API-controlled and represents the order document's state. This is different from read-only derived status fields like shipmentStatus and invoiceStatus, which are automatically calculated based on related shipments and invoices. While you set the order status directly, shipment and invoice status fields reflect the actual fulfillment and billing progress.

Label: Status
GraphQL Type: OptionList
Sortable: Yes

Possible Values:

ORDER_CREATED - Draft
ORDER_LOCKED - Committed
ORDER_COMPLETED - Completed
ORDER_CANCELLED - Canceled

`type`

The category of order that determines its purpose and workflow within the system. Orders can be sales orders for selling products to customers, purchase orders for buying products from suppliers, or fulfillment orders for internal inventory movements. The order type is set when the order is first created and cannot be changed afterward, ensuring order integrity throughout its lifecycle. The type determines which parties can be associated with the order, such as customers for sales orders or suppliers for purchase orders.

Label: Type
Sortable: No

Possible Values:

PURCHASE_ORDER - Purchase
SALES_ORDER - Sale
TRANSFER_ORDER - Transfer

Parameterized Fields

These fields accept parameters to customize the returned data. Parameters allow filtering by location, date ranges, aggregation methods, and more.

`totalUnits`

The total number of individual units across all items in the order. This represents the sum of units calculated from the quantities of all order items, taking into account different packing configurations (such as cases versus individual items). The field can be filtered to show total units for specific products by passing a product URL or list of product URLs. This metric is commonly used in reporting and analytics to understand order volume in terms of actual unit counts rather than just line item counts or dollar amounts.

Label: Total units
Sortable: Yes

Parameters:

productUrlList (List|ProductUrlString) Product(s)

Example Query:

{
  order(orderUrl: "example-url") {
    totalUnits(
      productUrlList: ["example-value"]
    )
  }
}

Relations

billTo

Related Collection: address
Label: Bill to

The billing address for this order. Invoices and payment communications are sent to this address. For sales orders, this defaults to the customer's designated billing address.

Example Query:

query {
  orderViewConnection(first: 10) {
    edges {
      node {
        billTo {
          name
          formatted
        }
      }
    }
  }
}

connectionRelation

Related Collection: connectionRelation
Label: Integration

Example Query:

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

recordCreatedUser

Related Collection: userLogin
Label: Record created user

Example Query:

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

recordLastUpdatedUser

Related Collection: userLogin
Label: Record last updated user

Example Query:

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

shipFrom

Related Collection: address
Label: Ship from

Example Query:

query {
  orderViewConnection(first: 10) {
    edges {
      node {
        shipFrom {
          name
          formatted
        }
      }
    }
  }
}

shipTo

Related Collection: address
Label: Ship to

The shipping destination address for this order. This is where the products will be delivered. For sales orders, this is typically the customer's delivery address and may differ from the billing address.

Example Query:

query {
  orderViewConnection(first: 10) {
    edges {
      node {
        shipTo {
          name
          formatted
        }
      }
    }
  }
}

processingSublocation

Related Collection: facility
Label: Transit sublocation

Example Query:

query {
  orderViewConnection(first: 10) {
    edges {
      node {
        processingSublocation {
          name
          facilityUrl
        }
      }
    }
  }
}

Filters

batchUrl

Label: Batch
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    batchUrl: "/finaleengineer/api/batch/100000"
  ) {
    edges {
      node {
        orderId
        batchUrl
      }
    }
  }
}

billToCountry

Label: Bill to country
Type: List|String
Enabled: Yes
Options: See Country Codes (ISO 3166-1 alpha-3)

billToStateRegion

Label: Bill to state / region
Type: List|String
Enabled: Yes
Options: See State and Region Codes

billsStatusSummary

Label: Bills status summary
Type: List|String
Enabled: Yes
Options:
- Billed w/ exceptions (##postedExceptions)
- Fully billed (##postedFull)
- No bill posted (##nonePosted)
- Other error (##otherError)
- Partially billed (##postedPartial)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiSalesOrder") {
    dataSets(name: "order") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  orderViewConnection(
    first: 10
    billsStatusSummary: ["##nonePosted", "##postedPartial"]
  ) {
    edges {
      node {
        orderId
        billsStatusSummary
      }
    }
  }
}

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 {
  orderViewConnection(
    first: 10
    connectionRelationErrorDates: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        orderId
        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: "uiSalesOrder") {
    dataSets(name: "order") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

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

customer

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 {
  orderViewConnection(
    first: 10
    customer: ["PARTY_URL_VALUE"]
  ) {
    edges {
      node {
        orderId
        party {
          name
        }
      }
    }
  }
}

destination

Label: Destination
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    destination: "US"
  ) {
    edges {
      node {
        orderId
        destination
      }
    }
  }
}

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 {
  orderViewConnection(
    first: 10
    dueDate: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        orderId
        dueDate
      }
    }
  }
}

eligibleToShip

Label: Fulfillment status
Type: List|String
Enabled: Yes
Options:
- Backordered (ORDER_BACKORDERED)
- Eligible (ORDER_ELIGIBLE)
- Fully packed (ORDER_PACKED)
- Fully shipped (ORDER_SHIPPED)
- Incomplete (ORDER_INCOMPLETE)
- No origin (ORDER_NO_ORIGIN)
- Uncommitted (ORDER_UNCOMMITTED)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiSalesOrder") {
    dataSets(name: "order") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  orderViewConnection(
    first: 10
    eligibleToShip: ["ORDER_ELIGIBLE", "ORDER_BACKORDERED"]
  ) {
    edges {
      node {
        orderId
        eligibleToShip
      }
    }
  }
}

fulfillment

Label: Fulfillment
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    fulfillment: "Standard"
  ) {
    edges {
      node {
        orderId
        fulfillment
      }
    }
  }
}

invoicesStatusSummary

Label: Invoices status summary
Type: List|String
Enabled: Yes
Options:
- Fully invoiced (##postedFull)
- Invoiced w/ exceptions (##postedExceptions)
- No invoice posted (##nonePosted)
- Other error (##otherError)
- Partially invoiced (##postedPartial)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiSalesOrder") {
    dataSets(name: "order") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  orderViewConnection(
    first: 10
    invoicesStatusSummary: ["##nonePosted", "##postedPartial"]
  ) {
    edges {
      node {
        orderId
        invoicesStatusSummary
      }
    }
  }
}

orderCancellationReason

Label: Order cancellation reason
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    orderCancellationReason: "Customer Request"
  ) {
    edges {
      node {
        orderId
        orderCancellationReason
      }
    }
  }
}

orderDate

Label: Order 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 {
  orderViewConnection(
    first: 10
    orderDate: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        orderId
        orderDate
      }
    }
  }
}

orderId

Label: Order ID
Type: List|String
Enabled: No

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    orderId: "1001"
  ) {
    edges {
      node {
        orderId
        orderId
      }
    }
  }
}

orderUrl

Label: Order
Type: List|OrderUrlString
Enabled: Yes

Filter Type: Reference to order collection

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

query {
  orderViewConnection(
    first: 100
  ) {
    edges {
      node {
        orderUrl    # Use this value in the filter
        orderId
      }
    }
  }
}

Usage Example:

query {
  orderViewConnection(
    first: 10
    orderUrl: ["ORDER_URL_VALUE"]
  ) {
    edges {
      node {
        orderId
        order {
          orderId
        }
      }
    }
  }
}

origin

Label: Origin
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    origin: "US"
  ) {
    edges {
      node {
        orderId
        origin
      }
    }
  }
}

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: "uiSalesOrder") {
    dataSets(name: "order") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

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

product

Label: Product
Type: List|ProductUrlString
Enabled: Yes

Filter Type: Reference to product collection

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

query {
  productViewConnection(
    first: 100
  ) {
    edges {
      node {
        productUrl    # Use this value in the filter
        title
      }
    }
  }
}

Usage Example:

query {
  orderViewConnection(
    first: 10
    product: ["PRODUCT_URL_VALUE"]
  ) {
    edges {
      node {
        orderId
        product {
          title
        }
      }
    }
  }
}

productCategory

Label: Category
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    productCategory: "Electronics"
  ) {
    edges {
      node {
        orderId
        productCategory
      }
    }
  }
}

receiveDate

Label: Estimated receive 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 {
  orderViewConnection(
    first: 10
    receiveDate: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        orderId
        receiveDate
      }
    }
  }
}

saleSource

Label: Source
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    saleSource: "Amazon demo"
  ) {
    edges {
      node {
        orderId
        saleSource
      }
    }
  }
}

search

Label: Not specified
Type: SearchString
Enabled: Yes

Filter Type: Search text

This filter performs a text search across multiple fields.

Usage Example:

query {
  orderViewConnection(
    first: 10
    search: "search term"
  ) {
    edges {
      node {
        orderId
      }
    }
  }
}

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 {
  orderViewConnection(
    first: 10
    searchCustom: {
      terms: "red widget"
    }
  ) {
    edges {
      node {
        orderId
      }
    }
  }
}

Example 2: Include additional fields in search:

# Searches defaults PLUS order description and reference fields
query {
  orderViewConnection(
    first: 10
    searchCustom: {
      terms: "acme"
      include: ["orderDescription", "orderReference"]
    }
  ) {
    edges {
      node {
        orderId
      }
    }
  }
}

Example 3: Expand results to include related records:

# For each matching order, also return the customer party record
query {
  orderViewConnection(
    first: 10
    searchCustom: {
      terms: "urgent"
      extend: ["customerPartyUrl"]
    }
  ) {
    edges {
      node {
        orderId
      }
    }
  }
}

Example 4: Combine include and extend:

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

shipDate

Label: Estimated ship 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 {
  orderViewConnection(
    first: 10
    shipDate: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        orderId
        shipDate
      }
    }
  }
}

shipFromCountry

Label: Ship from country
Type: List|String
Enabled: Yes
Options: See Country Codes (ISO 3166-1 alpha-3)

shipFromStateRegion

Label: Ship from state / region
Type: List|String
Enabled: Yes
Options: See State and Region Codes

shipToCountry

Label: Ship to country
Type: List|String
Enabled: Yes
Options: See Country Codes (ISO 3166-1 alpha-3)

shipToStateRegion

Label: Ship to state / region
Type: List|String
Enabled: Yes
Options: See State and Region Codes

shipmentsStatusSummary

Label: Shipments status summary
Type: List|String
Enabled: Yes
Options:
- Fully packed (##packedFull)
- Fully received (##receivedFull)
- Fully shipped (##shippedFull)
- In transit (##shippedNotReceived)
- Not packed or shipped (##nonePackedShipped)
- Not received (##noneReceived)
- Other error (##otherError)
- Packed w/ exceptions (##packedExceptions)
- Partially packed (##packedPartial)
- Partially received (##receivedPartial)
- Partially shipped (##shippedPartial)
- Received w/ exceptions (##receivedExceptions)
- Shipped w/ exceptions (##shippedExceptions)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiSalesOrder") {
    dataSets(name: "order") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  orderViewConnection(
    first: 10
    shipmentsStatusSummary: ["##nonePackedShipped", "##packedPartial"]
  ) {
    edges {
      node {
        orderId
        shipmentsStatusSummary
      }
    }
  }
}

shippingService

Label: Requested shipping
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    shippingService: "USPS First Class"
  ) {
    edges {
      node {
        orderId
        shippingService
      }
    }
  }
}

status

Label: Status
Type: List|String
Enabled: Yes
Options:
- Canceled (ORDER_CANCELLED)
- Committed (ORDER_LOCKED)
- Completed (ORDER_COMPLETED)
- Draft (ORDER_CREATED)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiSalesOrder") {
    dataSets(name: "order") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  orderViewConnection(
    first: 10
    status: ["ORDER_CREATED", "ORDER_LOCKED"]
  ) {
    edges {
      node {
        orderId
        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 {
  orderViewConnection(
    first: 10
    supplier: ["PARTY_URL_VALUE"]
  ) {
    edges {
      node {
        orderId
        party {
          name
        }
      }
    }
  }
}

terms

Label: Terms
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  orderViewConnection(
    first: 10
    terms: "Net 30"
  ) {
    edges {
      node {
        orderId
        terms
      }
    }
  }
}

type

Label: Type
Type: List|String
Enabled: Yes
Options:
- Purchase (PURCHASE_ORDER)
- Sale (SALES_ORDER)
- Transfer (TRANSFER_ORDER)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiSalesOrder") {
    dataSets(name: "order") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  orderViewConnection(
    first: 10
    type: ["PURCHASE_ORDER", "SALES_ORDER"]
  ) {
    edges {
      node {
        orderId
        type
      }
    }
  }
}