Product Catalog

Overview

This documentation provides an overview and API request examples for creating, retrieving, and modifying products through the ShipBob product catalog.

Base URL

All requests should be directed to the following base URL:

https://api.shipbob.com/2026-01/

Creating a Product

Endpoint: POST /product

1 {
2   "name": "Light Roast Coffee",
3   "type_id": 1,
4   "variants": [
5     {
6       "name": "Light Roast Coffee",
7       "sku": "light-roast",
8       "packaging_requirement_id": 1,
9       "packaging_material_type_id": 1,
10       "barcode": "06547321109",
11       "customs": {
12         "country_code_of_origin": "US",
13         "hs_tariff_code": "6103.22.00",
14         "value": "10",
15         "description": "coffee"
16       }
17     }
18   ]
19 }

Notes

Type ID: 1 indicates a regular product (not a bundle). Use 2 for creating a bundle product.
Taxonomy ID: Categorizes products in the UI. (266 represents “Clothing”).
Packaging Requirement ID: Determines special handling (e.g., 7 for apparel).
Customs Information: Required for international shipments.

Creating a Bundle Product

Endpoint: POST /product

1 {
2 	"name": "Coffee Bundle",
3   "type_id": 2,
4   "variants": [
5     {
6       "bundle_definition": [
7         {
8           "quantity": 1,
9           "variant_id": 16608663
10         },
11         {
12           "quantity": 1,
13           "variant_id": 16608664
14         },
15         {
16           "quantity": 1,
17           "variant_id": 16608667
18         }       
19       ],
20       "sku": "coffee-bundle"
21     }
22   ]
23 }

Creating a Varying Product

Endpoint: POST /product

1 {
2   "name": "Light Roast Coffee",
3   "type_id": 1,
4   "taxonomy_id": 266,
5   "variants": [
6     {
7       "name": "Light Roast Coffee - 3 lb",
8       "sku": "light-roast-3lb",
9       "packaging_requirement_id": 1,
10       "packaging_material_type_id": 1,
11       "barcode": "06547321110",
12       "customs": {
13         "country_code_of_origin": "US",
14         "hs_tariff_code": "6103.22.00",
15         "value": "10",
16         "description": "coffee"
17       }
18     }
19   ]
20 }

Updating Existing Products

Endpoint: PATCH /product/{product-id}

1 {
2   "variants": [
3     {
4       "id": 6,
5       "barcode": "4324323212",
6       "packaging_material_type_id": 6
7     },
8     {
9       "id": 8,
10       "name": "Jupiter Shirt (Small)"
11     }
12   ]
13 }

Retrieving Products

Endpoint: GET /product

/product?productTypeId=1&variantStatus=1&hasDigitalVariants=false

Product Attributes

Product-Level Attributes

Field	Type	Description
`name`	string	Name of the product
`type_id`	int	Regular Product (1) or Bundle (2)
`taxonomy_id`	int	Product category ID

Variant-Level Attributes

Field	Type	Description
`name`	string	Variant name (should match product name for non-varying products)
`status_id`	int	Active (1) or Inactive (2)
`sku`	string	Unique SKU for the variant
`barcode`	string	Barcode for scanning
`packaging_requirement_id`	int	Packaging requirement
`packaging_material_type_id`	int	Packaging material
`is_digital`	boolean	True for digital items
`customs`	object	Customs details for international shipping

Packaging Requirements

ID	Name
1	No Requirements
2	Fragile
3	Foldable
4	Media
5	Book
6	Poster
7	Apparel
8	Packaging Material

Packaging Material Types

ID	Name
1	Box
2	Bubble Mailer
3	Poly Mailer
5	Poster Tube
6	Custom Box
7	Bookfold
8	Ship In Own Container
9	Custom Bubble Mailer
10	Custom Poly Mailer

Taxonomy Values

Taxonomy values can be found using the lookup tool (requires login): ShipBob Taxonomy Lookup

FAQs

How do I pass channel-specific metadata when creating a product?

If your upstream platform uses a different identifier than your ShipBob SKU, send it in channel_metadata[].platform_identifier.

Example:

