Shipment

Overview

Shipments record the physical movement of goods and update inventory levels. Unlike orders which represent plans, shipments represent actual execution - goods leaving, arriving, or moving between your facilities. Every shipment creates permanent stock history entries that form the audit trail of inventory movements.

Sale shipments track goods leaving your warehouse to customers. The workflow involves first packing the shipment - scanning products to verify and reserve them - then shipping it by recording the carrier and tracking number. When packed, inventory moves from "on hand" to "packed" status, reserving it for that specific shipment. When shipped, inventory is removed from the warehouse entirely. This two-stage process gives you control and accuracy, preventing accidental shipment of wrong products.

Purchase shipments record goods arriving from suppliers. When you receive a shipment, products are verified and added to warehouse inventory at a specific cost. This updates both stock levels and inventory valuation. The receiving process can reference a purchase order to validate what was expected versus what actually arrived, flagging discrepancies for review.

Transfer shipments move inventory between your own facilities. They have a two-part workflow: first shipping from the origin location (moving stock to "in transit" status), then receiving at the destination (moving stock from "in transit" to the destination warehouse). This in-transit tracking ensures you always know where your inventory is, even when it's on a truck between warehouses.

Return shipments handle goods coming back from customers. They add inventory back to your warehouse, creating stock history entries that reverse the original sale. Returns can reference the original sale shipment, linking the reverse transaction to the initial sale for accurate financial and inventory tracking.

Shipments capture detailed information beyond just products and quantities. They record carrier information, tracking numbers, package dimensions and weights, and dates for each stage of the process. Line items can specify lot IDs for lot-tracked products and specific sublocations within a warehouse, giving you bin-level inventory accuracy. The GraphQL API provides calculated fields showing total units, total costs, and consolidation status for financial reporting.

GraphQL API

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

Query Name: shipmentViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
19 filter options
9 sortable fields
16 relations to other collections

Query Examples

Basic Query

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

