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

# Product

Each merchant maintains a completely unique catalog of products managed at ShipStream whether in stock or not. It is preferable that a merchant creates all of their products with accurate names, goods type and barcodes before actually shipping physical inventory to aid in accurate processing of deliveries.

## Methods

* [product.search](#product-search)
* [product.create](#product-create)
* [product.info](#product-info)
* [product.update](#product-update)

***

## Entity Properties

* [Product](#product-properties)

***

## `product.search`

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

Retrieve list of products with basic info (id, sku, type, set, name).

### Parameters

<ParamField path="filters" type="null | object">
  * `null` - Retrieve list of all products.
  * `object` - Retrieve list of products using specified [Search Filters](/merchant-api/search-filters).
    Allowed properties for filtering: "sku", "vendor\_sku", "status", "availability", "visibility", "created\_at", "updated\_at", "external\_id".
</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 [Product Properties](#product-properties).

### Example Request

Get product information for one product SKU:

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

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : [
        {
            "sku" : "productsku",
            "name" : "product name",
            "barcode" : "productbarcode",
            "goods_type" : "NORMAL",
            "status" : 1,
            "availability" : 1,
            "visibility" : 2,
            "weight" : 12.75,
            "weight_unit" : "lb",
            "length" : null,
            "width" : null,
            "height" : null,
            "customs_value" : "24.5600",
            "customs_value_currency" : "USD",
            "country_of_manufacture" : "DK",
            "hts_base_code" : 1234.56,
            "hts_country_code" : [
                {
                    "country_id" : "BB",
                    "extension" : "01"
                },
                {
                    "country_id" : "FO",
                    "extension" : "02"
                }
            ],
            "vendor_sku" : "vendorsku",
            "requires_packaging" : 1,
            "can_contain_other_items" : 0,
            "valid_containers" : ["containersku1", "containersku2"],
            "special_supplies" : [ "supplysku1", "supplysku2" ],
            "special_other" : [ "specialsku1", "specialsku2" ],
            "unit_qty" : 5
        }
    ]
}
```

### Error Codes

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

***

## `product.create`

`product.create (string $sku, object $productData)`

Create new product.

### Parameters

<ParamField path="sku" type="string">
  Product SKU.
</ParamField>

<ParamField path="productData" type="object">
  Product data.
</ParamField>

### Return Value

`true` if product was successfully created.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product.create",
        [
            "product3",
            {
                "name" : "Product 3",
                "barcode" : "product3",
                "goods_type" : "NORMAL",
                "weight" : 1.75,
                "weight_unit": "lb",
                "length" : 123,
                "width" : 100,
                "height" : 28,
                "dimension_unit" : "in",
                "customs_value" : "24.5600",
                "customs_value_currency" : "USD",
                "country_of_manufacture" : "DK",
                "hts_base_code" : 1234.56,
                "hts_country_code" : "BH:1000|ZW:1001",
                "vendor_sku" : "vendorsku",
                "requires_packaging" : 1,
                "can_contain_other_items" : 1,
                "valid_containers" : [ "containersku1", "containersku2" ],
                "special_supplies" : [ "supplysku1", "supplysku2" ],
                "special_other" : [ "specialsku1", "specialsku2" ],
                "unit_qty" : 5
            }
        ]
    ]
}
```

### Example Response

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

### Error Codes

| code | message                                                       |
| ---- | ------------------------------------------------------------- |
| 102  | Invalid data given. Details in error message.                 |
| 104  | Product type is not in allowed types.                         |
| 105  | Product's attribute set does not exist.                       |
| 106  | Product's attribute set is not a Catalog Product entity type. |
| 107  | Another product with this SKU already exists.                 |

***

## `product.info`

`product.info (string $sku)`

Retrieve product info.

### Parameters

<ParamField path="sku" type="string">
  Product SKU.
</ParamField>

### Return Value

Object with [Product Properties](#product-properties).

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product.info",
        [
            "product1"
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "sku" : "productsku",
        "name" : "product name",
        "barcode" : "productbarcode",
        "goods_type" : "NORMAL",
        "status" : 1,
        "availability" : 1,
        "visibility" : 2,
        "weight" : 12.75,
        "weight_unit" : "lb",
        "length" : null,
        "width" : null,
        "height" : null,
        "dimension_unit" : "in",
        "customs_value" : "24.5600",
        "customs_value_currency" : "USD",
        "country_of_manufacture" : "DK",
        "hts_base_code" : 1234.56,
        "hts_country_code" : [
            {
                "country_id" : "BB",
                "extension" : "01"
            },
            {
                "country_id" : "FO",
                "extension" : "02"
            }
        ],
        "vendor_sku" : "vendorsku",
        "requires_packaging" : 1,
        "can_contain_other_items" : 0,
        "valid_containers" : [ "containersku1", "containersku2" ],
        "special_supplies" : [ "supplysku1", "supplysku2" ],
        "special_other" : [ "othersku1", "othersku2" ],
        "unit_qty" : 5
    }
}
```

### Error Codes

| code | message             |
| ---- | ------------------- |
| 101  | Product not exists. |

***

## `product.update`

`product.update (string $sku, object $productData)`

Update product data.

### Parameters

<ParamField path="sku" type="string">
  Product SKU.
</ParamField>

<ParamField path="productData" type="object">
  Product data.
</ParamField>

### Return Value

`true` if product was successfully updated.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product.update",
        [
            "product3",
            {
                "name" : "product name",
                "barcode" : "productbarcode",
                "goods_type" : "NORMAL",
                "status" : 1,
                "availability" : 1,
                "visibility" : 2,
                "weight" : 12.75,
                "weight_unit" : "lb",
                "length" : null,
                "width" : null,
                "height" : null,
                "dimension_unit" : "lb",
                "customs_value" : "24.5600",
                "customs_value_currency" : "USD",
                "country_of_manufacture" : "DK",
                "hts_base_code" : 1234.56,
                "hts_country_code" : [
                    {
                        "country_id" : "BB",
                        "extension" : "01"
                    },
                    {
                        "country_id" : "FO",
                        "extension" : "02"
                    }
                ],
                "vendor_sku" : "vendorsku",
                "requires_packaging" : 1,
                "can_contain_other_items" : 0,
                "valid_containers" : [ "containersku1", "containersku2" ],
                "special_supplies" : [ "supplysku1", "supplysku2" ],
                "special_other" : [ "specialsku1", "specialsku2" ],
                "unit_qty" : 5
            }
        ]
    ]
}
```

### Example Response

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

### Error Codes

| code | message                                       |
| ---- | --------------------------------------------- |
| 101  | Product not exists.                           |
| 102  | Invalid data given. Details in error message. |

***

## Entity Properties

### Product Properties

<Expandable title="Product Properties">
  <ParamField path="sku" type="string">
    A unique identifier for a product. The SKU does appear on the packing slip. It is recommended that this be human-readable and end with a per-pack quantity to facilitate proper receiving. For example, a single blue widget may be "BlueWidget-1" and a pack of 5 blue widgets may be "BlueWidget-5". Maximum character length is 64.
  </ParamField>

  <ParamField path="name" type="string">
    The "Name" property.
  </ParamField>

  <ParamField path="export_description" type="string">
    Harmonized Tariff Schedule article description.
  </ParamField>

  <ParamField path="barcode" type="string">
    The "Barcode" property. Single or comma separated barcodes.
  </ParamField>

  <ParamField path="goods_type" type="string">
    The "Goods Type" property. Allowed: "NORMAL", "ORM\_D", "LIMITED\_QUANTITIES\_COMMODITIES", "HAZMAT".
  </ParamField>

  <ParamField path="status" type="integer">
    The "Status" property. Allowed: "0" - Disabled, "1" - Enabled.
  </ParamField>

  <ParamField path="availability" type="integer">
    The "Availability" property. Allowed: "1" - available. "2" - not available.
  </ParamField>

  <ParamField path="visibility" type="integer">
    The "Visibility" property. Allowed: "1" - not visible, "2" - visible.
  </ParamField>

  <ParamField path="weight" type="number">
    The "Weight" property.
  </ParamField>

  <ParamField path="weight_unit" type="string">
    The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
  </ParamField>

  <ParamField path="length" type="number">
    The "Length" property.
  </ParamField>

  <ParamField path="width" type="number">
    The "Width" property.
  </ParamField>

  <ParamField path="height" type="number">
    The "Height" property.
  </ParamField>

  <ParamField path="dimension_unit" type="string">
    The unit of measure used for `length`, `width`, and `height`. See: [Length Units](/merchant-api/units-of-measure#length). Note that this field is shared between `length`, `width`, and `height`; updating a single dimension will change the unit for all three.
  </ParamField>

  <ParamField path="freight_class" type="string">
    The "Freight Class" property.
  </ParamField>

  <ParamField path="freight_category" type="string">
    The "Freight Category" property.
  </ParamField>

  <ParamField path="customs_value" type="string">
    The "Customs Value" property.
  </ParamField>

  <ParamField path="customs_value_currency" type="string">
    The currency of the "Customs Value" property. Must be a valid ISO 4217 alphabetic code.
  </ParamField>

  <ParamField path="country_of_manufacture" type="string">
    The "Country of Manufacture" property.
  </ParamField>

  <ParamField path="hts_base_code" type="number">
    The "HTS Base Code" property.
  </ParamField>

  <ParamField path="hts_country_code" type="string">
    The "HTS Country Code" property. Format: "{COUNTRY}:{CODE}". Separator: "|".
  </ParamField>

  <ParamField path="requires_packaging" type="integer">
    The "Requires Packaging" property. Allowed: "0" - not required. "1" - required.
  </ParamField>

  <ParamField path="can_contain_other_items" type="integer">
    The "Can Contain Other Items" property. Allowed: "0" - cannot contain other items. "1" - can contain other items.
  </ParamField>

  <ParamField path="valid_containers" type="array">
    The "Valid Containers" property. An array of SKUs for valid containers.
  </ParamField>

  <ParamField path="special_supplies" type="array">
    The "Special Supplies" property. An array of SKUs for special packaging supplies.
  </ParamField>

  <ParamField path="special_other" type="array">
    The "Other Special Features" property. An array of SKUs for other special packaging features.
  </ParamField>

  <ParamField path="unit_qty" type="integer">
    The "Unit Quantity" property. Number of individually packaged items contained therein for purposes of special packaging features.
  </ParamField>

  <ParamField path="external_id" type="integer">
    The "External ID" property. The external unique numeric identifier for the product.
  </ParamField>

  <ParamField path="vendor_sku" type="string">
    The "Vendor SKU" property. Use if different from the "SKU" property.
  </ParamField>
</Expandable>