ShipBob SKU: dark-roast
Upstream identifier (from your platform): SHOPIFY-VARIANT-452198776

When using channel_metadata, make sure:

channel_id is the numeric ID of your ShipBob channel.
platform is API when creating products through your API channel.
platform_identifier is your upstream system’s unique variant/product identifier.
seller_sku can remain your platform-facing SKU if needed.

Endpoint: POST /product

1 {
2   "name": "Dark Roast Coffee",
3   "type_id": 1,
4   "variants": [
5     {
6       "name": "Dark Roast Coffee",
7       "sku": "dark-roast",
8       "channel_metadata": [
9         {
10           "channel_id": 175984,
11           "platform": "API",
12           "platform_identifier": "SHOPIFY-VARIANT-452198776",
13           "seller_sku": "dark-roast"
14         }
15       ]
16     }
17   ]
18 }

If you are not sure which channel_id to use, retrieve your channels first and use the ID for the channel that should own this product mapping.

Overview

This documentation provides an overview and API request examples for creating, retrieving, and modifying products through the ShipBob product catalog.

Base URL

All requests should be directed to the following base URL:

https://api.shipbob.com/2026-01/

Creating a Product

Endpoint: POST /product

1 {
2   "name": "Light Roast Coffee",
3   "type_id": 1,
4   "variants": [
5     {
6       "name": "Light Roast Coffee",
7       "sku": "light-roast",
8       "packaging_requirement_id": 1,
9       "packaging_material_type_id": 1,
10       "barcode": "06547321109",
11       "customs": {
12         "country_code_of_origin": "US",
13         "hs_tariff_code": "6103.22.00",
14         "value": "10",
15         "description": "coffee"
16       }
17     }
18   ]
19 }

Notes

Type ID: 1 indicates a regular product (not a bundle). Use 2 for creating a bundle product.
Taxonomy ID: Categorizes products in the UI. (266 represents “Clothing”).
Packaging Requirement ID: Determines special handling (e.g., 7 for apparel).
Customs Information: Required for international shipments.

Creating a Bundle Product

Endpoint: POST /product

1 {
2 	"name": "Coffee Bundle",
3   "type_id": 2,
4   "variants": [
5     {
6       "bundle_definition": [
7         {
8           "quantity": 1,
9           "variant_id": 16608663
10         },
11         {
12           "quantity": 1,
13           "variant_id": 16608664
14         },
15         {
16           "quantity": 1,
17           "variant_id": 16608667
18         }       
19       ],
20       "sku": "coffee-bundle"
21     }
22   ]
23 }

Creating a Varying Product

Endpoint: POST /product

1 {
2   "name": "Light Roast Coffee",
3   "type_id": 1,
4   "taxonomy_id": 266,
5   "variants": [
6     {
7       "name": "Light Roast Coffee - 3 lb",
8       "sku": "light-roast-3lb",
9       "packaging_requirement_id": 1,
10       "packaging_material_type_id": 1,
11       "barcode": "06547321110",
12       "customs": {
13         "country_code_of_origin": "US",
14         "hs_tariff_code": "6103.22.00",
15         "value": "10",
16         "description": "coffee"
17       }
18     }
19   ]
20 }

Updating Existing Products

Endpoint: PATCH /product/{product-id}

1 {
2   "variants": [
3     {
4       "id": 6,
5       "barcode": "4324323212",
6       "packaging_material_type_id": 6
7     },
8     {
9       "id": 8,
10       "name": "Jupiter Shirt (Small)"
11     }
12   ]
13 }

Retrieving Products

Endpoint: GET /product

/product?productTypeId=1&variantStatus=1&hasDigitalVariants=false

Product Attributes

Product-Level Attributes

Field	Type	Description
`name`	string	Name of the product
`type_id`	int	Regular Product (1) or Bundle (2)
`taxonomy_id`	int	Product category ID

Variant-Level Attributes

Field	Type	Description
`name`	string	Variant name (should match product name for non-varying products)
`status_id`	int	Active (1) or Inactive (2)
`sku`	string	Unique SKU for the variant
`barcode`	string	Barcode for scanning
`packaging_requirement_id`	int	Packaging requirement
`packaging_material_type_id`	int	Packaging material
`is_digital`	boolean	True for digital items
`customs`	object	Customs details for international shipping

