> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer-stage.shipbob.dev/experimental/guides/product-catalog/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-stage.shipbob.dev/_mcp/server.

# Product Catalog

> API documentation for managing products through the ShipBob 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:

```plaintext
https://api.shipbob.com/2026-07/
```

## Creating a Product

**Endpoint:** `POST /product`

```json
{
  "name": "Light Roast Coffee",
  "type_id": 1,
  "variants": [
    {
      "name": "Light Roast Coffee",
      "sku": "light-roast",
      "packaging_requirement_id": 1,
      "packaging_material_type_id": 1,
      "barcode": "06547321109",
      "customs": {
        "country_code_of_origin": "US",
        "hs_tariff_code": "6103.22.00",
        "value": "10",
        "description": "coffee"
      }
    }
  ]
}
```

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

```json
{
	"name": "Coffee Bundle",
  "type_id": 2,
  "variants": [
    {
      "bundle_definition": [
        {
          "quantity": 1,
          "variant_id": 16608663
        },
        {
          "quantity": 1,
          "variant_id": 16608664
        },
        {
          "quantity": 1,
          "variant_id": 16608667
        }       
      ],
      "sku": "coffee-bundle"
    }
  ]
}
```

## Creating a Varying Product

**Endpoint:** `POST /product`

```json
{
  "name": "Light Roast Coffee",
  "type_id": 1,
  "taxonomy_id": 266,
  "variants": [
    {
      "name": "Light Roast Coffee - 3 lb",
      "sku": "light-roast-3lb",
      "packaging_requirement_id": 1,
      "packaging_material_type_id": 1,
      "barcode": "06547321110",
      "customs": {
        "country_code_of_origin": "US",
        "hs_tariff_code": "6103.22.00",
        "value": "10",
        "description": "coffee"
      }
    }
  ]
}
```

## Updating Existing Products

**Endpoint:** `PATCH /product/{product-id}`

```json
{
  "variants": [
    {
      "id": 6,
      "barcode": "4324323212",
      "packaging_material_type_id": 6
    },
    {
      "id": 8,
      "name": "Jupiter Shirt (Small)"
    }
  ]
}
```

## Retrieving Products

**Endpoint:** `GET /product`

```plaintext
/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](https://web.shipbob.com/app/merchant/#/product-catalog/taxonomy)

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

```json
{
  "name": "Dark Roast Coffee",
  "type_id": 1,
  "variants": [
    {
      "name": "Dark Roast Coffee",
      "sku": "dark-roast",
      "channel_metadata": [
        {
          "channel_id": 175984,
          "platform": "API",
          "platform_identifier": "SHOPIFY-VARIANT-452198776",
          "seller_sku": "dark-roast"
        }
      ]
    }
  ]
}
```

> **Note**
>
> 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.

> API documentation for managing products through the ShipBob product catalog.