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

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

**filters** `null | object`

* `null` - Retrieve list of all products.
* `object` - Retrieve list of products using specified [Search Filters](https://docs.shipstream.io/merchant-api/search-filters.md).
  Allowed properties for filtering: "sku", "vendor\_sku", "manufacturer\_part\_number", "status", "availability", "visibility", "created\_at", "updated\_at", "external\_id".

**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 [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

**sku** `string`

Product SKU.

**productData** `object`

Product data.

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

**sku** `string`

Product SKU.

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

**sku** `string`

Product SKU.

**productData** `object`

Product data.

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

**Product Properties**

**sku** `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.

**name** `string`

The "Name" property.

**export\_description** `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.

**barcode** `string`

The "Barcode" property. Single or comma separated barcodes.

**goods\_type** `string`

The "Goods Type" property. Allowed: "NORMAL", "ORM\_D", "LIMITED\_QUANTITIES\_COMMODITIES", "HAZMAT".

**status** `integer`

The "Status" property. Allowed: "0" - Disabled, "1" - Enabled.

**availability** `integer`

The "Availability" property. Allowed: "1" - available. "2" - not available.

**visibility** `integer`

The "Visibility" property. Allowed: "1" - not visible, "2" - visible.

**weight** `number`

The "Weight" property.

**weight\_unit** `string`

The unit of measure used for `weight`. See: [Weight Units](https://docs.shipstream.io/merchant-api/units-of-measure.md#weight).

**length** `number`

The "Length" property.

**width** `number`

The "Width" property.

**height** `number`

The "Height" property.

**dimension\_unit** `string`

The unit of measure used for `length`, `width`, and `height`. See: [Length Units](https://docs.shipstream.io/merchant-api/units-of-measure.md#length). Note that this field is shared between `length`, `width`, and `height`; updating a single dimension will change the unit for all three.

**freight\_class** `string`

The "Freight Class" property.

**freight\_category** `string`

The "Freight Category" property.

**unit\_level** `string`

The "Unit Level" property: the packaging level of the Product within its quantity Bill of Materials family.
Allowed: "each", "inner\_pack", "case", "pallet", or an empty value to clear it. `null` in responses when not set.
A Replenishment Policy's Move In level uses it to choose the related Product a replenishment task moves in. A
create or update is refused when the level contradicts the sizes in the quantity family, for example a Product
declared "pallet" that holds fewer units than a related Product declared "case".

**customs\_value** `string`

The "Customs Value" property. The declared customs value per unit as a number with up to 4 decimal places.
Required for international shipping.

**customs\_value\_currency** `string`

The currency of the "Customs Value" property. Must be a valid ISO 4217 alphabetic code (e.g. "USD").

**customs\_value\_usd** `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`.

**country\_of\_manufacture** `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.

**hs\_base\_code** `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.

**hs\_country\_extension** `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.

**hts\_base\_code** `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`.

**hts\_country\_code** `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.

**requires\_packaging** `integer`

The "Requires Packaging" property. Allowed: "0" - not required. "1" - required.

**can\_contain\_other\_items** `integer`

The "Can Contain Other Items" property. Allowed: "0" - cannot contain other items. "1" - can contain other items.

**valid\_containers** `array`

The "Valid Containers" property. An array of SKUs for valid containers.

**special\_supplies** `array`

The "Special Supplies" property. An array of SKUs for special packaging supplies.

**special\_other** `array`

The "Other Special Features" property. An array of SKUs for other special packaging features.

**unit\_qty** `integer`

The "Unit Quantity" property. Number of individually packaged items contained therein for purposes of special packaging features.

**external\_id** `integer`

The "External ID" property. The external unique numeric identifier for the product.

**vendor\_sku** `string`

The "Vendor SKU" property. Use if different from the "SKU" property.

**manufacturer\_part\_number** `string`

The "Manufacturer Part Number" property. The manufacturer's part number for the item; may be required for
customs on shipments to EU countries.


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