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.

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 for details.

Entity Properties

Product

`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

null | object

null - Retrieve list of all products.
object - Retrieve list of products using specified Search Filters. Allowed properties for filtering: “sku”, “vendor_sku”, “manufacturer_part_number”, “status”, “availability”, “visibility”, “created_at”, “updated_at”, “external_id”.

null | array

null - No options will be applied.
object - Apply specified Search Options.

Return Value

An array of objects. Each object will contain Product Properties.

Example Request

Get product information for one product SKU:

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product.search",
        [
            {
                "sku" : { "eq" : "product2" }
            }
        ]
    ]
}

Example Response

Response

{
    "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

string

Product SKU.

object

Product data.

Return Value

true if product was successfully created.

Example Request

Request

{
    "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

Response

{
    "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

string

Product SKU.

Return Value

Object with Product Properties.

Example Request

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product.info",
        [
            "product1"
        ]
    ]
}

Example Response

Response

{
    "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

string

Product SKU.

object

Product data.

Return Value

true if product was successfully updated.

Example Request

Request

{
    "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

Response

{
    "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

Show Product Properties

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.

string

The “Name” property.

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.

string

The “Barcode” property. Single or comma separated barcodes.

string

The “Goods Type” property. Allowed: “NORMAL”, “ORM_D”, “LIMITED_QUANTITIES_COMMODITIES”, “HAZMAT”.

integer

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

integer

The “Availability” property. Allowed: “1” - available. “2” - not available.

integer

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

number

The “Weight” property.

string

The unit of measure used for weight. See: Weight Units.

number

The “Length” property.

number

The “Width” property.

number

The “Height” property.

string

The unit of measure used for length, width, and height. See: Length Units. Note that this field is shared between length, width, and height; updating a single dimension will change the unit for all three.

string

The “Freight Class” property.

string

The “Freight Category” property.

string

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

string

The currency of the “Customs Value” property. Must be a valid ISO 4217 alphabetic code (e.g. “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.

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.

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/. Required for international shipping.

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.

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.

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.

integer

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

integer

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

array

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

array

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

array

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

integer

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

integer

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

string

The “Vendor SKU” property. Use if different from the “SKU” property.

string

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

Get Started

Common Features

Shipping

Receiving

Inventory

System

Methods

Entity Properties

`product.search`

Parameters

Return Value

Example Request

Example Response

Error Codes

`product.create`

Parameters

Return Value

Example Request

Example Response

Error Codes

`product.info`

Parameters

Return Value

Example Request

Example Response

Error Codes

`product.update`

Parameters

Return Value

Example Request

Example Response

Error Codes

Entity Properties

Product Properties

​Methods

​Entity Properties

​product.search

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​product.create

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​product.info

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​product.update

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​Entity Properties

​Product Properties

Methods

Entity Properties

`product.search`

Parameters

Return Value

Example Request

Example Response

Error Codes

`product.create`

Parameters

Return Value

Example Request

Example Response

Error Codes

`product.info`

Parameters

Return Value

Example Request

Example Response

Error Codes

`product.update`

Parameters

Return Value

Example Request

Example Response

Error Codes

Entity Properties

Product Properties