Facility

Overview

Facilities represent the physical and logical locations where inventory is stored or moved. They provide the structure for tracking where products are located, supporting everything from basic warehouse operations to multi-location inventory management. The system distinguishes between locations (warehouse-level) and sublocations (areas within warehouses).

Locations represent physical warehouses, stores, or storage sites. Each location is a separate physical space where inventory is held. Multi-location businesses use this to track inventory across different geographic sites - a distribution center in California, another in New York, a retail store in Texas. Each location's inventory is tracked separately, letting you see what's available at each site for fulfillment or transfer planning.

Sublocations represent specific areas within a location. These might be aisles, bins, shelves, or zones within a warehouse. By tracking inventory at the sublocation level, you achieve bin-level accuracy that supports efficient picking and putaway. Workers can be directed to exact bins, reducing search time and errors. Cycle counting can target specific sublocations, improving inventory accuracy without full warehouse counts.

The facility hierarchy is typically two levels - locations containing sublocations. A location might have dozens or hundreds of sublocations depending on warehouse size and complexity. This structure balances detailed tracking with manageable complexity. You can report at the location level for high-level visibility or at the sublocation level for operational precision.

Transit sublocations are special system-created areas representing goods in transit. When inventory is shipped from one location to another, it moves to a transit sublocation until it's received. This ensures inventory is always accounted for - it's never "lost" between locations. Transit tracking is automatic and provides visibility into in-transit stock for accurate available-to-promise calculations.

Facility status controls whether a location can be used. Active facilities accept new inventory transactions. Inactive facilities are retained for historical reporting but can't be used for new shipments or stock. This lets you phase out closed warehouses without losing historical data.

The control type indicates what kind of inventory tracking applies. Some facilities might track lot numbers, others serial numbers, others just quantities. This facility-level control supports different operational models in different parts of your business - tight serialized control in one location, simpler quantity tracking in another.

GraphQL API

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

Query Name: facilityViewConnection

Available Features:

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

Query Examples

Basic Query

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

