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

<Note>
  The canonical field names for the Harmonized System code fields are `hs_base_code` ("Harmonized System Code") and
  `hs_country_extension` ("HS Code Extensions"). The legacy `hts_base_code` and `hts_country_code` field names remain
  accepted as input aliases indefinitely, and responses include both the canonical and legacy keys for backwards
  compatibility. If both a legacy alias and its canonical `hs_*` field are supplied in the same request, the canonical
  `hs_*` value wins. See [Product Properties](#product-properties) for details.
</Note>

## 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", "manufacturer\_part\_number", "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",
            "hs_base_code" : "8471.30",
            "hs_country_extension" : [
                {
                    "country_id" : "US",
                    "extension" : "0010"
                },
                {
                    "country_id" : "CA",
                    "extension" : "0020"
                }
            ],
            "hts_base_code" : "8471.30",
            "hts_country_code" : [
                {
                    "country_id" : "US",
                    "extension" : "0010"
                },
                {
                    "country_id" : "CA",
                    "extension" : "0020"
                }
            ],
            "vendor_sku" : "vendorsku",
            "manufacturer_part_number" : "manufacturerpartnumber",
            "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",
                "hs_base_code" : "8471.30",
                "hs_country_extension" : "US:0010|CA:0020",
                "vendor_sku" : "vendorsku",
                "manufacturer_part_number" : "manufacturerpartnumber",
                "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",
        "hs_base_code" : "8471.30",
        "hs_country_extension" : [
            {
                "country_id" : "US",
                "extension" : "0010"
            },
            {
                "country_id" : "CA",
                "extension" : "0020"
            }
        ],
        "hts_base_code" : "8471.30",
        "hts_country_code" : [
            {
                "country_id" : "US",
                "extension" : "0010"
            },
            {
                "country_id" : "CA",
                "extension" : "0020"
            }
        ],
        "vendor_sku" : "vendorsku",
        "manufacturer_part_number" : "manufacturerpartnumber",
        "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" : "in",
                "customs_value" : "24.5600",
                "customs_value_currency" : "USD",
                "country_of_manufacture" : "DK",
                "hs_base_code" : "8471.30",
                "hs_country_extension" : [
                    {
                        "country_id" : "US",
                        "extension" : "0010"
                    },
                    {
                        "country_id" : "CA",
                        "extension" : "0020"
                    }
                ],
                "vendor_sku" : "vendorsku",
                "manufacturer_part_number" : "manufacturerpartnumber",
                "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">
    The "Export Description" property. A detailed description of the product used for international shipping and
    customs declarations (e.g. on commercial invoices). Required for international shipping.
  </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. The declared customs value per unit as a number with up to 4 decimal places.
    Required for international shipping.
  </ParamField>

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

  <ParamField path="customs_value_usd" type="string" deprecated>
    Deprecated alias of `customs_value`, retained for backwards compatibility. Accepted as input only when
    `customs_value` is not supplied, and included in responses alongside `customs_value`.
  </ParamField>

  <ParamField path="country_of_manufacture" type="string">
    The "Country of Manufacture" property. The two-letter ISO 3166-1 alpha-2 code of the country where the product
    was manufactured (e.g. "DK"). Required for international shipping.
  </ParamField>

  <ParamField path="hs_base_code" type="string">
    The "Harmonized System Code" property. The 6-digit Harmonized System (HS) code that classifies the product for
    international trade, formatted `####.##` (e.g. "8471.30"), not including any country-specific extensions. This
    code can be found using a search tool such as [https://hts.usitc.gov/](https://hts.usitc.gov/). Required for
    international shipping.
  </ParamField>

  <ParamField path="hs_country_extension" type="string | array">
    The "HS Code Extensions" property. Country-specific extensions to the 6-digit Harmonized System code — for
    imports into the United States this is the last 4 digits of the 10-digit HTS (Harmonized Tariff Schedule) code.

    As input, either a string in the format `"{COUNTRY}:{CODE}"` with multiple entries separated by the pipe
    character (e.g. `"US:0010|CA:0020"`), or an array of objects each having `country_id` and `extension`
    properties. `{COUNTRY}` (`country_id`) is the two-letter ISO 3166-1 alpha-2 code of the import country and
    `{CODE}` (`extension`) is that country's extension digits.

    In responses this property is returned as an array of objects with `country_id` and `extension` properties.
  </ParamField>

  <ParamField path="hts_base_code" type="string" deprecated>
    Deprecated alias of `hs_base_code`, retained for backwards compatibility. Accepted as input indefinitely
    (ignored when `hs_base_code` is also supplied) and included in responses alongside `hs_base_code`.
  </ParamField>

  <ParamField path="hts_country_code" type="string | array" deprecated>
    Deprecated alias of `hs_country_extension`, retained for backwards compatibility. Accepted as input indefinitely
    (ignored when `hs_country_extension` is also supplied) and included in responses alongside
    `hs_country_extension`. The alias `hs_country_code` is also tolerated as input.
  </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>

  <ParamField path="manufacturer_part_number" type="string">
    The "Manufacturer Part Number" property. The manufacturer's part number for the item; may be required for
    customs on shipments to EU countries.
  </ParamField>
</Expandable>