---
agentTools:
  projectIndex: https://apidocs.macrofab.com/llms.txt
---

# Update BOM Items

Update specific bill of materials items for a version of a PCB project.

Items are matched by their `record_num`, as returned by
`GET /api/v3/pcb/{pcb_id}/{pcb_version}/bom`. Using this endpoint, you can modify the
attributes of an item in your bill of materials, such as:

* value
  The value (e.g. '1K') for the item.

* package
  The package type (e.g. '0402') for the item.

* populate
  Whether or not this part should be populated on the board.

* approved_vendor_list_id
  The approved vendor list to source the item from.

You must specify `record_num`, `part`, and one or more of these keys. Keys you do not specify
are not changed.

To change which manufacturer parts may be used for an item, edit its approved vendor list with
the Approved Vendor List endpoints. The part is chosen from that list when the PCB is quoted.
To change how an item is sourced, use `PUT /api/v3/pcb/{pcb_id}/{pcb_version}/sourcing/defaults`;
the `origin` field is deprecated and not used.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "MacroFab API",
    "description": "MacroFab API\n\n**Authentication**\n\nAuthenticate every request by sending your API key in the `X-MacroFab-API-Key` header.\nRequests act as the user that generated the API key.\n\n**Responses**\n\nSend `Accept: application/json` with every request. Some endpoints return an empty response\nwithout it.\n\n**Versions**\n\nEndpoints are versioned in their path (`/api/v2/`, `/api/v3/`, `/api/v4/`, `/api/v5/`), and\ndifferent endpoints are at different versions. Use the version documented here for each\nendpoint.\n",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "https://api.macrofab.com"
    }
  ],
  "paths": {
    "/api/v3/pcb/{pcb_id}/{pcb_version}/bom": {
      "get": {
        "tags": [
          "PCB"
        ],
        "summary": "Get BOM",
        "description": "Retrieve the electrical bill of materials for a specific PCB version.\n\nThe _bom_ key points to an object whose _parts_ array has one entry for each component\n(designator) on the board. While several of the part keys are obvious in their meaning, some\nrequire more detail:\n\n**populate**\n\nThe populate key indicates whether you have specified that the particular instance of that\ncomponent be populated on the board. By default, it is set to true, unless you have marked the\ncomponent \"Do not place\" in the Bill of Materials view for the PCB in the user interface. This\nkey having a value of true does not, however, ensure the part's population in assembly. The\ncomponent must also have a part to source.\n\n**approved_vendor_list**\n\nEvery BOM line is sourced through an approved vendor list (AVL): the manufacturer parts that\nmay be used for that line, in order of preference. A single MPN can be manufactured by a number\nof vendors, so every manufacturer part has a unique `part_id`. Lines that use the same part\nshare the same `approved_vendor_list_id`, so use it to group lines. Manage AVLs with the Approved\nVendor List endpoints.\n\n**sourcing_default**\n\nHow the line is sourced: `macrofab` (MacroFab purchases a part from the AVL) or `customer` (you\nsupply one). Change it with `PUT /api/v3/pcb/{pcb_id}/{pcb_version}/sourcing/defaults`. The\nolder `origin` field is deprecated and not used.\n\n**selected_part**, **selected_mpn**\n\nThese fields are deprecated and are generally `null`. Parts are not selected on the BOM: when\na PCB is quoted, MacroFab chooses the part for each line from its approved vendor list, based\non the list's priority (`precedence_preference` and `list_precedence`) and the market\navailability of the parts on it.\n",
        "responses": {
          "200": {
            "description": "The PCB version's electrical BOM",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "bom"
                  ],
                  "properties": {
                    "bom": {
                      "type": "object",
                      "required": [
                        "name",
                        "organizations",
                        "parts",
                        "user_id",
                        "version"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "BOM for PCB mdx0ce:1"
                        },
                        "created": {
                          "type": "string",
                          "description": "When the BOM was created",
                          "example": "2025-10-28 22:26:57"
                        },
                        "organizations": {
                          "type": "array",
                          "description": "IDs of the organizations that own the BOM",
                          "items": {
                            "type": "string",
                            "example": "m5x5f5"
                          }
                        },
                        "user_id": {
                          "type": "string",
                          "description": "ID of the user who created the BOM",
                          "example": "k364uj"
                        },
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "created_avls": {
                          "type": "array",
                          "description": "Approved vendor lists created while saving the BOM, if any",
                          "items": {}
                        },
                        "parts": {
                          "type": "array",
                          "description": "One entry for each designator on the board",
                          "items": {
                            "$ref": "#/paths/~1api~1v3~1pcb~1{pcb_id}~1{pcb_version}~1bom~1parts/put/responses/200/content/application~1json/schema/properties/parts/items"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "bom": {
                    "user_id": "k364uj",
                    "created": "2025-10-28 22:26:57",
                    "organizations": [
                      "m5x5f5"
                    ],
                    "name": "BOM for PCB mdx0ce:1",
                    "created_avls": [],
                    "version": 1,
                    "parts": [
                      {
                        "record_num": 12,
                        "part": "C1",
                        "mpn": "MF-CAP-0805-0.1uF",
                        "package": "0805",
                        "value": "0.1",
                        "device": null,
                        "selected_part": null,
                        "selected_mpn": null,
                        "approved_vendor_list_id": "ba4cf671-1894-4ebe-831f-603de818c5c6",
                        "approved_vendor_list_ipn": "MFI-C1644321-751917",
                        "origin": "turnkey",
                        "sourcing_default": "macrofab",
                        "input_source_type": null,
                        "populate": 1,
                        "group_key": null,
                        "updated": "2025-10-28 22:26:57",
                        "form_factor": null,
                        "alternate_parts": [],
                        "approved_vendor_list": {
                          "precedence_preference": "price",
                          "customer_part_number": null,
                          "parts": [
                            {
                              "manufacturer_part_number": "MF-CAP-0805-0.1uF",
                              "manufacturer_name": "MacroFab",
                              "part_id": "7bbb4057-9db1-5358-af9e-4877fcdd9ea8",
                              "list_precedence": 1
                            }
                          ]
                        }
                      },
                      {
                        "record_num": 6,
                        "part": "C3",
                        "mpn": "C3216X5R1V226M160AC",
                        "package": "1206",
                        "value": "22",
                        "device": null,
                        "selected_part": null,
                        "selected_mpn": null,
                        "approved_vendor_list_id": "48774583-95e5-42c7-ad5b-1815b0c22670",
                        "approved_vendor_list_ipn": "MFI-C1879318-392420",
                        "origin": "turnkey",
                        "sourcing_default": "macrofab",
                        "input_source_type": null,
                        "populate": 1,
                        "group_key": null,
                        "updated": "2025-10-28 22:26:57",
                        "form_factor": null,
                        "alternate_parts": [],
                        "approved_vendor_list": {
                          "precedence_preference": "price",
                          "customer_part_number": null,
                          "parts": [
                            {
                              "manufacturer_part_number": "C3216X5R1V226M160AC",
                              "manufacturer_name": "Taiyo Yuden",
                              "part_id": "d1a1addb-acf9-5717-9c3b-683d4d4852f6",
                              "list_precedence": 1
                            },
                            {
                              "manufacturer_part_number": "C3216X5R1V226M160AC",
                              "manufacturer_name": "TDK",
                              "part_id": "3de834ab-eb84-57ee-a8b9-68905d624f5e",
                              "list_precedence": 2
                            }
                          ]
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The PCB or PCB version does not exist, or you do not have access to it",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Error response returned by MacroFab microservice endpoints.",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "message"
                      ],
                      "properties": {
                        "message": {
                          "type": "string",
                          "description": "Human-readable description of the error",
                          "example": "PCB not found"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "apikeyHeader": []
          }
        ]
      },
      "parameters": [
        {
          "name": "pcb_id",
          "in": "path",
          "required": true,
          "description": "The PCB ID",
          "schema": {
            "type": "string",
            "example": "mdx0ce"
          }
        },
        {
          "name": "pcb_version",
          "in": "path",
          "required": true,
          "description": "The PCB version number",
          "schema": {
            "type": "integer",
            "example": 1
          }
        }
      ]
    },
    "/api/v3/pcb/{pcb_id}/{pcb_version}/bom/parts": {
      "put": {
        "tags": [
          "PCB"
        ],
        "summary": "Update BOM Items",
        "description": "Update specific bill of materials items for a version of a PCB project.\n\nItems are matched by their `record_num`, as returned by\n`GET /api/v3/pcb/{pcb_id}/{pcb_version}/bom`. Using this endpoint, you can modify the\nattributes of an item in your bill of materials, such as:\n\n* value\n  The value (e.g. '1K') for the item.\n\n* package\n  The package type (e.g. '0402') for the item.\n\n* populate\n  Whether or not this part should be populated on the board.\n\n* approved_vendor_list_id\n  The approved vendor list to source the item from.\n\nYou must specify `record_num`, `part`, and one or more of these keys. Keys you do not specify\nare not changed.\n\nTo change which manufacturer parts may be used for an item, edit its approved vendor list with\nthe Approved Vendor List endpoints. The part is chosen from that list when the PCB is quoted.\nTo change how an item is sourced, use `PUT /api/v3/pcb/{pcb_id}/{pcb_version}/sourcing/defaults`;\nthe `origin` field is deprecated and not used.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "parts"
                ],
                "properties": {
                  "parts": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "A BOM line to add or update. `part` is always required, and `record_num` is required when\nupdating. Fields that are left out are not changed when updating.\n",
                      "required": [
                        "part"
                      ],
                      "properties": {
                        "record_num": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Required when updating: the row number of the item to update, from the BOM. Ignored when\nadding items.\n",
                          "example": 12
                        },
                        "part": {
                          "type": "string",
                          "description": "Required. The part designator (e.g. `C1`) for the item.",
                          "example": "C1"
                        },
                        "origin": {
                          "type": "string",
                          "deprecated": true,
                          "description": "Deprecated and not used for quoting or the ready check. To set how a line is sourced, use\n`PUT /api/v3/pcb/{pcb_id}/{pcb_version}/sourcing/defaults`.\n"
                        },
                        "mpn": {
                          "type": "string",
                          "description": "The manufacturer part number for the item. When adding a line without an\n`approved_vendor_list_id`, MacroFab matches this MPN to an approved vendor list.\n",
                          "example": "GRM155R71C104KA88D"
                        },
                        "value": {
                          "type": "string",
                          "description": "The value (e.g. `1K`) for the item.",
                          "example": "0.1uF"
                        },
                        "package": {
                          "type": "string",
                          "description": "The package type (e.g. `0402`) for the item.",
                          "example": "0402"
                        },
                        "device": {
                          "type": "string",
                          "deprecated": true,
                          "description": "Deprecated. Use `value`."
                        },
                        "populate": {
                          "description": "Whether or not this part should be populated on the board. Defaults to true.",
                          "oneOf": [
                            {
                              "type": "boolean"
                            },
                            {
                              "type": "integer",
                              "enum": [
                                0,
                                1
                              ]
                            }
                          ]
                        },
                        "approved_vendor_list_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The approved vendor list (AVL) to source this line from. Use an AVL returned by\n`GET /api/v1/partnumber/organization/{organization_id}/approved-vendor-list` or by\nanother BOM line.\n"
                        },
                        "selected_part": {
                          "type": "string",
                          "deprecated": true,
                          "description": "Deprecated. Set the part through the line's approved vendor list instead; parts are chosen\nfrom it when the PCB is quoted.\n"
                        },
                        "selected_mpn": {
                          "type": "string",
                          "deprecated": true,
                          "description": "Deprecated."
                        },
                        "group_key": {
                          "type": "string",
                          "deprecated": true,
                          "description": "Deprecated and ignored. Lines that share a part share an `approved_vendor_list_id`.\n"
                        },
                        "form_factor": {
                          "type": "object",
                          "description": "Placement type and pin count, used to calculate labor",
                          "required": [
                            "type",
                            "pins"
                          ],
                          "properties": {
                            "type": {
                              "type": "string",
                              "example": "SMD"
                            },
                            "pins": {
                              "type": "integer",
                              "minimum": 0,
                              "example": 2
                            }
                          }
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "parts": [
                  {
                    "record_num": 12,
                    "part": "C1",
                    "value": "0.1uF"
                  },
                  {
                    "record_num": 6,
                    "part": "C3",
                    "populate": false
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "parts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A single line of a PCB's electrical bill of materials",
                        "required": [
                          "record_num",
                          "part",
                          "origin",
                          "populate",
                          "approved_vendor_list_id",
                          "approved_vendor_list"
                        ],
                        "properties": {
                          "record_num": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "The row number of the item. Use it to identify the line when deleting parts.",
                            "example": 6
                          },
                          "part": {
                            "type": "string",
                            "description": "The part designator (e.g. `C1`)",
                            "example": "C3"
                          },
                          "mpn": {
                            "type": "string",
                            "nullable": true,
                            "description": "The manufacturer part number supplied with the design",
                            "example": "C3216X5R1V226M160AC"
                          },
                          "value": {
                            "type": "string",
                            "nullable": true,
                            "description": "The value (e.g. `1K`) of the item",
                            "example": "22"
                          },
                          "package": {
                            "type": "string",
                            "nullable": true,
                            "description": "The package (e.g. `0402`) of the item",
                            "example": "1206"
                          },
                          "device": {
                            "type": "string",
                            "nullable": true,
                            "deprecated": true,
                            "description": "Deprecated; generally `null`, or the same as `value`. Use `value`."
                          },
                          "origin": {
                            "type": "string",
                            "deprecated": true,
                            "description": "Deprecated. This value isn't kept up to date, and quotes and the ready check don't use it.\nUse `sourcing_default` to see how the line is sourced.\n",
                            "example": "turnkey"
                          },
                          "populate": {
                            "description": "Whether this part should be populated on the board. By default it is true, unless you have\nmarked the component \"Do not place\" in the Bill of Materials view for the PCB. A true value\ndoes not by itself ensure the part is placed during assembly: the line must also have a\npart to source (see `approved_vendor_list`).\n",
                            "oneOf": [
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "integer",
                                "enum": [
                                  0,
                                  1
                                ]
                              }
                            ],
                            "example": 1
                          },
                          "approved_vendor_list_id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "ID of the approved vendor list (AVL) that sources this line. Every BOM line has one.\nLines that share a part share an AVL.\n",
                            "example": "48774583-95e5-42c7-ad5b-1815b0c22670"
                          },
                          "approved_vendor_list_ipn": {
                            "type": "string",
                            "description": "MacroFab's internal part number for the AVL",
                            "example": "MFI-C1879318-392420"
                          },
                          "approved_vendor_list": {
                            "type": "object",
                            "description": "The approved vendor list (AVL) for a BOM line: the manufacturer parts that may be used to\nfill it, in order of preference. Manage AVLs with the Approved Vendor List endpoints.\n",
                            "required": [
                              "precedence_preference",
                              "parts"
                            ],
                            "properties": {
                              "customer_part_number": {
                                "type": "string",
                                "nullable": true,
                                "description": "Your internal part number for this AVL, if one has been assigned"
                              },
                              "precedence_preference": {
                                "type": "string",
                                "description": "How MacroFab chooses among the parts on the AVL when the PCB is quoted: `price` picks the\nlowest-priced available part, and `manual` picks the first available part in\n`list_precedence` order.\n",
                                "enum": [
                                  "price",
                                  "manual"
                                ],
                                "example": "price"
                              },
                              "parts": {
                                "type": "array",
                                "description": "The manufacturer parts approved for this BOM line",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "list_precedence",
                                    "manufacturer_name",
                                    "manufacturer_part_number",
                                    "part_id"
                                  ],
                                  "properties": {
                                    "list_precedence": {
                                      "type": "integer",
                                      "description": "Preference order of this part within the AVL (1 is most preferred)",
                                      "example": 1
                                    },
                                    "manufacturer_name": {
                                      "type": "string",
                                      "example": "Taiyo Yuden"
                                    },
                                    "manufacturer_part_number": {
                                      "type": "string",
                                      "example": "C3216X5R1V226M160AC"
                                    },
                                    "part_id": {
                                      "type": "string",
                                      "format": "uuid",
                                      "description": "MacroFab's unique ID for this manufacturer part",
                                      "example": "d1a1addb-acf9-5717-9c3b-683d4d4852f6"
                                    }
                                  }
                                }
                              }
                            }
                          },
                          "selected_part": {
                            "type": "string",
                            "nullable": true,
                            "deprecated": true,
                            "description": "Deprecated; generally `null`. Parts are chosen when the PCB is quoted, from the line's\napproved vendor list.\n",
                            "example": null
                          },
                          "selected_mpn": {
                            "type": "string",
                            "nullable": true,
                            "deprecated": true,
                            "description": "Deprecated; generally `null`.",
                            "example": null
                          },
                          "sourcing_default": {
                            "type": "string",
                            "description": "How this line is sourced: `macrofab` (MacroFab purchases a part from the AVL) or `customer`\n(you supply a part from the AVL). PCB quotes and the ready check use it. Change it with\n`PUT /api/v3/pcb/{pcb_id}/{pcb_version}/sourcing/defaults`.\n",
                            "enum": [
                              "macrofab",
                              "customer"
                            ],
                            "example": "macrofab"
                          },
                          "input_source_type": {
                            "type": "string",
                            "nullable": true,
                            "description": "How the line was created, if known",
                            "enum": [
                              "xyrs",
                              "xlsx",
                              "manual",
                              null
                            ]
                          },
                          "group_key": {
                            "type": "string",
                            "nullable": true,
                            "deprecated": true,
                            "description": "Deprecated; always `null`. Lines that share a part share an `approved_vendor_list_id`, so\ngroup lines by that instead.\n"
                          },
                          "form_factor": {
                            "type": "object",
                            "nullable": true,
                            "description": "Placement type and pin count, if known",
                            "properties": {
                              "type": {
                                "type": "string",
                                "example": "SMD"
                              },
                              "pins": {
                                "type": "integer",
                                "example": 2
                              }
                            }
                          },
                          "alternate_parts": {
                            "type": "array",
                            "items": {}
                          },
                          "updated": {
                            "type": "string",
                            "description": "When the line was last updated",
                            "example": "2025-10-28 22:26:57"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The PCB or PCB version does not exist, or you do not have access to it",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1api~1v3~1pcb~1{pcb_id}~1{pcb_version}~1bom/get/responses/404/content/application~1json/schema"
                }
              }
            }
          }
        },
        "security": [
          {
            "apikeyHeader": []
          }
        ]
      },
      "parameters": [
        {
          "name": "pcb_id",
          "in": "path",
          "required": true,
          "description": "The PCB ID",
          "schema": {
            "type": "string",
            "example": "mdx0ce"
          }
        },
        {
          "name": "pcb_version",
          "in": "path",
          "required": true,
          "description": "The PCB version number",
          "schema": {
            "type": "integer",
            "example": 1
          }
        }
      ]
    }
  },
  "components": {
    "securitySchemes": {
      "apikeyHeader": {
        "type": "apiKey",
        "name": "X-MacroFab-API-Key",
        "in": "header"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 100,
      "1": 251,
      "2": 93,
      "3": 50,
      "4": 34,
      "5": 139,
      "6": 70,
      "7": 0,
      "8": 113,
      "9": 3,
      "10": 149,
      "11": 120
    }
  }
}
```