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

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

### Pagination

Use cursor-based pagination to retrieve large datasets:

```graphql
# 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:

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

### Sorting

Sort results by one or more fields:

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

### Relations

Query related data:

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

```graphql
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:**
- `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:

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

Expected result structure:

```json
{
  "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)

### 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:**
- `##consolidationStatusExcluded` 
- `##consolidationStatusPending` 
- `##consolidationStatusConsolidated` 
- `##consolidationStatusConsolidation`

#### `status`
The current lifecycle stage of the shipment.

**Label:** Status
**Sortable:** No
**Possible Values:**
- `SHIPMENT_INPUT` 
- `SHIPMENT_DELIVERED` 
- `SHIPMENT_PACKED` 
- `SHIPMENT_UNPACKED` 
- `SHIPMENT_SHIPPED` 
- `SHIPMENT_CANCELLED`

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

**Label:** Type
**Sortable:** No
**Possible Values:**
- `PURCHASE_SHIPMENT` 
- `TRANSFER` 
- `SALES_SHIPMENT` 
- `SALES_RETURN`

### Parameterized Fields
#### `totalUnits`
The total number of individual units across all items in the shipment.

**Label:** Total units
**Sortable:** No
**Parameters:**
- **productUrlList** (List|ProductUrlString)

## Relations
### cancelTransactionUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Cancel transaction user

### carrier
- **Related Collection:** [party](https://developer.finaleinventory.com/reference/graphql-party)
- **Label:** Carrier

### destination
- **Related Collection:** [facility](https://developer.finaleinventory.com/reference/graphql-facility)
- **Label:** Destination

### connectionRelation
- **Related Collection:** [connectionRelation](https://developer.finaleinventory.com/reference/graphql-shipment)
- **Label:** Integration

### order
- **Related Collection:** [order](https://developer.finaleinventory.com/reference/graphql-shipment)
- **Label:** Order

### origin
- **Related Collection:** [facility](https://developer.finaleinventory.com/reference/graphql-facility)
- **Label:** Origin

### packLastSublocationTransactionUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Pack last sublocation transaction user

### packTransactionUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Pack transaction user

### product
- **Related Collection:** [product](https://developer.finaleinventory.com/reference/graphql-shipment)
- **Label:** Product (consolidated)

### receiveTransactionUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Receive transaction user

### recordCreatedUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Record created user

### recordLastUpdatedUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Record last updated user

### shipFrom
- **Related Collection:** [address](https://developer.finaleinventory.com/reference/graphql-address)
- **Label:** Ship from

### shipTo
- **Related Collection:** [address](https://developer.finaleinventory.com/reference/graphql-address)
- **Label:** Ship to

### shipTransactionUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Ship transaction user

### unpackTransactionUser
- **Related Collection:** [userLogin](https://developer.finaleinventory.com/reference/graphql-user-login)
- **Label:** Unpack transaction user

## Filters
### connectionRelationErrorDates
- **Label:** Latest error date
- **Type:** dateRangeInput
- **Enabled:** Yes

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

### consolidationStatus
- **Label:** Consolidation status
- **Type:** List|String
- **Enabled:** Yes

### destination
- **Label:** Destination
- **Type:** List|FacilityUrlLocationString
- **Enabled:** Yes

### orderOrderDate
- **Label:** Order date
- **Type:** dateRangeInput
- **Enabled:** Yes

### orderType
- **Label:** Type
- **Type:** List|String
- **Enabled:** Yes

### orderUrl
- **Label:** Order
- **Type:** TransferShipmentOrderUrlString
- **Enabled:** Yes

### origin
- **Label:** Origin
- **Type:** List|FacilityUrlLocationString
- **Enabled:** Yes

### packDate
- **Label:** Pack date
- **Type:** dateRangeInput
- **Enabled:** Yes

### product
- **Label:** Product
- **Type:** List|ProductUrlString
- **Enabled:** Yes

### receiveDateActual
- **Label:** Receive date actual
- **Type:** dateRangeWithFutureInput
- **Enabled:** Yes

### receiveDateEstimated
- **Label:** Receive date estimated
- **Type:** dateRangeWithFutureInput
- **Enabled:** Yes

### search
- **Label:** Not specified
- **Type:** SearchString
- **Enabled:** Yes

### shipDateActual
- **Label:** Ship date actual
- **Type:** dateRangeWithFutureInput
- **Enabled:** Yes

### shipDateEstimated
- **Label:** Ship date estimated
- **Type:** dateRangeWithFutureInput
- **Enabled:** Yes

### shipmentUrl
- **Label:** Shipment
- **Type:** List|ShipmentUrlString
- **Enabled:** Yes

### status
- **Label:** Status
- **Type:** List|String
- **Enabled:** Yes

### type
- **Label:** Type
- **Type:** List|String
- **Enabled:** Yes