> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage mBOM items

> Query and manage mBOM items and substitutes through the ION GraphQL API.

An mBOM item represents the bill of materials required to construct a part. A part has an mBOM made up of many mBOM items, which dictate the subparts used in the part's construction. You can think of parts as a tree structure, where the nodes are part objects and the edges are mBOM items. The root of the tree is a part representing a completed assembly. Its mBOM is the parts used in its construction. Each of those parts can have its own mBOM.

## mBOM items

| mBOM item   | Description                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| id          | Unique identifier of the mBOM item object.                                                             |
| parent      | The [part](/api/guides/parts-and-part-revisioning) object whose construction this mBOM item describes. |
| part        | The [part](/api/guides/parts-and-part-revisioning) object used in the construction of the parent.      |
| quantity    | The amount of a specific part needed in construction.                                                  |
| substitutes | List of valid substitutes that can be used in place of the specified part.                             |

## mBOM substitutes

An mBOM substitute is a valid alternative that can be used in place of the defined part. Each mBOM item can have many mBOM substitutes, which are subpart replacements for that specific subpart.

| mBOM substitute | Description                                                                                                      |
| --------------- | ---------------------------------------------------------------------------------------------------------------- |
| id              | Unique identifier of the mBOM substitute object.                                                                 |
| part            | The [part](/api/guides/parts-and-part-revisioning) object that can be substituted for the part in the mBOM item. |
| mbomItem        | The mBOM item for which this object is a valid substitute.                                                       |

## Query an mBOM item

It is often more effective to query the mBOM relation through a part object.

List mBOM items with a filter:

```graphql theme={null}
query MBOMItems($filters: MBomItemsInputFilters) {
    mbomItems(filters: $filters) {
        edges {
            node {
                id partId parentId quantity
            }
        }
    }
}
```

Set the filter variables:

```json theme={null}
{
    "filters": {
        "parentId": {
            "eq": 1
        }
    }
}
```

Get a single mBOM item by ID:

```graphql theme={null}
query GetMBOMItem {
    mbomItem(id: 1) {
        id partId parentId quantity
    }
}
```

## Explode a multi-level mBOM

`mbomExplosion` returns every descendant line of a root assembly's mBOM in one request, so you don't have to walk the tree one request per node.

```graphql theme={null}
query MBomExplosion($input: MBomExplosionInput!) {
    mbomExplosion(input: $input) {
        edges {
            node {
                level parentPartId quantity totalQuantity
                mbomItem {
                    id partId parentId
                }
            }
        }
    }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "partId": 1
    }
}
```

Each node describes one line of the exploded tree:

| Field           | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------- |
| `level`         | Depth in the tree. Lines on the root mBOM are level 1.                                |
| `parentPartId`  | The part whose assembly this line sits under.                                         |
| `quantity`      | The line's own quantity, per one unit of its parent assembly.                         |
| `totalQuantity` | The quantity rolled up through the tree: the parent's total multiplied by `quantity`. |
| `mbomItem`      | The underlying mBOM item, so you can select the part, substitutes, and designators.   |

Lines come back depth-first, so you can rebuild the tree, or write a CSV, straight from the order they arrive in.

`partId` is required. `mbomId` is optional and sets the version used for the **root** level only: pass it to explode a specific version, or omit it to use the part's released mBOM, falling back to its latest when there is no released version. Nested levels always resolve released-else-latest. Passing an `mbomId` that belongs to a different part returns a validation error.

### What the results leave out

Three cases drop lines from the response without returning an error, so check for them before treating a result as a complete tree:

* **Repeated parts.** If a part already appears higher in the same branch, the line for it is left out of the results entirely, rather than returned without its children. A cyclic mBOM terminates instead of looping.
* **Export-controlled parts.** When you aren't allowed to see an export-controlled part, its line is omitted along with everything below it. If the **root** assembly itself is export-controlled, the query returns no lines at all, which reads the same as an assembly that has no mBOM.
* **Very deep trees.** Explosion stops after 100 levels. Anything deeper is dropped silently.

## Query an mBOM substitute

List mBOM substitutes with a filter:

```graphql theme={null}
query MBOMSubstitutes($filters: MBomSubstituteInputFilters) {
    mbomSubstitutes(filters: $filters) {
        edges {
            node {
                id partId parentId mbomItemId
            }
        }
    }
}
```

Set the filter variables:

```json theme={null}
{
    "filters": {
        "mbomItemId": {
            "eq": 1
        }
    }
}
```

Get a single mBOM substitute by ID:

```graphql theme={null}
query MBOMSubstitute {
    mbomSubstitute(id: 1) {
        id partId parentId mbomItemId
    }
}
```

## Create an mBOM item

An mBOM item defines which part, and how many of it, a new part needs. `parent` is the part being built, and `part` is the part required in the build. The quantity value must be greater than 0.

Create the mBOM item with this mutation:

```graphql theme={null}
mutation($input: CreateMBomItemInput!){
  createMbomItem(input: $input){
      mbomItem {
          id parentId partId quantity
      }
  }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "parentId": 2,
        "partId": 1,
        "quantity": 3
    }
}
```

## Update an mBOM item

You can update the quantity of an mBOM item and its associated part. Returns the updated mBOM item.

Update the mBOM item with this mutation:

```graphql theme={null}
mutation UpdateMBomItem($input: UpdateMBomItemInput!) {
  updateMbomItem(input: $input) {
    mbomItem {
      id parentId partId quantity
    }
  }
}
```

Set the variables:

```json theme={null}
{
    "input": {
        "etag": "etag1",
        "id": 1,
        "partId": 3,
        "quantity": 5
    }
}
```

## Create mBOM substitutes

Create a valid substitution for a specific part within an mBOM. Any parts listed with mBOM substitutes do not raise a validation error if they are attached to an aBOM instead of the part specified in the original mBOM item.

Create the mBOM substitutes with this mutation:

```graphql theme={null}
  mutation CreateMbomSubstitutes($input:
                                 [CreateMBomSubstituteInput]!){
    createMbomSubstitutes(input: $input){
      mbomSubstitutes {
        id parentId partId mbomItemId
      }
    }
  }
```

Set the variables:

```json theme={null}
{
    "input": [
        { "partId": 3, "parentId": 2, "mbomItemId": 1 },
        { "partId": 4, "parentId": 2, "mbomItemId": 1 }
    ]
}
```

## Delete an mBOM item

You can delete an mBOM item unless it has already been used in the construction of an aBOM. Returns the ID of the deleted mBOM item.

Delete the mBOM item with this mutation:

```graphql theme={null}
mutation DeleteMBomItem($id: ID!, $etag: String!){
    deleteMbomItem(id: $id, etag: $etag){
        id
    }
}
```

Set the variables:

```json theme={null}
{
    "id": 1,
    "etag": "etag1"
}
```

## Delete an mBOM substitute

Delete the mBOM substitute with this mutation:

```graphql theme={null}
mutation DeleteMBomSubstitute($id: ID!, $etag: String!){
    deleteMbomSubstitute(id: $id, etag: $etag){
        id
    }
}
```

Set the variables:

```json theme={null}
{
    "id": 1,
    "etag": "etag1"
}
```

## Related

* [Manage parts and revisions](/api/guides/parts-and-part-revisioning)
* [Build an aBOM](/api/guides/abom-as-built-bill-of-materials-api)