query {
  shipmentViewConnection(first: 10) {
    edges {
      node {
        cancelTransactionTimestamp
        cbmSubtotal
        consolidationStatus
        countPackages
        nativeNeqSubtotal
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

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

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

Filtering

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

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

Sorting

Sort results by one or more fields:

query {
  shipmentViewConnection(
    first: 10
    sort: [{ field: "packDate", mode: "desc" }]
  ) {
    edges {
      node {
        shipmentId
        packDate
      }
    }
  }
}

Relations

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

query {
  shipmentViewConnection(first: 10) {
    edges {
      node {
        shipmentId
        cancelTransactionUser {
          name
          userLoginUrl
        }
      }
    }
  }
}

Summary and Aggregation

This collection supports metrics aggregation through the summary field. You can calculate totals, averages, counts, and other aggregate values across filtered data.

Note: This collection does not support groupBy dimensions. For dimensional analysis, use collections like product, order, or invoice.

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

Query Structure

shipmentViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 2 metrics that can be aggregated:

Metric	Parameters	Description
`totalUnits`	`transform`, `operator`, `productUrlList`	Total number of units
`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

Examples

Example 1: Total shipment Metrics

Calculate aggregate metrics across all shipment records:

query {
  shipmentViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      metrics {
        totalCount: count
      }
    }
  }
}

Expected result structure:

{
  "data": {
    "shipmentViewConnection": {
      "summary": {
        "errorCode": null,
        "errorMessage": null,
        "metrics": {
          "totalCount": [1523]
        }
      }
    }
  }
}

Fields

This collection has 40 fields:

36 simple fields
3 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.

`cancelTransactionTimestamp`

The timestamp when a shipment cancellation transaction was processed. This field records the exact date and time when the shipment was cancelled in the system, providing an audit trail for shipment cancellations.

Label: Cancel transaction timestamp
Sortable: No

`cbmSubtotal`

The total cubic meters (CBM) volume for all items in the shipment. This measurement represents the sum of the volumetric space occupied by the shipment contents, which is commonly used in freight and logistics for calculating shipping costs and space requirements.

Label: CBM subtotal
Sortable: No

`countPackages`

The number of boxes or packages included in a shipment. This field is used to display shipping information on shipment status screens, showing phrases like "1 box" or "3 boxes" when the shipment is in packed or shipped status. The field accepts numeric values and is displayed alongside shipment dates and other logistics information to give users a quick overview of the physical packaging details.

Label: Count packages
Sortable: No

`nativeNeqSubtotal`

The total net explosive quantity (NEQ) for all items in the shipment, expressed in the company's native unit of measure. Net explosive quantity represents the mass of explosive material contained in hazardous products, which is important for regulatory compliance and shipping documentation for dangerous goods. This field aggregates the NEQ values across all shipment items.

Label: Native NEQ subtotal
Sortable: No

`nativeWeightSubtotal`

The total weight of all items in the shipment, calculated in the system's native weight units. This subtotal aggregates the weight values from all shipment items included in the shipment. When a shipment has no items or doesn't exist, the field returns null. The value is typically displayed with two decimal places for precision in weight tracking and shipping calculations.

Label: Native Weight subtotal
Sortable: No

`packDate`

The date and time when the shipment was packed. This field is populated when a shipment reaches the SHIPMENT_PACKED status and is displayed in the shipment's status summary to show when the packing activity was completed.

Label: Pack date
Sortable: Yes

`packLastSublocationDate`

The date when the last sublocation was recorded during the packing process of the shipment. This field tracks the most recent sublocation assignment as items are packed, providing visibility into where items were located within a warehouse or facility at the time of packing. It works in conjunction with the pack last sublocation transaction timestamp and user fields to provide a complete audit trail of sublocation information during shipment packing operations.

Label: Pack last sublocation date
Sortable: No

`packLastSublocationTransactionTimestamp`

The timestamp when the most recent sublocation inventory transaction occurred during the packing process for this shipment. When packing a shipment involves moving inventory from a specific sublocation within a warehouse, this field records the exact time that last sublocation-based inventory movement was processed. This helps track when inventory was last pulled from a specific warehouse location as part of fulfilling the shipment.

Label: Pack last sublocation transaction timestamp
Sortable: No

`packTransactionTimestamp`

The date and time when the shipment was packed. This timestamp records when the packing operation was completed for the shipment, marking a key milestone in the fulfillment process between order creation and shipping.

Label: Pack transaction timestamp
Sortable: No

`privateNotes`

Internal notes or comments about the shipment that are intended for private use within the organization. These notes are not meant to be shared with customers or external parties, unlike public notes which may appear on shipping documents. Users can enter free-form text to record important information about the shipment such as special handling instructions, internal routing details, or other operational notes that staff need to reference when processing or fulfilling the shipment.

Label: Internal notes
Sortable: No

`publicNotes`

Notes about the shipment that are visible to external parties such as customers or suppliers. Unlike internal notes, public notes may appear on customer-facing documents or be shared outside the organization. Users can add free-form text to provide shipping instructions, delivery details, or other information that should be communicated externally.

Label: Public notes
Sortable: No

`receiveDate`

The date when the shipment was received. This field combines both the actual receive date and the estimated receive date into a single value for reporting and filtering purposes. When a shipment has been received, this shows the actual receive date; when a shipment has not yet been received, this shows the estimated receive date. This consolidated field allows users to view, filter, and group shipments by their receive timing regardless of whether the shipment has been delivered or is still pending.

Label: Receive date
Sortable: No

`receiveDateActual`

The actual date when the shipment was received. This field records when goods physically arrived at their destination, as opposed to the estimated receive date. The field is populated when a shipment's status changes to "Received" and a receive transaction is completed. It remains empty for shipments that have not yet been received.

Label: Receive date actual
Sortable: Yes

`receiveDateEstimated`

The anticipated date when a shipment is expected to arrive at its destination. This field is used for planning and tracking purposes before the actual arrival occurs, helping businesses forecast inventory arrival and manage customer expectations. Once the shipment is actually received, the actual arrival date is recorded in the receiveDate field.

Label: Receive date estimated
Sortable: Yes

`receiveTransactionTimestamp`

The timestamp when the shipment was received. This records the date and time when the receiving transaction was completed, marking when the goods physically arrived and were accepted into inventory. This is distinct from the estimated or actual receive date fields, as it captures the exact moment the receive transaction was processed in the system. The timestamp is associated with the user who performed the receive transaction.

Label: Receive transaction timestamp
Sortable: No

`recordCreated`

The date and time when the shipment record was first created in the system. This field displays the creation timestamp in a formatted date-time format and can be used to track when shipments were originally entered. The field may be null for older records that were created before this tracking was implemented.

Label: Record created
Sortable: No

`recordLastUpdated`

The date and time when the shipment record was last modified, displayed in a user-friendly format. This field shows when any changes were made to the shipment, such as status updates, item modifications, or other edits to the shipment data. The timestamp is formatted for easy reading rather than as a raw ISO date string.

Label: Record last updated
Sortable: No

`shipDate`

The actual date when the shipment was sent or departed. This field is populated with the confirmed ship date once the shipment has been dispatched, distinguishing it from the estimated ship date which represents the planned departure date. Users update this field to record when goods physically left the origin facility, and it is used for tracking shipment progress and calculating delivery timelines.

Label: Ship date
Sortable: No

`shipDateActual`

The actual date when the shipment was shipped. This field distinguishes from the estimated ship date by recording when the shipment actually left the origin location. When a shipment has not yet been shipped, this field remains empty. Once goods physically leave the facility, this date is populated to track the actual shipping timeline versus the originally estimated date.

Label: Ship date actual
Sortable: Yes

`shipDateEstimated`

The anticipated date when the shipment is expected to leave the originating location. This represents the planned or projected ship date, as opposed to the actual ship date when the shipment physically departs. Users can set this field to communicate expected timelines for outbound shipments, which is particularly useful for planning and coordination purposes before the shipment actually ships.

Label: Ship date estimated
Sortable: Yes

`shipmentId`

The unique identifier for the shipment record. This is the primary ID used internally by the system to reference shipments, and is typically displayed to users as the Shipment ID. The field supports identifiers up to 60 characters and must not be empty. Examples from the system include simple numeric IDs like "300" or "301", as well as order-based formats like "891-2" or "892-1" which indicate the shipment is associated with a specific order and may be sequentially numbered.

Label: Shipment ID
Sortable: Yes
Default Formatter: html

Example Query:

{
  shipment(shipmentUrl: "example-url") {
    shipmentId    # Uses default formatter: html
    shipmentIdRaw: shipmentId(formatter: "none")  # Get raw value
  }
}

`shipmentUrl`

The unique identifier that provides access to a specific shipment record. This field is automatically generated by the server and serves as the primary identifier for retrieving, updating, and referencing shipment information throughout the system. It is used to look up shipment records, check authorization for shipment operations, and establish relationships between shipments and related entities like orders and returns. Orders maintain lists of associated shipment URLs, and returns can reference shipments through their shipmentUrlList fields.

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: Shipment Url
Sortable: No

`shipTransactionTimestamp`

The timestamp when the shipment was marked as shipped. This field captures the date and time when the shipment status changed to 'Shipped', recording when the goods actually left the origin facility. The timestamp is derived from the shipment's status history when the status transitions to SHIPMENT_SHIPPED. This field is displayed in a formatted date-time format (e.g., "Jun 14 2014 5:51:56 am") and remains null until the shipment is actually shipped.

Label: Ship transaction timestamp
Sortable: No

`statusExtended`

An extended or more detailed representation of the shipment's status. This field provides additional status information beyond the primary status field, offering users a more descriptive view of where the shipment stands in its lifecycle. The field is display-only and cannot be used for sorting in reports or queries.

Label: Status extended
Sortable: No

`subtotal`

The total monetary value of all items in the shipment before any adjustments, fees, or taxes are applied. This represents the sum of the individual line item amounts (quantity times unit price) for all products included in the shipment. Users would reference this field to see the base value of goods being shipped before additional charges or discounts modify the final total.

Label: Subtotal
Sortable: No

`title`

A human-readable label that identifies the shipment by combining its type and user-facing ID. The format is "[Type] shipment [ID]" where the type describes the shipment category such as Transfer, Return, Sale, or Purchase, and the ID is the user-assigned shipment identifier. For example, "Sale shipment 892-1" or "Transfer shipment 301". This field is used throughout the system for display purposes, making it easy for users to quickly identify and distinguish between different shipments in lists, reports, and navigation breadcrumbs.

Label: Title
Sortable: No

`totalAllocatedAdjustments`

The total monetary value of all allocated adjustments across all items in the shipment. This field represents the sum of adjustments that have been allocated to individual shipment items, providing an aggregate view of adjustment costs at the shipment level. This value is typically used in financial reporting and cost analysis alongside other totals like allocated miscellaneous charges and income after adjustments.

Label: Total allocated adjustments
Sortable: No

`totalAllocatedMiscellaneous`

The total amount of miscellaneous costs that have been allocated to this shipment. This is a calculated field that aggregates various miscellaneous charges or expenses associated with the shipment. The field is displayed as a right-aligned monetary value.

Label: Total allocated miscellaneous
Sortable: No

`totalAverageCost`

The total cost of goods sold (COGS) for the shipment, calculated using average cost valuation. This represents an estimated total cost when the shipment record is created, based on the average cost of items in the shipment at that time. For actual landed cost after all shipment-related expenses are applied, see totalLandedCost.

Label: Total COGS
Sortable: No

`totalIncomeAfterAdjustments`

The total revenue amount for the shipment after applying all adjustments, calculated by summing the income after adjustments for each item in the shipment. This represents the shipment's subtotal plus any adjustments (such as discounts or fees) that have been allocated to the shipment items. This field is used for financial reporting and analysis to understand the actual income generated from a shipment after all price modifications have been applied.

Label: Total income after adjustments
Sortable: No

`totalLandedCost`

The total landed cost for a purchase shipment, which represents the sum of all costs associated with getting the goods to their destination. This includes the subtotal of items plus any allocated adjustments such as freight, duties, and other miscellaneous charges. This value helps businesses understand the true total cost of acquiring inventory through a purchase shipment.

Label: Total landed cost
Sortable: No

`totalStandardAccountingCost`

The total value of all items in the shipment calculated using standard accounting cost. This cost field represents a specific accounting method valuation for the shipment's contents, distinct from average cost or landed cost calculations. The field is displayed with two decimal places in currency format. It appears alongside other shipment cost totals such as total average cost, total landed cost, and total transfer value in reporting and analysis interfaces.

Label: Total standard accounting cost
Sortable: No

`totalTransferValue`

The total transfer value for the shipment, representing the cumulative value of inventory being transferred. This field is displayed alongside other shipment cost totals such as total landed cost, total average cost, and total standard accounting cost. The field is used to track the monetary value of goods being moved in transfer-type shipments.

Label: Total transfer value
Sortable: No

`trackingCode`

The tracking number provided by the shipping carrier for a shipment, used to track the package's delivery status and location. This code is typically assigned by carriers like FedEx, UPS, or USPS when a shipment is created, and customers can use it to monitor their package in transit. The field may be null for shipments that haven't been assigned a tracking number yet, such as those still being prepared or shipments that don't require tracking.

Label: Tracking code
Sortable: Yes

`unpackTransactionTimestamp`

The transaction timestamp when the shipment was unpacked. This represents the system timestamp when the unpack action was executed, recording when the shipment's status was changed to unpacked in the database. For sales shipments, unpacking reverses the packed status and returns the shipment to an earlier state in the fulfillment workflow.

Label: Unpack transaction timestamp
Sortable: No

`weightSubtotal`

The total weight of all items in the shipment. This field aggregates the weight across all products and quantities included in the shipment, providing a cumulative weight measurement for the entire shipment transaction.

Label: Weight subtotal
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

`consolidationStatus`

Indicates whether the shipment has been consolidated for accounting and reporting purposes. This field has two possible values: Pending (the shipment has not yet been consolidated) or Consolidated (the shipment has been consolidated). This status is used to track which shipments have been processed and finalized for financial reporting and is commonly used as a filter when generating reports and analyzing shipment data.

Label: Consolidation status
Sortable: No

Possible Values:

##consolidationStatusExcluded - Excluded
##consolidationStatusPending - Pending
##consolidationStatusConsolidated - Consolidated
##consolidationStatusConsolidation - Consolidation

`status`

The current lifecycle stage of the shipment. This field tracks whether a shipment is in initial entry, has been packed, has been shipped, has been delivered/received, or has been cancelled. The status determines which operations can be performed on the shipment and affects inventory calculations. Common status values include input for newly created shipments, packed when items are ready to ship, shipped when the shipment is in transit, delivered/received when items arrive at their destination, and cancelled for shipments that were voided.

Label: Status
Sortable: No

Possible Values:

SHIPMENT_INPUT - Editable
SHIPMENT_DELIVERED - Received
SHIPMENT_PACKED - Packed
SHIPMENT_UNPACKED - Unpacked
SHIPMENT_SHIPPED - Shipped
SHIPMENT_CANCELLED - Canceled

`type`

The category of shipment that determines the direction and purpose of the inventory movement. The three main types are SALES_SHIPMENT for outbound shipments to customers, PURCHASE_SHIPMENT for inbound shipments from vendors, and TRANSFER for moving inventory between facilities. An additional type, SALES_RETURN, is used when customers return products. The type controls business logic such as which facilities are involved and how inventory is adjusted.

Label: Type
Sortable: No

Possible Values:

PURCHASE_SHIPMENT - Purchase
TRANSFER - Transfer
SALES_SHIPMENT - Sale
SALES_RETURN - Return

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 shipment, calculated by multiplying each line item's quantity by its product's units per case and summing the results. This field provides the aggregate unit count for the entire shipment, accounting for products that are packed in cases or multi-unit packages. For example, if a shipment contains 2 cases of a product with 12 units per case and 5 cases of another product with 6 units per case, the totalUnits would be 54. This field can be filtered to show totals for specific products only.

Label: Total units
Sortable: No

Parameters:

productUrlList (List|ProductUrlString) Product(s)

Example Query:

{
  shipment(shipmentUrl: "example-url") {
    totalUnits(
      productUrlList: ["example-value"]
    )
  }
}