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:
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.
- 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 - In the Query Variables pane, enter the
componentIdfrom Retrieve Items:{ "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ" } - Click Play. The
resultsarray 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 astargetIdwhen 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. SelectnameandpartNumberso your output has human-readable identifiers.toComponentState— an opaque continuation token. Pass it back to the API unchanged viacomponentFromState(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 toWORKING(the current working design). Other values:RELEASED(the most recently released BOM) andPENDING(changes pending review and approval).RELEASEDandPENDINGrequire 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 }
}
}
}
}
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 }
}
}
}
}
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 defaultdepth: 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 }
}
}
}
}
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.
- Capture
toComponentStatefrom a BOM row in Step 1. - Pass it to
componentFromStateto get the childComponentresolved at the correct composition/time. - 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 }
}
}
}
}
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 ofresults[*].id), which you pass astargetId. - The
results[*].quantityProperty.definition.idon that same row, which you pass aspropertyDefinitionId.
Set an Override
mutation SetQuantityOverride($input: SetPropertiesInput!) {
setProperties(input: $input) {
targetId
properties {
value
definition { id }
}
}
}
{
"input": {
"targetId": "Ym9tcmVsYXRpb25-MzdIYmo0R1ZBaG5FM1ZYVGRyajN4c19MMkN-d0J4aGVKQ1JaTWtCNHZPTjdJZlJuSA",
"propertyInputs": [
{
"propertyDefinitionId": "cHJvcGVydHlkZWZpbml0aW9ufn...",
"value": 4
}
]
}
}
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
}
]
}
}
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 }
}
}
}
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
}
]
}
}
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 } }
}
}
}
}
{
"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": []
}
}
}
}
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
}
]
}
}
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).
- 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 - Variables: either set
timeoncomponentorcomputeTimeonpartsList. 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
compositiontoRELEASED:{ "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ", "composition": "RELEASED", "computeTime": "2025-09-15T13:33:30.83Z" } - The first response typically returns
status: IN_PROGRESSand an emptyresultsarray:{ "data": { "component": { "id": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ", "partsList": { "status": "IN_PROGRESS", "pagination": { "cursor": null }, "totals": { "results": [] }, "results": [], "errors": null } } } }Show More - Poll the same query with the same arguments (typically every 1–2
seconds; back off to 5 seconds on persistent
IN_PROGRESS) untilstatusisCOMPLETE. IfstatusisERROR, inspect the top-levelerrorsarray.A truncated
COMPLETEresponse:{ "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[*].componentisnull.results[*].sequenceNumberandresults[*].quantityPropertyare still populated.results[*].computedPropertiesis not populated.results[*].errorscontains aPartsListErrorwithcode: 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
idyou queried in Step 1, passed asparentId. - The BOM relation
id(results[*].id) you want to move, passed astargetId. - A second BOM relation
idunder the same parent that positions the target, passed asmoveBeforeId(move the target immediately before it) ormoveAfterId(move it immediately after it). Provide only one.
- 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 - In the Query Variables pane, enter the parent
componentIdand two BOM relation IDs from your Step 1 results:{ "componentId": "cHJvZHVjdH5VaFdQRXROYU9FdDBBbEhxYTNIckh0X0wyQ35lTG1melpjdWo4VUZqQm1pQm5iYkQx", "targetBOMRelationId": "Ym9tcmVsYXRpb25-VWhXUEV0TmFPRXQwQWxIcWEzSHJIdF9MMkN-ZGtJOEFHb0piUlJiM2pPQW1HWnRDUA", "moveBeforeBOMRelationId": "Ym9tcmVsYXRpb25-VWhXUEV0TmFPRXQwQWxIcWEzSHJIdF9MMkN-emcxZXZzM3dDU3B6ekhOU0pMNTQ0OQ" } - 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 componentidyou queried in Step 1.childComponentId— atoComponent.idfrom a Step 1 BOM row.
Remove a Row
- In the Query pane, enter:
mutation RemoveComponentFromBOM($input: RemoveComponentFromBOMInput!) { removeComponentFromBOM(input: $input) { component { id } status } } - In the Query Variables pane, enter the parent and child component IDs:
{ "input": { "parentComponentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ", "childComponentId": "cHJvZHVjdH4zN0hiajRHVkFobkUzVlhUZHJqM3hzX0wyQ35aTTE3aHZKRTNCNlBHb0JMS2RpMjZnX2FnYQ" } } - Click Play. The response reports the resulting
status—EXCLUDEDfor a CAD-backed row (hidden but retained) orREMOVEDfor 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.
- In the Query pane, enter:
mutation InsertComponentToBOM($input: InsertComponentToBOMInput!) { insertComponentToBOM(input: $input) { component { id } } } - In the Query Variables pane, enter the same IDs used to remove the row:
{ "input": { "parentComponentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35GMkJWR2xuUnZUY2VCZlExNWtVTkpVX2FnYQ", "childComponentId": "cHJvZHVjdH4zN0hiajRHVkFobkUzVlhUZHJqM3hzX0wyQ35aTTE3aHZKRTNCNlBHb0JMS2RpMjZnX2FnYQ" } } - Click Play. Re-run the Step 1 query to confirm the row appears in
bomRelations.resultsagain.
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.