Shipment

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:

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:

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:

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.

Query Structure

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

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:

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:

Simple Fields

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.

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.

Label: Native NEQ subtotal Sortable: No

nativeWeightSubtotal

The total weight of all items in the shipment, calculated in the system's native weight units.

Label: Native Weight subtotal Sortable: No

packDate

The date and time when the shipment was packed.

Label: Pack date Sortable: Yes

packLastSublocationDate

The date when the last sublocation was recorded during the packing process of the shipment.

Label: Pack last sublocation date Sortable: No

packLastSublocationTransactionTimestamp

The timestamp when the most recent sublocation inventory transaction occurred during the packing process.

Label: Pack last sublocation transaction timestamp Sortable: No

packTransactionTimestamp

The date and time when the shipment was packed.

Label: Pack transaction timestamp Sortable: No

privateNotes

Internal notes or comments about the shipment that are intended for private use within the organization.

Label: Internal notes Sortable: No

publicNotes

Notes about the shipment that are visible to external parties such as customers or suppliers.

Label: Public notes Sortable: No

receiveDate

The date when the shipment was received.

Label: Receive date Sortable: No

receiveDateActual

The actual date when the shipment was received.

Label: Receive date actual Sortable: Yes

receiveDateEstimated

The anticipated date when a shipment is expected to arrive at its destination.

Label: Receive date estimated Sortable: Yes

receiveTransactionTimestamp

The timestamp when the shipment was received.

Label: Receive transaction timestamp Sortable: No

recordCreated

The date and time when the shipment record was first created in the system.

Label: Record created Sortable: No

recordLastUpdated

The date and time when the shipment record was last modified.

Label: Record last updated Sortable: No

shipDate

The actual date when the shipment was sent or departed.

Label: Ship date Sortable: No

shipDateActual

The actual date when the shipment was shipped.

Label: Ship date actual Sortable: Yes

shipDateEstimated

The anticipated date when the shipment is expected to leave the originating location.

Label: Ship date estimated Sortable: Yes

shipmentId

The unique identifier for the shipment record.

Label: Shipment ID Sortable: Yes

shipmentUrl

The unique identifier that provides access to a specific shipment record.

Label: Shipment Url Sortable: No

shipTransactionTimestamp

The timestamp when the shipment was marked as shipped.

Label: Ship transaction timestamp Sortable: No

statusExtended

An extended or more detailed representation of the shipment's status.

Label: Status extended Sortable: No

subtotal

The total monetary value of all items in the shipment before any adjustments, fees, or taxes are applied.

Label: Subtotal Sortable: No

title

A human-readable label that identifies the shipment by combining its type and user-facing ID.

Label: Title Sortable: No

totalAllocatedAdjustments

The total monetary value of all allocated adjustments across all items in the shipment.

Label: Total allocated adjustments Sortable: No

totalAllocatedMiscellaneous

The total amount of miscellaneous costs that have been allocated to this shipment.

Label: Total allocated miscellaneous Sortable: No

totalAverageCost

The total cost of goods sold (COGS) for the shipment, calculated using average cost valuation.

Label: Total COGS Sortable: No

totalIncomeAfterAdjustments

The total revenue amount for the shipment after applying all adjustments.

Label: Total income after adjustments Sortable: No

totalLandedCost

The total landed cost for a purchase shipment.

Label: Total landed cost Sortable: No

totalStandardAccountingCost

The total value of all items in the shipment calculated using standard accounting cost.

Label: Total standard accounting cost Sortable: No

totalTransferValue

The total transfer value for the shipment, representing the cumulative value of inventory being transferred.

Label: Total transfer value Sortable: No

trackingCode

The tracking number provided by the shipping carrier for a shipment.

Label: Tracking code Sortable: Yes

unpackTransactionTimestamp

The transaction timestamp when the shipment was unpacked.

Label: Unpack transaction timestamp Sortable: No

weightSubtotal

The total weight of all items in the shipment.

Label: Weight subtotal Sortable: No

Enum Fields

consolidationStatus

Indicates whether the shipment has been consolidated for accounting and reporting purposes.

Label: Consolidation status Sortable: No Possible Values:

status

The current lifecycle stage of the shipment.

Label: Status Sortable: No Possible Values:

type

The category of shipment that determines the direction and purpose of the inventory movement.

Label: Type Sortable: No Possible Values:

Parameterized Fields

totalUnits

The total number of individual units across all items in the shipment.

Label: Total units Sortable: No Parameters:

Relations

cancelTransactionUser

carrier

destination

connectionRelation

order

origin

packLastSublocationTransactionUser

packTransactionUser

product

receiveTransactionUser

recordCreatedUser

recordLastUpdatedUser

shipFrom

shipTo

shipTransactionUser

unpackTransactionUser

Filters

connectionRelationErrorDates

connectionRelationSyncStatuses

consolidationStatus

destination

orderOrderDate

orderType

orderUrl

origin

packDate

product

receiveDateActual

receiveDateEstimated

search

shipDateActual

shipDateEstimated

shipmentUrl

status

type