> ## 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 BOM versions

> How mBOMs are versioned over time, what triggers a new version, and how in-flight runs handle BOM changes.

ION tracks mBOM changes through explicit versions. See [Bills of materials overview](/build-hardware/bills-of-materials) for how versioning relates to part revisions and in-flight runs. This page covers what triggers a new version, the version states, and the release flow.

## When a new version is needed

| Change                              | Action                                                   |
| ----------------------------------- | -------------------------------------------------------- |
| Add a new build requirement         | New version                                              |
| Remove a build requirement          | New version                                              |
| Change a part on an existing line   | New version                                              |
| Change a quantity                   | New version (significant); in-place edit (clarification) |
| Add or remove a substitute          | In-place edit                                            |
| Add or change reference designators | New version                                              |
| Toggle MOA on a line                | New version                                              |
| Edit a note or instruction          | In-place edit                                            |

In general, structural changes (what gets installed, where, and how many) need a new version. Metadata changes (notes, alternates, and clarifications) can be in-place edits.

## Version states

mBOM versions move through:

| State         | Meaning                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **Draft**     | Editable; not used by any new run                                                                |
| **In Review** | Submitted for review before release                                                              |
| **Released**  | Locked structure; new runs against the parent part instantiate from this version                 |
| **Archived**  | No longer current; preserved for historical reference and in-flight runs that started against it |

Only one version of an mBOM is **Released** at a time. Releasing a new version automatically archives the previously released version.

## Release a new version

1. Open the **mBOM** card on the part page with the version in **Draft**.
2. Make the structural changes.
3. Use the status dropdown to move the version through **In Review** and then **Released**.

The new version becomes **Released**, and the previous version moves to **Archived**. To start the next version once the current one is released, click **Create new mBom version** in the card header.

## In-flight runs

When you release a new mBOM version, in-flight runs are unaffected:

* Each run captures the mBOM version it was started against at create time.
* Mid-flight runs continue running the old version even after the new one is released.
* New runs started after the release pick up the new version.
* The transition is handled per-run. There's no way to upgrade an existing run to the new mBOM.

<Note>
  To apply a structural change to an in-flight run, use a [redline](/build-hardware/runs-and-execution/redlines-and-deviations).
</Note>

## Switch between versions

The **mBOM** card on the part page has a version dropdown (for example, `v1`, `v2`) in its header. Pick a version to view its lines. Each option shows the version's status, and **Draft** versions can be deleted from the dropdown. To see a version's full line items, open the full mBOM with the **Go to full mBom** link in the card header.

## Programmatic comparison

ION has no built-in page that diffs two mBOM versions. For integrations or scripts, adapt the [Compare two aBOM versions](/api-reference/common-queries/compare-aboms) query template: fetch the line items for both versions and diff them client-side.

## Change-control patterns

<Tip>
  Group related changes from an Engineering Change Notice into one release rather than several incremental ones. Write a specific release note, such as "Updated R3 to 10kΩ per ECN-2026-0042", rather than "minor updates". Don't edit archived versions, even for typo fixes, since the historical record is part of the audit trail.
</Tip>

## Related

* [Bills of materials overview](/build-hardware/bills-of-materials)
* [Manufacturing BOM (mBOM)](/build-hardware/bills-of-materials/manufacturing-bom)
* [As-built BOM (aBOM)](/build-hardware/bills-of-materials/as-built-bom)
* [Edit build requirements](/build-hardware/bills-of-materials/editing-build-requirements)
* [Redlines and deviations](/build-hardware/runs-and-execution/redlines-and-deviations)
* [Compare two aBOM versions](/api-reference/common-queries/compare-aboms)