Journal Entry

Overview

Journal Entries are manual accounting entries that directly update the General Ledger without corresponding to physical transactions. They're used for adjustments, corrections, period-end accruals, and other accounting operations that don't flow from normal business transactions like shipments or invoices.

The primary use case is accounting adjustments. If you discover an error in a previous entry, a journal entry can correct it. If you need to accrue expenses at month-end that haven't been invoiced yet, a journal entry records the accrual. If you need to reclassify amounts from one account to another, a journal entry makes the move. These manual entries give your accounting team the flexibility to keep books accurate despite the complexities of real-world business.

Each journal entry contains multiple line items - typically at least two, since debits must equal credits. Each line specifies a GL account, whether it's a debit or credit, and the amount. The entry as a whole has a date (when it applies) and a description (explaining what it's for). This structure follows standard double-entry accounting and ensures the books stay balanced.

Consolidation journal entries are a special type created automatically by the system. When multiple shipments or invoices are consolidated, the system creates a consolidation journal entry that aggregates their GL impact into a single entry. This reduces GL clutter while preserving transaction detail. Consolidation entries are marked with a special type so they can be identified and excluded from certain reports.

Journal entries support period-end accounting processes. At the end of a month or year, you might need to record depreciation, accrue unbilled revenue, adjust prepaid expenses, or make other timing adjustments. Journal entries handle these non-transactional accounting needs, ensuring your financial statements accurately reflect your financial position even when the timing of business transactions doesn't perfectly align with accounting periods.

The workflow for journal entries typically involves creating them in a draft state, reviewing them for accuracy, and then posting them to make them permanent. Once posted, they create the actual GL entries and become locked. If a posted journal entry needs to be corrected, you can't edit it - you must void it (creating reversing entries) and create a new correct entry, maintaining a complete audit trail.

GraphQL API

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

Query Name: journalEntryViewConnection

Available Features:

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

Query Examples

Basic Query

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

