Request

Response

    Fetch & Process BOM Information

    This tutorial walks through the common ways to retrieve and work with Bill of Materials (BOM) data for a component.

    You will learn how to:

    • Retrieve the first-level BOM rows for a component.
    • Choose a BOM composition (WORKING / RELEASED / PENDING) and point in time.
    • Paginate large BOMs.
    • Walk the BOM beyond one level (whole tree or level by level).
    • Override a BOM quantity and revert the override.
    • Hide the children of a sub-assembly so it appears as a single part, and revert the change.
    • Generate a parts-only (flat) BOM.
    • Reorder the BOM relations under a component.
    • Remove a BOM row and restore it.

    Prerequisites

    Before starting this tutorial, complete:

    1. Retrieve Hubs.
    2. Retrieve Projects.
    3. Retrieve Folders.
    4. Retrieve Items.

    You will use the following operations in this topic:

    Note: All examples can be run from the Manufacturing Data Model Explorer. The componentId used throughout is the component returned for the design you selected in Retrieve Items.

    Step 1 - Retrieve First-Level BOM Rows

    The component query returns a BOM item. Its bomRelations field returns the immediate (first-level) children of that item: sequence, child component, quantity, and an opaque toComponentState token for deeper traversal.

    1. In the Explorer, enter the following in the Query pane:

      query GetBOMRelations($componentId: ID!) {
        component(componentId: $componentId) {
          id
          bomRelations(depth: 1) {
            pagination { cursor }
            results {
              id
              sequenceNumber
              toComponent {
                id
                name { value }
                partNumber { value }
              }
              toComponentState
              quantityProperty {
                value
                definition { id }
              }
            }
          }
        }
      }
      
      Show More
    2. In the Query Variables pane, enter the componentId from Retrieve Items:

      {
        "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ"
      }
      
    3. Click Play. The results array contains one entry per first-level BOM relation. A truncated example:

      {
        "data": {
          "component": {
            "id": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
            "bomRelations": {
              "pagination": { "cursor": null },
              "results": [
                {
                  "id": "Ym9tcmVsYXRpb25-MzdIYmo0R1ZBaG5FM1ZYVGRyajN4c19MMkN-d0J4aGVKQ1JaTWtCNHZPTjdJZlJuSA",
                  "sequenceNumber": 10,
                  "toComponent": {
                    "id": "cHJvZHVjdH4zN0hiajRHVkFobkUzVlhUZHJqM3hzX0wyQ35aTTE3aHZKRTNCNlBHb0JMS2RpMjZnX2FnYQ",
                    "name": { "value": "Hex Nut M6" },
                    "partNumber": { "value": "FAS-100042" }
                  },
                  "toComponentState": "c3RhdGV-V09SS0lOR35udWxsfnsi...",
                  "quantityProperty": {
                    "value": 2,
                    "definition": { "id": "cHJvcGVydHlkZWZpbml0aW9ufn..." }
                  }
                }
              ]
            }
          }
        }
      }
      
      Show More

    Field reference (selected):

    • id — the BOM relation ID. You pass this as targetId when setting properties on the relation (e.g., the quantity override in Step 5).
    • sequenceNumber — 1-based ordering within the parent; sort by this to mirror the authored BOM order.
    • toComponent — the child component. Select name and partNumber so your output has human-readable identifiers.
    • toComponentState — an opaque continuation token. Pass it back to the API unchanged via componentFromState(state: ...) to walk deeper (Step 4). Do not parse or rely on its contents.
    • quantityProperty.value — the current quantity used downstream. Reflects a user-supplied override if one is set, otherwise the value derived from CAD.
    • quantityProperty.definition.id — the property-definition ID needed to override the quantity (Step 5).

    Note: Use quantityProperty { value }. The scalar quantity: Int! on BOMRelation is deprecated.

    Note: The depth argument controls how many levels are returned as a flat list. depth: 1 returns the immediate children (used here), depth: 2 returns two levels, and the default depth: 0 returns the whole BOM tree. To walk the BOM one level at a time, see Step 4.

    Step 2 - Choose a BOM Composition and Point in Time

    The component query accepts two optional arguments that select which BOM you are resolving:

    • composition: BOMCompositionEnum — defaults to WORKING (the current working design). Other values: RELEASED (the most recently released BOM) and PENDING (changes pending review and approval). RELEASED and PENDING require the Fusion Manage Extension.
    • time: DateTime — defaults to the current moment. Pass an earlier timestamp to resolve the BOM as it existed at that point in time.
    query GetBOMRelationsAtTime(
      $componentId: ID!
      $composition: BOMCompositionEnum = WORKING
      $time: DateTime
    ) {
      component(componentId: $componentId, composition: $composition, time: $time) {
        id
        bomRelations(depth: 1) {
          results {
            id
            sequenceNumber
            toComponent { id name { value } partNumber { value } }
            quantityProperty { value }
          }
        }
      }
    }
    
    Show More

    Example variables: fetch the most recently released BOM for the component:

    {
      "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
      "composition": "RELEASED"
    }
    

    Example variables: fetch the BOM as it existed on a specific date:

    {
      "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
      "time": "2025-09-15T13:33:30.83Z"
    }
    

    Step 3 - Paginate Large BOMs

    bomRelations returns paginated results. For BOMs with many children the first response contains one page of rows plus a pagination.cursor. If that cursor is non-null, pass it back in the next request to fetch the next page.

    query GetBOMRelationsPaged(
      $componentId: ID!
      $pagination: PaginationInput
    ) {
      component(componentId: $componentId) {
        bomRelations(depth: 1, pagination: $pagination) {
          pagination { cursor }
          results {
            id
            sequenceNumber
            toComponent { id name { value } partNumber { value } }
            quantityProperty { value }
          }
        }
      }
    }
    
    Show More

    First call - request a page size and no cursor:

    {
      "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
      "pagination": { "limit": 50 }
    }
    

    Subsequent calls - pass the cursor from the previous response:

    {
      "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
      "pagination": { "limit": 50, "cursor": "eyJvZmZzZXQiOjUwfQ==" }
    }
    

    Stop paginating when pagination.cursor comes back null.

    Step 4 - Walk the BOM Beyond One Level

    There are two ways to retrieve more than the immediate children:

    • Fetch multiple levels in one call by raising depth (or the whole tree with the default depth: 0). Simplest when you want the full structure up front.
    • Walk one level at a time by re-rooting at each child. Best for very large assemblies or lazy, on-demand loading.

    Option A - Fetch the Whole Tree in One Call

    Set depth to the number of levels you want, or omit it (default depth: 0) to return all levels. The response is a flat list of BOM relations, so include both fromComponent (parent) and toComponent (child) on each row and use those links to reconstruct the hierarchy client-side.

    query GetWholeBOM(
      $componentId: ID!
      $composition: BOMCompositionEnum = WORKING
      $time: DateTime
    ) {
      component(componentId: $componentId, composition: $composition, time: $time) {
        id
        bomRelations {
          pagination { cursor }
          results {
            id
            sequenceNumber
            fromComponent { id name { value } }
            toComponent { id name { value } partNumber { value } }
            toComponentState
            quantityProperty { value }
          }
        }
      }
    }
    
    Show More

    Variables:

    {
      "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ"
    }
    

    Group the returned rows by fromComponent.id to rebuild each parent’s child list, then link the groups together to form the tree. Large trees are still paginated: keep requesting pages until pagination.cursor is null.

    Option B - Walk Level by Level

    For very large assemblies or lazy loading, walk the BOM one level at a time by re-rooting at each child using the toComponentState token returned for that row.

    1. Capture toComponentState from a BOM row in Step 1.
    2. Pass it to componentFromState to get the child Component resolved at the correct composition/time.
    3. Select bomRelations(depth: 1) on that child to get its children.
    query NextLevel($state: String!) {
      componentFromState(state: $state) {
        id
        bomRelations(depth: 1) {
          pagination { cursor }
          results {
            id
            sequenceNumber
            toComponent { id name { value } partNumber { value } }
            toComponentState
            quantityProperty { value }
          }
        }
      }
    }
    
    Show More

    Variables:

    {
      "state": "c3RhdGV-V09SS0lOR35udWxsfnsi..."
    }
    

    Repeat the pattern (call componentFromState with each new toComponentState) to walk the BOM breadth-first or depth-first as needed. A common pattern is to enqueue each toComponentState you see and drain the queue until every branch is resolved.

    Step 5 - Override a BOM Quantity

    Use the setProperties mutation to override the quantity of an individual BOM relation without modifying the underlying CAD design. You need two IDs you already captured in the Step 1 response:

    • The BOM relation id (the value of results[*].id), which you pass as targetId.
    • The results[*].quantityProperty.definition.id on that same row, which you pass as propertyDefinitionId.

    Set an Override

    mutation SetQuantityOverride($input: SetPropertiesInput!) {
      setProperties(input: $input) {
        targetId
        properties {
          value
          definition { id }
        }
      }
    }
    
    Show More
    {
      "input": {
        "targetId": "Ym9tcmVsYXRpb25-MzdIYmo0R1ZBaG5FM1ZYVGRyajN4c19MMkN-d0J4aGVKQ1JaTWtCNHZPTjdJZlJuSA",
        "propertyInputs": [
          {
            "propertyDefinitionId": "cHJvcGVydHlkZWZpbml0aW9ufn...",
            "value": 4
          }
        ]
      }
    }
    
    Show More

    On success, properties[*].value in the response reflects the new quantity; re-running the Step 1 query for the same relation will return the same value from quantityProperty.value.

    Remove an Override

    Send the same mutation with value set to null to revert to the CAD-derived value.

    {
      "input": {
        "targetId": "Ym9tcmVsYXRpb25-MzdIYmo0R1ZBaG5FM1ZYVGRyajN4c19MMkN-d0J4aGVKQ1JaTWtCNHZPTjdJZlJuSA",
        "propertyInputs": [
          {
            "propertyDefinitionId": "cHJvcGVydHlkZWZpbml0aW9ufn...",
            "value": null
          }
        ]
      }
    }
    
    Show More

    Validation: the override value must satisfy:

    • Positive integer (≥ 1). Zero, decimals, negative numbers, and non-numeric values are rejected.
    • The property definition must be applicable to BOM relationships, must not be archived, and must not be read-only.

    Step 6 - Hide Children of a Sub-Assembly

    Use setProperties on a sub-assembly Component to enable Hide Children (bomStructureTypeProperty value 2; the same setting is exposed as Make Part in Fusion). The change applies everywhere that component appears — structured bomRelations traversal (Steps 1 and 4) and the flat partsList (Step 7). CAD geometry is unchanged; BOM queries stop returning the sub-assembly’s child rows.

    Unlike Step 5, the targetId here is a component id (the toComponent.id of the sub-assembly row from Step 1), not a BOM relation id. You also need bomStructureTypeProperty.definition.id from the query below.

    query GetBomStructureTypeDefinition($componentId: ID!) {
      component(componentId: $componentId) {
        id
        bomStructureTypeProperty {
          value
          definition { id }
        }
      }
    }
    
    Show More

    Supported values for this property are 0 (DEFAULT; children visible in the BOM) and 2 (HIDDEN_CHILDREN; children hidden in the BOM).

    Enable Hide Children

    mutation HideBomChildren($input: SetPropertiesInput!) {
      setProperties(input: $input) {
        targetId
        properties { value definition { id } }
      }
    }
    
    {
      "input": {
        "targetId": "cHJvZHVjdH4zN0hiajRHVkFobkUzVlhUZHJqM3hzX0wyQ35aTTE3aHZKRTNCNlBHb0JMS2RpMjZnX2FnYQ",
        "propertyInputs": [
          {
            "propertyDefinitionId": "cHJvcGVydHlkZWZpbml0aW9ufn...",
            "value": 2
          }
        ]
      }
    }
    
    Show More

    On success, properties[*].value in the response is 2.

    Verify

    The root assembly still lists the sub-assembly as one row in Step 1; only the child list under the sub-assembly changes. Pick a row whose toComponent is itself a sub-assembly — i.e., one that has children of its own; the verification only makes sense when there are children to hide. From Step 1, copy that row’s toComponentState (for example Motor Mount), then run:

    query SubAssemblyChildren($state: String!) {
      componentFromState(state: $state) {
        bomStructureTypeProperty { value }
        bomRelations(depth: 1) {
          results {
            sequenceNumber
            toComponent { id name { value } }
          }
        }
      }
    }
    
    Show More
    {
      "state": "c3RhdGV-V09SS0lOR35udWxsfnsi..."
    }
    

    While bomStructureTypeProperty.value is still 0, bomRelations lists the sub-assembly’s children (for example Bracket, Shaft). After the mutation, run the same query with the same state. You should see bomStructureTypeProperty.value of 2 and an empty bomRelations.results array:

    {
      "data": {
        "componentFromState": {
          "bomStructureTypeProperty": { "value": 2 },
          "bomRelations": {
            "results": []
          }
        }
      }
    }
    
    Show More

    Restore the Default

    Send the same mutation with value set to 0. The sub-assembly’s bomRelations child rows return.

    {
      "input": {
        "targetId": "cHJvZHVjdH4zN0hiajRHVkFobkUzVlhUZHJqM3hzX0wyQ35aTTE3aHZKRTNCNlBHb0JMS2RpMjZnX2FnYQ",
        "propertyInputs": [
          {
            "propertyDefinitionId": "cHJvcGVydHlkZWZpbml0aW9ufn...",
            "value": 0
          }
        ]
      }
    }
    
    Show More

    Note

    The setting applies to the component everywhere it is used in a BOM, not only under one parent assembly.

    Step 7 - Generate a Parts-Only (Flat) BOM

    Use Component.partsList to retrieve a flat list of leaf components required to manufacture an assembly. Intermediate sub-assemblies are excluded; each row is a single leaf part with its total rolled-up quantity.

    The parts list is generated asynchronously. The first call returns status: IN_PROGRESS and the caller polls until status becomes COMPLETE. The result is uniquely identified by componentId, composition, and computeTime (or the baseline time on component, when only that is provided).

    1. Make the first call:

      query GetPartsList(
        $componentId: ID!
        $composition: BOMCompositionEnum = WORKING
        $time: DateTime
        $computeTime: DateTime
        $filter: PropertyFilterInput
        $pagination: PaginationInput
      ) {
        component(componentId: $componentId, composition: $composition, time: $time) {
          id
          partsList(
            computeTime: $computeTime
            filter: $filter
            pagination: $pagination
          ) {
            status
            pagination { cursor }
            totals {
              results { name value }
            }
            results {
              sequenceNumber
              component { id name { value } partNumber { value } }
              quantityProperty { name value }
              computedProperties {
                results { name value }
              }
              errors { code message }
            }
            errors { code message }
          }
        }
      }
      
      Show More
    2. Variables: either set time on component or computeTime on partsList. If you set both, they must be equal.

      {
        "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
        "computeTime": "2025-09-15T13:33:30.83Z"
      }
      

      To get the most recently released parts list (requires the Fusion Manage Extension), set composition to RELEASED:

      {
        "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
        "composition": "RELEASED",
        "computeTime": "2025-09-15T13:33:30.83Z"
      }
      
    3. The first response typically returns status: IN_PROGRESS and an empty results array:

      {
        "data": {
          "component": {
            "id": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
            "partsList": {
              "status": "IN_PROGRESS",
              "pagination": { "cursor": null },
              "totals": { "results": [] },
              "results": [],
              "errors": null
            }
          }
        }
      }
      
      Show More
    4. Poll the same query with the same arguments (typically every 1–2 seconds; back off to 5 seconds on persistent IN_PROGRESS) until status is COMPLETE. If status is ERROR, inspect the top-level errors array.

      A truncated COMPLETE response:

      {
        "data": {
          "component": {
            "id": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
            "partsList": {
              "status": "COMPLETE",
              "pagination": { "cursor": null },
              "totals": { "results": [] },
              "results": [
                {
                  "sequenceNumber": 1,
                  "component": {
                    "id": "cHJvZHVjdH4zN0hiajRHVkFobkUzVlhUZHJqM3hzX0wyQ35aTTE3aHZKRTNCNlBHb0JMS2RpMjZnX2FnYQ",
                    "name": { "value": "Hex Nut M6" },
                    "partNumber": { "value": "FAS-100042" }
                  },
                  "quantityProperty": { "name": "Quantity", "value": 8 },
                  "computedProperties": { "results": [] },
                  "errors": null
                }
              ],
              "errors": null
            }
          }
        }
      }
      
      Show More

    Access control for leaf parts. Permission checks apply to the leaf components in the result. If a caller lacks permission to view a specific leaf:

    • results[*].component is null.
    • results[*].sequenceNumber and results[*].quantityProperty are still populated.
    • results[*].computedProperties is not populated.
    • results[*].errors contains a PartsListError with code: PERMISSION_DENIED.

    The other PartsListErrorEnum value is CIRCULAR_REFERENCE, returned when a cycle prevents full traversal of a branch.

    Step 8 - Reorder BOM Relations

    Use the reorderList mutation to change the order in which BOM relations appear under a parent component, without modifying the underlying CAD design. The new order is reflected by the sequenceNumber returned in Step 1.

    You need three IDs, all captured from the Step 1 response:

    • The parent component id you queried in Step 1, passed as parentId.
    • The BOM relation id (results[*].id) you want to move, passed as targetId.
    • A second BOM relation id under the same parent that positions the target, passed as moveBeforeId (move the target immediately before it) or moveAfterId (move it immediately after it). Provide only one.
    1. In the Query pane, enter:

      mutation ReorderStructureView(
        $componentId: ID!
        $targetBOMRelationId: ID!
        $moveBeforeBOMRelationId: ID!
      ) {
        reorderList(
          input: {
            listType: BOM_RELATIONS
            parentId: $componentId
            reorderInputs: [
              {
                targetId: $targetBOMRelationId
                moveBeforeId: $moveBeforeBOMRelationId
              }
            ]
          }
        ) {
          success
        }
      }
      
      Show More
    2. In the Query Variables pane, enter the parent componentId and two BOM relation IDs from your Step 1 results:

      {
        "componentId": "cHJvZHVjdH5VaFdQRXROYU9FdDBBbEhxYTNIckh0X0wyQ35lTG1melpjdWo4VUZqQm1pQm5iYkQx",
        "targetBOMRelationId": "Ym9tcmVsYXRpb25-VWhXUEV0TmFPRXQwQWxIcWEzSHJIdF9MMkN-ZGtJOEFHb0piUlJiM2pPQW1HWnRDUA",
        "moveBeforeBOMRelationId": "Ym9tcmVsYXRpb25-VWhXUEV0TmFPRXQwQWxIcWEzSHJIdF9MMkN-emcxZXZzM3dDU3B6ekhOU0pMNTQ0OQ"
      }
      
    3. Click Play. On success the response is:

      {
        "data": {
          "reorderList": {
            "success": true
          }
        }
      }
      

    Re-run the Step 1 query for the same parent component to confirm the updated sequenceNumber ordering.

    Note: To position a relation after a reference row instead, replace moveBeforeId with moveAfterId. To move several relations in one call, add more entries to the reorderInputs array. The same mutation reorders parts list items when you set listType: PARTS_LIST_ITEMS and pass PartsListItem IDs.

    Step 9 - Remove and Restore a BOM Row

    Use removeComponentFromBOM to remove (exclude) a child component from a parent’s BOM, and insertComponentToBOM to restore it. Both operate on component IDs, not BOM relation IDs:

    • parentComponentId — the parent component id you queried in Step 1.
    • childComponentId — a toComponent.id from a Step 1 BOM row.

    Remove a Row

    1. In the Query pane, enter:

      mutation RemoveComponentFromBOM($input: RemoveComponentFromBOMInput!) {
        removeComponentFromBOM(input: $input) {
          component { id }
          status
        }
      }
      
    2. In the Query Variables pane, enter the parent and child component IDs:

      {
        "input": {
          "parentComponentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
          "childComponentId": "cHJvZHVjdH4zN0hiajRHVkFobkUzVlhUZHJqM3hzX0wyQ35aTTE3aHZKRTNCNlBHb0JMS2RpMjZnX2FnYQ"
        }
      }
      
    3. Click Play. The response reports the resulting status — EXCLUDED for a CAD-backed row (hidden but retained) or REMOVED for a row that is fully deleted:

      {
        "data": {
          "removeComponentFromBOM": {
            "component": {
              "id": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ"
            },
            "status": "EXCLUDED"
          }
        }
      }
      
      Show More

    Re-run the Step 1 query for the parent; the excluded row no longer appears in bomRelations.results.

    Restore a Row

    Use insertComponentToBOM with the same parent and child IDs to restore an excluded row.

    1. In the Query pane, enter:

      mutation InsertComponentToBOM($input: InsertComponentToBOMInput!) {
        insertComponentToBOM(input: $input) {
          component { id }
        }
      }
      
    2. In the Query Variables pane, enter the same IDs used to remove the row:

      {
        "input": {
          "parentComponentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ",
          "childComponentId": "cHJvZHVjdH4zN0hiajRHVkFobkUzVlhUZHJqM3hzX0wyQ35aTTE3aHZKRTNCNlBHb0JMS2RpMjZnX2FnYQ"
        }
      }
      
    3. Click Play. Re-run the Step 1 query to confirm the row appears in bomRelations.results again.

    Note: insertComponentToBOM only restores a row that was previously removed (excluded). Inserting a component that was not previously excluded returns an error.

    After following these steps you will know how to fetch BOM rows at any composition or point in time, paginate large BOMs, walk the BOM tree beyond the first level, override quantities, hide a sub-assembly’s children to flatten it into a single part, generate a flat parts-only BOM, reorder the BOM relations under a component, and remove and restore BOM rows.