Packaging Requirements

ID	Name
1	No Requirements
2	Fragile
3	Foldable
4	Media
5	Book
6	Poster
7	Apparel
8	Packaging Material

Packaging Material Types

ID	Name
1	Box
2	Bubble Mailer
3	Poly Mailer
5	Poster Tube
6	Custom Box
7	Bookfold
8	Ship In Own Container
9	Custom Bubble Mailer
10	Custom Poly Mailer

Taxonomy Values

Taxonomy values can be found using the lookup tool (requires login): ShipBob Taxonomy Lookup

FAQs

How do I pass channel-specific metadata when creating a product?

If your upstream platform uses a different identifier than your ShipBob SKU, send it in channel_metadata[].platform_identifier.

Example:

ShipBob SKU: dark-roast
Upstream identifier (from your platform): SHOPIFY-VARIANT-452198776

When using channel_metadata, make sure:

channel_id is the numeric ID of your ShipBob channel.
platform is API when creating products through your API channel.
platform_identifier is your upstream system’s unique variant/product identifier.
seller_sku can remain your platform-facing SKU if needed.

Endpoint: POST /product

1 {
2   "name": "Dark Roast Coffee",
3   "type_id": 1,
4   "variants": [
5     {
6       "name": "Dark Roast Coffee",
7       "sku": "dark-roast",
8       "channel_metadata": [
9         {
10           "channel_id": 175984,
11           "platform": "API",
12           "platform_identifier": "SHOPIFY-VARIANT-452198776",
13           "seller_sku": "dark-roast"
14         }
15       ]
16     }
17   ]
18 }

If you are not sure which channel_id to use, retrieve your channels first and use the ID for the channel that should own this product mapping.

1	{
2	"name": "Light Roast Coffee",
3	"type_id": 1,
4	"variants": [
5	{
6	"name": "Light Roast Coffee",
7	"sku": "light-roast",
8	"packaging_requirement_id": 1,
9	"packaging_material_type_id": 1,
10	"barcode": "06547321109",
11	"customs": {
12	"country_code_of_origin": "US",
13	"hs_tariff_code": "6103.22.00",
14	"value": "10",
15	"description": "coffee"
16	}
17	}
18	]
19	}

1	{
2	"name": "Coffee Bundle",
3	"type_id": 2,
4	"variants": [
5	{
6	"bundle_definition": [
7	{
8	"quantity": 1,
9	"variant_id": 16608663
10	},
11	{
12	"quantity": 1,
13	"variant_id": 16608664
14	},
15	{
16	"quantity": 1,
17	"variant_id": 16608667
18	}
19	],
20	"sku": "coffee-bundle"
21	}
22	]
23	}

1	{
2	"name": "Light Roast Coffee",
3	"type_id": 1,
4	"taxonomy_id": 266,
5	"variants": [
6	{
7	"name": "Light Roast Coffee - 3 lb",
8	"sku": "light-roast-3lb",
9	"packaging_requirement_id": 1,
10	"packaging_material_type_id": 1,
11	"barcode": "06547321110",
12	"customs": {
13	"country_code_of_origin": "US",
14	"hs_tariff_code": "6103.22.00",
15	"value": "10",
16	"description": "coffee"
17	}
18	}
19	]
20	}

1	{
2	"variants": [
3	{
4	"id": 6,
5	"barcode": "4324323212",
6	"packaging_material_type_id": 6
7	},
8	{
9	"id": 8,
10	"name": "Jupiter Shirt (Small)"
11	}
12	]
13	}

1	{
2	"name": "Dark Roast Coffee",
3	"type_id": 1,
4	"variants": [
5	{
6	"name": "Dark Roast Coffee",
7	"sku": "dark-roast",
8	"channel_metadata": [
9	{
10	"channel_id": 175984,
11	"platform": "API",
12	"platform_identifier": "SHOPIFY-VARIANT-452198776",
13	"seller_sku": "dark-roast"
14	}
15	]
16	}
17	]
18	}