query {
  journalEntryViewConnection(first: 10) {
    edges {
      node {
        consolidationCustomer
        consolidationDescription
        consolidationPeriod
        consolidationSaleSource
        date
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

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

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

Filtering

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

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

Sorting

Sort results by one or more fields:

query {
  journalEntryViewConnection(
    first: 10
    sort: [{ field: "consolidationCustomer", mode: "desc" }]
  ) {
    edges {
      node {
        journalEntryId
        consolidationCustomer
      }
    }
  }
}

Relations

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

query {
  journalEntryViewConnection(first: 10) {
    edges {
      node {
        journalEntryId
        creditAccount {
          name
          glAccountUrl
        }
      }
    }
  }
}

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

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

Available Metrics

This collection provides 25 metrics that can be aggregated:

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:

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

Examples

Example 1: Basic Aggregation

Calculate metrics for journalEntry:

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

Fields

This collection has 14 fields:

• 10 simple fields
• 4 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.

consolidationCustomer

The customer party associated with a consolidated transaction journal entry. Retrieved from the consolidatedTransactionDescriptorList by looking up the consolidationPartyUrl and validating the party has a CUSTOMER role type.

Label: Consolidation customer
Sortable: Yes
Default Formatter: html

Example Query:

{
  journalEntry(journalEntryUrl: "example-url") {
    consolidationCustomer    # Uses default formatter: html
    consolidationCustomerRaw: consolidationCustomer(formatter: "none")  # Get raw value
  }
}

consolidationDescription

A formatted description of consolidated transactions. Provides a human-readable summary of the consolidation details for a journal entry.

Label: Consolidation description
Sortable: Yes

consolidationSaleSource

The sales channel or source for consolidated sales transactions (e.g., Shopify, Amazon). Derived from the saleSourceId attribute in the consolidatedTransactionDescriptorList and matched against sales order type options.

Label: Consolidation sale source
Sortable: Yes

date

The transaction date of the journal entry. Used for filtering and sorting journal entries chronologically.

Label: Effective date
Sortable: Yes

journalEntryId

The unique identifier for the journal entry. Displayed as a clickable link to the journal entry detail page and used for lookups and imports.

Label: Journal entry ID
Sortable: Yes
Default Formatter: html

Example Query:

{
  journalEntry(journalEntryUrl: "example-url") {
    journalEntryId    # Uses default formatter: html
    journalEntryIdRaw: journalEntryId(formatter: "none")  # Get raw value
  }
}

journalEntryUrl

The unique identifier for the journal entry resource. This field is automatically generated by the server and used as the primary key for lookups and relationships within the system.

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: Journal entry Url
Sortable: Yes

notes

Label: Notes
Sortable: Yes

recordCreated

Label: Record created
Sortable: Yes

recordLastUpdated

Label: Record last updated
Sortable: Yes

totalAmount

Label: Total amount
Sortable: Yes

Enum Fields

These fields return one of a predefined set of values.

averageCostChangeWarning

Warning indicator for journal entries where the expected average cost does not match the resulting average cost. Displays as an icon with tooltip showing "Expected/resulting cost mismatch" when present.

Label: Warning
Type: ##iconWithTooltip
Sortable: No

Possible Values:

• ##avgCostChangeWarningCostMismatch - Expected/resulting cost mismatch

consolidationPeriod

The time period used for consolidating transactions, such as weekly or monthly. Extracted from the consolidatedTransactionDescriptorList attribute named 'consolidationPeriod'.

Label: Consolidation period
Sortable: Yes

Possible Values:

• ##consolidationPeriodDaily - Daily
• ##consolidationPeriodWeekly - Weekly
• ##consolidationPeriodMonthly - Monthly

status

The current workflow state of the journal entry. Journal entries follow a three-state lifecycle: Created (draft), Completed (posted), and Cancelled.

When a journal entry is first created, it defaults to the Created status, which represents a draft state. In this status, the journal entry is fully editable and can be modified freely. Journal entries in Created status can be transitioned to Completed or Cancelled.

The Completed status indicates the journal entry has been posted and finalized. When a journal entry is marked as Completed, it affects accounting calculations such as average cost changes and general ledger balances. Completed journal entries are not editable, with one exception: a Completed journal entry can be changed to Cancelled status only - no other modifications are allowed.

The Cancelled status indicates the journal entry has been voided and will not affect accounting calculations. Once cancelled, a journal entry cannot be uncancelled or modified in any way. Cancelled journal entries retain their data for historical purposes but are excluded from financial calculations.

For average cost change journal entries specifically, the status determines which cost values are used: Created status shows draft/expected costs, while Completed status shows the actual costs at the time the entry was completed. Cancelled entries revert to showing costs as if the entry had never been applied.

Label: Status
Sortable: Yes

Possible Values:

• JOURNAL_CREATED - Draft
• JOURNAL_COMPLETED - Posted
• JOURNAL_CANCELLED - Canceled

type

Label: Type
Sortable: Yes

Possible Values:

• JOURNAL_ENTRY - Journal entry
• AVERAGE_COST_CHANGE - Average cost change

Relations

creditAccount

• Related Collection: generalLedgerAccount
• Label: Credit account

TODO: Add relation description

debitAccount

• Related Collection: generalLedgerAccount
• Label: Debit account

TODO: Add relation description

connectionRelation

• Related Collection: connectionRelation
• Label: Integration

TODO: Add relation description

recordCreatedUser

• Related Collection: userLogin
• Label: Record created user

TODO: Add relation description

recordLastUpdatedUser

• Related Collection: userLogin
• Label: Record last updated user

TODO: Add relation description

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 {
  journalEntryViewConnection(
    first: 10
    connectionRelationErrorDates: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        journalEntryId
        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: "uiJournalEntry") {
    dataSets(name: "journalEntry") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

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

consolidationEquivalenceClass

• Label: Consolidation equivalence class
• Type: List|String
• Enabled: Yes
• Options:
  • Sales COGS (##eqvClassSalesCogs)
  • Sales income (##eqvClassSalesIncome)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiJournalEntry") {
    dataSets(name: "journalEntry") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  journalEntryViewConnection(
    first: 10
    consolidationEquivalenceClass: ["##eqvClassSalesCogs", "##eqvClassSalesIncome"]
  ) {
    edges {
      node {
        journalEntryId
        consolidationEquivalenceClass
      }
    }
  }
}

consolidationSaleSource

• Label: Consolidation sale source
• Type: List|String
• Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  journalEntryViewConnection(
    first: 10
    consolidationSaleSource: "Amazon demo"
  ) {
    edges {
      node {
        journalEntryId
        consolidationSaleSource
      }
    }
  }
}

date

• Label: Effective 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 {
  journalEntryViewConnection(
    first: 10
    date: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        journalEntryId
        date
      }
    }
  }
}

journalEntryId

• Label: Journal entry ID
• Type: List|String
• Enabled: No

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  journalEntryViewConnection(
    first: 10
    journalEntryId: "12"
  ) {
    edges {
      node {
        journalEntryId
        journalEntryId
      }
    }
  }
}

journalEntryUrl

• Label: Journal entry
• Type: List|JournalEntryUrlString
• Enabled: Yes

Filter Type: Reference to journalEntry collection

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

query {
  journalEntryViewConnection(
    first: 100
  ) {
    edges {
      node {
        journalEntryUrl    # Use this value in the filter
        journalEntryId
      }
    }
  }
}

Usage Example:

query {
  journalEntryViewConnection(
    first: 10
    journalEntryUrl: ["JOURNALENTRY_URL_VALUE"]
  ) {
    edges {
      node {
        journalEntryId
        journalEntry {
          journalEntryId
        }
      }
    }
  }
}

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 {
  journalEntryViewConnection(
    first: 10
    product: ["PRODUCT_URL_VALUE"]
  ) {
    edges {
      node {
        journalEntryId
        product {
          title
        }
      }
    }
  }
}

recordCreated

• Label: 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 {
  journalEntryViewConnection(
    first: 10
    recordCreated: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        journalEntryId
        recordCreated
      }
    }
  }
}

recordLastUpdated

• Label: 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 {
  journalEntryViewConnection(
    first: 10
    recordLastUpdated: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        journalEntryId
        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 {
  journalEntryViewConnection(
    first: 10
    search: "search term"
  ) {
    edges {
      node {
        journalEntryId
      }
    }
  }
}

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

Example 2: Include additional fields in search:

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

Example 3: Expand results to include related records:

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

Example 4: Combine include and extend:

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

status

• Label: Status
• Type: List|String
• Enabled: Yes
• Options:
  • Canceled (JOURNAL_CANCELLED)
  • Draft (JOURNAL_CREATED)
  • Posted (JOURNAL_COMPLETED)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiJournalEntry") {
    dataSets(name: "journalEntry") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  journalEntryViewConnection(
    first: 10
    status: ["JOURNAL_CREATED", "JOURNAL_COMPLETED"]
  ) {
    edges {
      node {
        journalEntryId
        status
      }
    }
  }
}

type

• Label: Type
• Type: List|String
• Enabled: Yes
• Options:
  • Average cost change (AVERAGE_COST_CHANGE)
  • Journal entry (JOURNAL_ENTRY)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiJournalEntry") {
    dataSets(name: "journalEntry") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  journalEntryViewConnection(
    first: 10
    type: ["JOURNAL_ENTRY", "AVERAGE_COST_CHANGE"]
  ) {
    edges {
      node {
        journalEntryId
        type
      }
    }
  }
}