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

**filters** `null | object`

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

**options** `null | array`

* `null` - No options will be applied.
* `object` - Apply specified [Search Options](https://docs.shipstream.io/merchant-api/search-options.md).

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

**bomData** `object`

BOM data.

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

**bomId** `integer`

BOM ID.

**bomData** `object`

BOM data.
Allowed properties for update are the same as the create method.

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

**bomId** `integer`

BOM ID.

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

**BOM Properties**

**product\_bom\_id** `integer`

An automatically generated unique identifier for a BOM.

**name** `string`

A descriptive name to indicate what action a BOM will take.

**sku** `string`

The product SKU that will be substituted by the BOM components.

**yield\_qty** `integer`

The number of product units produced by the BOM. A positive integer.

**is\_kit\_on\_demand** `string`

If this option is true, order items will automatically be substituted by the BOM during warehouse allocation. Allowed: "1" - TRUE, "0" - FALSE

**is\_kit\_to\_stock** `string`

If this option is true, the BOM will be available for use with a Work Order. Allowed: "1" - TRUE, "0" - FALSE

**assembly\_instructions** `string`

Instructions for assembling the BOM.

**priority** `integer`

If multiple BOMs are defined for a SKU, then they will be processed in ascending order of this field. An integer.

**components** `array`

A list of [BOM component objects](#bom-component-properties).

### BOM Component Properties

**BOM Component Properties**

**bom\_child\_id** `integer`

An automatically generated unique identifier for a BOM component.

**product\_bom\_id** `integer`

The unique identifier of the parent BOM of the component item.

**sku** `string`

The product SKU of the component.

**qty** `integer`

The quantity of the component item consumed by the BOM. A positive integer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.