query {
  facilityViewConnection(first: 10) {
    edges {
      node {
        controlTypeId
        facilityUrl
        name
        parentFacilityUrl
        status
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

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

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

Filtering

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

query {
  facilityViewConnection(
    first: 10
    controlTypeId: "FACILITY_USER"
  ) {
    edges {
      node { controlTypeId }
    }
  }
}

Sorting

Sort results by one or more fields:

query {
  facilityViewConnection(
    first: 10
    sort: [{ field: "name", mode: "desc" }]
  ) {
    edges {
      node {
        controlTypeId
        name
      }
    }
  }
}

Relations

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

query {
  facilityViewConnection(first: 10) {
    edges {
      node {
        controlTypeId
        location {
          name
          facilityUrl
        }
      }
    }
  }
}

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

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

Available Metrics

This collection provides 1 metric that can be aggregated:

Metric	Parameters	Description
`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 facility Metrics

Calculate aggregate metrics across all facility records:

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

Expected result structure:

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

Fields

This collection has 6 fields:

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

`facilityUrl`

The unique identifier for the facility. This field serves as the primary key for facilities and is used throughout the system to reference both locations (top-level facilities) and sublocations (facilities with a parent). The facilityUrl is read-only and automatically generated by the server when a facility is created.

This identifier is used extensively in inventory operations to track where stock is located, in shipments to specify source and destination facilities, in orders to designate fulfillment locations, and in reorder guidelines to set location-specific inventory policies. When filtering or grouping inventory data, facilityUrl enables precise tracking of stock quantities, reservations, and transfers across different warehouse locations and their sublocations.

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

`name`

The unique identifier and display name for a facility (location or sublocation). This field is required and must be unique across all facilities in the system. It serves as both the primary way to identify facilities in the user interface and as the lookup key when importing or referencing facilities throughout the system.

The name can contain any characters and is limited to 100 characters. During import operations, the name is used to match existing facilities for updates or to create new facilities. When renaming a facility, a separate "New Sublocation" field is used to specify the new name while using the current name to identify which facility to update.

Examples from test data include location names like "Hdqtrs", "South Annex", and "North Facility" for top-level locations, and shorter identifiers like "H0", "S0", "Basement", "Attic", and "Closet" for sublocations.

Label: Name
Sortable: Yes

`parentFacilityUrl`

References the parent facility for sublocations in a hierarchical facility structure. This field establishes the location/sublocation relationship where facilities can be organized into a two-level hierarchy: top-level locations (which have a null parentFacilityUrl) and sublocations (which reference their parent location via this field).

When this field is null, the facility is considered a location. When it references another facility's URL, the current facility is a sublocation belonging to that parent location. This distinction is used throughout the system to determine facility type (FACILITY_LOCATION vs FACILITY_SUBLOCATION) and affects which operations are allowed - for example, sublocations cannot have addresses (those belong to the parent location), and certain facility attributes like shipping/receiving settings can only be configured on locations, not sublocations.

The field is validated during import to prevent converting existing facilities between location and sublocation types, and is used in inventory tracking to determine the actual location of stock (inventory in a sublocation is considered to be at its parent location).

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: Parent facility url
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

`controlTypeId`

Distinguishes between user-managed facilities and system-managed facilities. The field has two possible values: "User" (FACILITY_USER) or "System" (FACILITY_SYSTEM). User facilities are standard facilities created and managed by users for normal inventory operations. System facilities are special-purpose facilities managed by the system, typically used for integrations or automated processes. By default, most facility queries and lists filter out system facilities, showing only user facilities unless specifically requested. When the field is null or not specified, it defaults to "User".

Label: Control type
Sortable: No

Possible Values:

FACILITY_USER - User
FACILITY_SYSTEM - System

`status`

Indicates whether a facility (location or sublocation) is active or inactive. Active facilities are available for normal operations including inventory transactions, order fulfillment, and product location management. Inactive facilities are excluded from operational workflows - they cannot be edited (except to reactivate them), do not appear in location selection filters for reorder screens and product locations, and are hidden from most facility listings. The status defaults to Active when facilities are created. Facilities can be marked inactive to preserve historical data while preventing their use in new transactions. In the import system, inactive facilities cannot be modified unless explicitly being reactivated to Active status. The status field is used throughout the system to filter facilities, determine editability, and control which facilities appear in dropdown options for location selection.

Label: Status
Sortable: No

Possible Values:

FACILITY_ACTIVE - Active
FACILITY_INACTIVE - Inactive

`type`

Indicates whether the facility is a top-level location or a sublocation within a location. A facility is classified as "Location" when it has no parent facility, and "Sublocation" when it has a parent facility. This distinction is computed based on the presence of a parentFacilityUrl value rather than being stored directly. Locations represent physical warehouses or buildings and can have address information, while sublocations represent specific areas within a location (such as rooms, aisles, or bins) and cannot have their own addresses. The type affects which operations and settings are available for the facility, such as whether it can be used for sale shipping, purchase receiving, return receiving, or build sourcing.

Label: Type
Sortable: No

Possible Values:

FACILITY_LOCATION - Location
FACILITY_SUBLOCATION - Sublocation

Relations

location

Related Collection: facility
Label: Location

TODO: Add relation description

Filters

controlTypeId

Label: Control type
Type: List|FacilityControlTypeString
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  facilityViewConnection(
    first: 10
    controlTypeId: "FACILITY_USER"
  ) {
    edges {
      node {
        name
        controlTypeId
      }
    }
  }
}

facilityUrl

Label: Facility
Type: List|FacilityUrlString
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  facilityViewConnection(
    first: 10
    facilityUrl: "/finaleengineer/api/facility/100000"
  ) {
    edges {
      node {
        name
        facilityUrl
      }
    }
  }
}

parentFacilityUrl

Label: Parent facility
Type: List|FacilityUrlLocationString
Enabled: Yes

Filter Type: Reference to facility collection

Note: Filters to locations only

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

query {
  facilityViewConnection(
    first: 100
    type: "FACILITY_LOCATION"
    status: "FACILITY_ACTIVE"
  ) {
    edges {
      node {
        facilityUrl    # Use this value in the filter
        name
      }
    }
  }
}

Usage Example:

query {
  facilityViewConnection(
    first: 10
    parentFacilityUrl: ["FACILITY_URL_VALUE"]
  ) {
    edges {
      node {
        name
        facility {
          name
        }
      }
    }
  }
}

search

Label: Not specified
Type: SearchString
Enabled: Yes

Filter Type: Search text

This filter performs a text search across multiple fields.

Usage Example:

query {
  facilityViewConnection(
    first: 10
    search: "search term"
  ) {
    edges {
      node {
        name
      }
    }
  }
}

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

Example 2: Include additional fields in search:

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

Example 3: Expand results to include related records:

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

Example 4: Combine include and extend:

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

status

Label: Status
Type: List|FacilityStatusString
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  facilityViewConnection(
    first: 10
    status: "FACILITY_ACTIVE"
  ) {
    edges {
      node {
        name
        status
      }
    }
  }
}

type

Label: Type
Type: List|String
Enabled: Yes
Options:
- Location (FACILITY_LOCATION)
- Sublocation (FACILITY_SUBLOCATION)

Filter Type: Predefined options

Get Current Options:

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

query {
  dataSetMeta(purpose: "uiProduct") {
    dataSets(name: "facility") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  facilityViewConnection(
    first: 10
    type: ["FACILITY_LOCATION", "FACILITY_SUBLOCATION"]
  ) {
    edges {
      node {
        name
        type
      }
    }
  }
}