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

# Bill of Materials

A Bill of Materials (BOM) defines a relationship between one SKU and a set of component SKUs. For instance, a SKU "Widget-A" could be made up of of three components "Component-A", "Component-B", "Component-C". Placing an order for SKU "Widget-A" would result in "Component-A", "Component-B", "Component-C" automatically being fulfilled in it's place.

BOMs can also define relationships between similar products in different pack/case sizes. For example if "ProductA-12" is a case of 12 single products, and "ProductA-1" is 1 single product from a case of "ProductA-12", then a BOM relationship could be created to allow orders for "ProductA-1" to be fulfilled by splitting a case of "ProductA-12", which would avoid having dedicated inventory for "ProductA-1".

## Methods

* [bom.search](#bom-search)
* [bom.create](#bom-create)
* [bom.update](#bom-update)
* [bom.delete](#bom-delete)

***

## Entity Properties

* [BOM](#bom-properties)
* [BOM Component](#bom-component-properties)

***

## `bom.search`

`bom.search(null|object $filters = null, null|array $options = null)`

Retrieve list of BOMs.

### Parameters

<ParamField path="filters" type="null | object">
  * `null` - Retrieve list of all BOMs.
  * `object` - Retrieve list of BOMs using specified [Search Filters](/merchant-api/search-filters).
    Allowed properties for filtering: "product\_bom\_id", "sku", "name", "yield\_qty", "is\_kit\_on\_demand", "is\_kit\_to\_stock", "assembly\_instructions", "priority".
</ParamField>

<ParamField path="options" type="null | array">
  * `null` - No options will be applied.
  * `object` - Apply specified [Search Options](/merchant-api/search-options).
</ParamField>

### Return Value

An array of objects. Each object will contain [Bom Properties](#bom-properties).

### Example Request

Get list of BOMs for one product SKU:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "bom.search",
        [
            {
                "sku" : { "eq" : "product2" }
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : [
        {
            "product_bom_id" : 73,
            "name" : "Build Product2",
            "sku" : "product2",
            "yield_qty" : 1,
            "is_kit_on_demand" : 1,
            "is_kit_to_stock" : 0,
            "assembly_instructions" : "",
            "priority" : 0,
            "components" : [
                {
                    "bom_child_id" : 211,
                    "product_bom_id" : 73,
                    "sku" : "product2_PartA",
                    "qty" : 1
                },
                {
                    "bom_child_id" : 212,
                    "product_bom_id" : 73,
                    "sku" : "product2_PartB",
                    "qty" : 1
                }
            ]
        }
    ]
}
```

### Error Codes

| code | message                                          |
| ---- | ------------------------------------------------ |
| 104  | Invalid filters given. Details in error message. |

***

## `bom.create`

`bom.create (object $bomData)`

Create new BOM.

### Parameters

<ParamField path="bomData" type="object">
  BOM data.
</ParamField>

### Return Value

BOM object if successful.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "bom.create",
        [
            {
                "name" : "Build Product2",
                "sku" : "product2",
                "yield_qty" : 1,
                "is_kit_on_demand" : 1,
                "assembly_instructions" : "",
                "priority" : 0,
                "components" : [
                    {
                        "sku" : "product2_PartA",
                        "qty" : 1
                    },
                    {
                        "sku" : "product2_PartB",
                        "qty" : 1
                    }
                ]
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "product_bom_id" : 73,
        "name" : "Build Product2",
        "sku" : "product2",
        "yield_qty" : 1,
        "is_kit_on_demand" : 1,
        "is_kit_to_stock" : 0,
        "assembly_instructions" : "",
        "priority" : 0,
        "components" : [
            {
                "bom_child_id" : 211,
                "product_bom_id" : 73,
                "sku" : "product2_PartA",
                "qty" : 1
            },
            {
                "bom_child_id" : 212,
                "product_bom_id" : 73,
                "sku" : "product2_PartB",
                "qty" : 1
            }
        ]
    }
}
```

### Error Codes

| code | message                                       |
| ---- | --------------------------------------------- |
| 102  | Invalid data given. Details in error message. |
| 105  | Product does not exist.                       |

***

## `bom.update`

`bom.update (int $bomId, object $bomData)`

Update BOM data.

### Parameters

<ParamField path="bomId" type="integer">
  BOM ID.
</ParamField>

<ParamField path="bomData" type="object">
  BOM data.
  Allowed properties for update are the same as the create method.
</ParamField>

### Return Value

`true` if BOM was successfully updated.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "bom.update",
        [
            "73",
            {
                "is_kit_on_demand" : 0
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : true
}
```

***

## `bom.delete`

`bom.delete (int $bomId)`

Delete a BOM. A BOM can only be deleted if it is not currently in use by any sales orders or deliveries.

### Parameters

<ParamField path="bomId" type="integer">
  BOM ID.
</ParamField>

### Return Value

`true` if BOM was successfully deleted.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "bom.delete",
        [
            "73"
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : true
}
```

### Error Codes

| code | message             |
| ---- | ------------------- |
| 101  | BOM does not exist. |

## Entity Properties

### BOM Properties

<Expandable title="BOM Properties">
  <ParamField path="product_bom_id" type="integer">
    An automatically generated unique identifier for a BOM.
  </ParamField>

  <ParamField path="name" type="string">
    A descriptive name to indicate what action a BOM will take.
  </ParamField>

  <ParamField path="sku" type="string">
    The product SKU that will be substituted by the BOM components.
  </ParamField>

  <ParamField path="yield_qty" type="integer">
    The number of product units produced by the BOM. A positive integer.
  </ParamField>

  <ParamField path="is_kit_on_demand" type="string">
    If this option is true, order items will automatically be substituted by the BOM during warehouse allocation. Allowed: "1" - TRUE, "0" - FALSE
  </ParamField>

  <ParamField path="is_kit_to_stock" type="string">
    If this option is true, the BOM will be available for use with a Work Order. Allowed: "1" - TRUE, "0" - FALSE
  </ParamField>

  <ParamField path="assembly_instructions" type="string">
    Instructions for assembling the BOM.
  </ParamField>

  <ParamField path="priority" type="integer">
    If multiple BOMs are defined for a SKU, then they will be processed in ascending order of this field. An integer.
  </ParamField>

  <ParamField path="components" type="array">
    A list of [BOM component objects](#bom-component-properties).
  </ParamField>
</Expandable>

### BOM Component Properties

<Expandable title="BOM Component Properties">
  <ParamField path="bom_child_id" type="integer">
    An automatically generated unique identifier for a BOM component.
  </ParamField>

  <ParamField path="product_bom_id" type="integer">
    The unique identifier of the parent BOM of the component item.
  </ParamField>

  <ParamField path="sku" type="string">
    The product SKU of the component.
  </ParamField>

  <ParamField path="qty" type="integer">
    The quantity of the component item consumed by the BOM. A positive integer.
  </ParamField>
</Expandable>