**版本：202601**

# 创建商品

**POST** `/openapi/2026-01/products`

根据提供的信息创建一个新商品。

## 请求

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `product` object (required)

  待创建的商品数据

  - `title` string (required)

    商品名称
  - `brief` string

    商品简要描述
  - `description` string

    商品描述
  - `published` boolean

    商品是否已上架
  - `requires_shipping` boolean

    商品是否需要物流
  - `taxable` boolean

    商品是否需要计税
  - `tags` string[]

    商品标签列表
  - `vendor` string

    供应商名称
  - `vendor_url` string

    供应商 URL
  - `note` string

    自定义备注，例如："This is a customizable product"
  - `seo_title` string

    SEO 标题
  - `seo_description` string

    SEO 描述
  - `seo_keywords` string[]

    SEO 关键词列表
  - `handle` string

    商品 handle（用于 URL 的友好别名）
  - `has_only_default_variant` boolean (required)

    是否仅有默认款式（即无多款式），默认为 `true`
  - `inventory_tracking` boolean

    是否启用库存追踪
  - `inventory_policy` string

    库存策略，可选值：`continue`（缺货时继续销售）、`deny`（缺货时停止销售）、`auto_unpublished`（缺货时自动下架）；当 `inventory_tracking` 为 `true` 时必填
  - `need_variant_image` boolean

    是否需要为款式设置图片；当 `has_only_default_variant` 为 `false` 时必填
  - `spu` string

    商品 SPU（标准产品单元）
  - `fake_sales` int64

    商品虚拟销量
  - `display_fake_sales` boolean

    是否在前台展示虚拟销量
  - `options` object[]

    商品款式属性列表（如颜色、尺寸等）

    *   Array \[

    - `name` string (required)

      款式属性名称，例如："color"、"size"
    - `values` string[] (required)

      款式属性的可选值列表，例如：\["red", "black"\]、\["small", "large"\]
    *   \]
  - `images` object[] (required)

    商品图片列表

    *   Array \[

    - `src` string (required)

      图片 URL
    - `width` int32

      图片宽度（单位：像素）
    - `height` int32

      图片高度（单位：像素）
    - `alt` string

      图片替代文本（alt）
    - `path` string

      图片存储路径
    *   \]
  - `variants` object[] (required)

    商品子款式列表

    *   Array \[

    - `option1` string

      商品款式属性 1 的取值（例如"颜色"取值"红色"）
    - `option2` string

      商品款式属性 2 的取值
    - `option3` string

      商品款式属性 3 的取值
    - `image` object

      子款式图片，例如：`{"src":"//cn.cdn.shoplazza.com/c8bf5695d347092d7a010f00182581f7.jpeg"}`

      - `src` string (required)

        图片 URL
      - `width` int32

        图片宽度（单位：像素）
      - `height` int32

        图片高度（单位：像素）
      - `alt` string

        图片替代文本（alt）
      - `path` string

        图片存储路径
    - `compare_at_price` double

      划线价
    - `price` double (required)

      子款式售价；如需留空请设置为 "0.00"
    - `sku` string

      SKU
    - `barcode` string

      条形码
    - `note` string

      款式备注/说明
    - `inventory_quantity` int64

      库存数量
    - `weight` double

      重量
    - `weight_unit` string

      重量单位，可选值：`kg`、`g`、`lb`、`oz`
    - `cost_price` double

      成本价
    - `wholesale_price` object[]

      批发价列表

      *   Array \[

      - `price` double (required)

        批发价
      - `min_quantity` int64 (required)

        起购量（达到该数量才适用此批发价）
      *   \]
    - `whole_prices` object[]

      批发价列表。已废弃，等价于 `wholesale_price`；两者同时传时以 `wholesale_price` 为准。

      *   Array \[

      - `price` double (required)

        批发价
      - `min_quantity` int64 (required)

        起购量（达到该数量才适用此批发价）
      *   \]
    - `retail_price` double

      零售价
    - `position` int64

      子款式在列表中的排序位置
    - `extend` object

      子款式扩展信息（包裹尺寸、原产地国别、HS 代码等）

      - `length` double

        包裹长度
      - `width` double

        包裹宽度
      - `height` double

        包裹高度
      - `dimension_unit` string

        尺寸单位，可选值：`cm`、`in`、`mm`
      - `origin_country_code` string

        原产地国别（国家代码，例如 `CN`、`US`）
      - `hs_code` string

        HS（协调制度）代码
    *   \]
  - `mixed_wholesale` boolean

    是否支持混批
  - `collection_ids` string[]

    商品所属专辑的 ID 列表
  - `product_type` string

    商品类型
  - `brand` string

    品牌
  - `unique_token` string

    用于幂等性校验的唯一令牌
  - `independent_seo` boolean

    商品是否启用独立的 SEO 设置
  - `inventory_quantity` int64

    商品库存数量
  - `category_id` string

    商品分类 ID
  - `auto_publish_at` string

    商品定时上架时间。设置 `auto_publish_at` 后，商品将在该时间按计划上架；时间格式遵循 RFC 3339，例如：`2026-01-26T10:00:00.000+00:00`

```json
{
  "product": {
    "title": "string",
    "brief": "string",
    "description": "string",
    "published": true,
    "requires_shipping": true,
    "taxable": true,
    "tags": [
      "string"
    ],
    "vendor": "string",
    "vendor_url": "string",
    "note": "string",
    "seo_title": "string",
    "seo_description": "string",
    "seo_keywords": [
      "string"
    ],
    "handle": "string",
    "has_only_default_variant": true,
    "inventory_tracking": true,
    "inventory_policy": "string",
    "need_variant_image": true,
    "spu": "string",
    "fake_sales": 0,
    "display_fake_sales": true,
    "options": [
      {
        "name": "string",
        "values": [
          "string"
        ]
      }
    ],
    "images": [
      {
        "src": "string",
        "width": 0,
        "height": 0,
        "alt": "string",
        "path": "string"
      }
    ],
    "variants": [
      {
        "option1": "string",
        "option2": "string",
        "option3": "string",
        "image": {
          "src": "string",
          "width": 0,
          "height": 0,
          "alt": "string",
          "path": "string"
        },
        "compare_at_price": 0,
        "price": 0,
        "sku": "string",
        "barcode": "string",
        "note": "string",
        "inventory_quantity": 0,
        "weight": 0,
        "weight_unit": "string",
        "cost_price": 0,
        "wholesale_price": [
          {
            "price": 0,
            "min_quantity": 0
          }
        ],
        "whole_prices": [
          {
            "price": 0,
            "min_quantity": 0
          }
        ],
        "retail_price": 0,
        "position": 0,
        "extend": {
          "length": 0,
          "width": 0,
          "height": 0,
          "dimension_unit": "string",
          "origin_country_code": "string",
          "hs_code": "string"
        }
      }
    ],
    "mixed_wholesale": true,
    "collection_ids": [
      "string"
    ],
    "product_type": "string",
    "brand": "string",
    "unique_token": "string",
    "independent_seo": true,
    "inventory_quantity": 0,
    "category_id": "string",
    "auto_publish_at": "string"
  }
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `product` object

    已创建的商品

    - `id` string

      商品 ID
    - `title` string

      商品名称
    - `description` string

      商品描述
    - `published` boolean

      商品是否已上架
    - `requires_shipping` boolean

      商品是否需要物流
    - `taxable` boolean

      商品是否需要计税
    - `tags` string[]

      商品标签列表
    - `vendor` string

      供应商名称
    - `vendor_url` string

      供应商 URL
    - `note` string

      自定义备注，例如："This is a customizable product"
    - `seo_title` string

      SEO 标题
    - `seo_description` string

      SEO 描述
    - `seo_keywords` string[]

      SEO 关键词列表
    - `handle` string

      商品 handle（用于 URL 的友好别名）
    - `has_only_default_variant` boolean

      是否仅有默认款式（即无多款式）
    - `inventory_tracking` boolean

      是否启用库存追踪
    - `inventory_policy` string

      库存策略，可选值：`continue`（缺货时继续销售）、`deny`（缺货时停止销售）、`auto_unpublished`（缺货时自动下架）；当 `inventory_tracking` 为 `true` 时必填
    - `need_variant_image` boolean

      是否需要为款式设置图片；当 `has_only_default_variant` 为 `false` 时必填
    - `spu` string

      商品 SPU（标准产品单元）
    - `fake_sales` int64

      商品虚拟销量
    - `display_fake_sales` boolean

      是否在前台展示虚拟销量
    - `options` object[]

      商品款式属性列表（如颜色、尺寸等）

      *   Array \[

      - `id` string

        款式属性 ID
      - `name` string

        款式属性名称，例如："color"、"size"
      - `values` string[]

        款式属性的可选值列表，例如：\["red", "black"\]、\["small", "large"\]
      - `position` int64

        款式属性排序位置
      *   \]
    - `images` object[]

      商品图片列表

      *   Array \[

      - `id` string

        图片 ID
      - `src` string

        图片 URL
      - `width` int32

        图片宽度（单位：像素）
      - `height` int32

        图片高度（单位：像素）
      - `alt` string

        图片替代文本（alt）
      - `position` int64

        图片排序位置
      - `path` string

        图片存储路径
      *   \]
    - `variants` object[]

      商品子款式列表

      *   Array \[

      - `id` string

        子款式 ID
      - `product_id` string

        子款式所属商品的 ID
      - `image_id` string

        子款式关联的图片 ID
      - `created_at` string

        子款式创建时间
      - `updated_at` string

        子款式最后更新时间
      - `title` string

        子款式标题
      - `option1` string

        子款式在第 1 个商品款式属性上的取值
      - `option2` string

        子款式在第 2 个商品款式属性上的取值
      - `option3` string

        子款式在第 3 个商品款式属性上的取值
      - `image` object

        子款式图片

        - `src` string

          图片 URL
        - `width` int32

          图片宽度（单位：像素）
        - `height` int32

          图片高度（单位：像素）
        - `alt` string

          图片替代文本（alt）
        - `path` string

          图片存储路径
      - `position` int64

        子款式在商品中的排序位置
      - `compare_at_price` double

        划线价
      - `price` double

        子款式售价
      - `sku` string

        SKU
      - `barcode` string

        条形码
      - `note` string

        款式备注
      - `inventory_quantity` int64

        库存数量
      - `weight` double

        重量
      - `weight_unit` string

        重量单位，可选值：`kg`、`g`、`lb`、`oz`
      - `cost_price` double

        成本价
      - `wholesale_price` object[]

        批发价列表

        *   Array \[

        - `price` double (required)

          批发价
        - `min_quantity` int64 (required)

          起购量（达到该数量才适用此批发价）
        *   \]
      - `whole_prices` object[]

        批发价列表。已废弃，等价于 `wholesale_price`，两者返回相同内容。

        *   Array \[

        - `price` double (required)

          批发价
        - `min_quantity` int64 (required)

          起购量（达到该数量才适用此批发价）
        *   \]
      - `retail_price` double

        零售价
      - `is_discount` boolean

        子款式当前是否处于打折状态
      - `origin_price` double

        原价
      - `extend` object

        子款式扩展信息（包裹尺寸、原产地国别、HS 代码等）

        - `length` double

          包裹长度
        - `width` double

          包裹宽度
        - `height` double

          包裹高度
        - `dimension_unit` string

          尺寸单位，可选值：`cm`、`in`、`mm`
        - `origin_country_code` string

          原产地国别（国家代码，例如 `CN`、`US`）
        - `hs_code` string

          HS（协调制度）代码
      *   \]
    - `mixed_wholesale` boolean

      是否支持混批
    - `product_type` string

      商品类型
    - `brand` string

      品牌
    - `brief` string

      商品简介
    - `inventory_quantity` int64

      库存数量
    - `price_min` double

      各子款式售价中的最低价
    - `price_max` double

      各子款式售价中的最高价
    - `compare_at_price_min` double

      各子款式划线价中的最低价
    - `compare_at_price_max` double

      各子款式划线价中的最高价
    - `published_at` string

      商品上架时间
    - `created_at` string

      商品创建时间
    - `updated_at` string

      商品最后更新时间
    - `sales` int64

      商品实际销量
    - `independent_seo` boolean

      是否启用独立的 SEO 设置
    - `url` string

      商品访问 URL
    - `available` boolean

      商品是否可售
    - `retail_price_min` double

      各子款式零售价中的最低价
    - `retail_price_max` double

      各子款式零售价中的最高价
    - `origin_price_min` double

      各子款式原价中的最低价
    - `origin_price_max` double

      各子款式原价中的最高价
    - `primary_image` object

      商品主图

      - `src` string

        图片 URL
      - `width` int32

        图片宽度（单位：像素）
      - `height` int32

        图片高度（单位：像素）
      - `alt` string

        图片替代文本（alt）
      - `path` string

        图片存储路径
    - `tax_code` string

      商品税码
    - `category_id` string

      商品所属分类 ID
    - `category` object

      商品所属分类信息

      - `id` uint64

        分类 ID
      - `name` string

        分类名称
      - `google_id` int64

        Google 分类 ID
      - `level` int32

        分类层级
      - `path` string

        分类层级路径

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "product": {
      "id": "string",
      "title": "string",
      "description": "string",
      "published": true,
      "requires_shipping": true,
      "taxable": true,
      "tags": [
        "string"
      ],
      "vendor": "string",
      "vendor_url": "string",
      "note": "string",
      "seo_title": "string",
      "seo_description": "string",
      "seo_keywords": [
        "string"
      ],
      "handle": "string",
      "has_only_default_variant": true,
      "inventory_tracking": true,
      "inventory_policy": "string",
      "need_variant_image": true,
      "spu": "string",
      "fake_sales": 0,
      "display_fake_sales": true,
      "options": [
        {
          "id": "string",
          "name": "string",
          "values": [
            "string"
          ],
          "position": 0
        }
      ],
      "images": [
        {
          "id": "string",
          "src": "string",
          "width": 0,
          "height": 0,
          "alt": "string",
          "position": 0,
          "path": "string"
        }
      ],
      "variants": [
        {
          "id": "string",
          "product_id": "string",
          "image_id": "string",
          "created_at": "string",
          "updated_at": "string",
          "title": "string",
          "option1": "string",
          "option2": "string",
          "option3": "string",
          "image": {
            "src": "string",
            "width": 0,
            "height": 0,
            "alt": "string",
            "path": "string"
          },
          "position": 0,
          "compare_at_price": 0,
          "price": 0,
          "sku": "string",
          "barcode": "string",
          "note": "string",
          "inventory_quantity": 0,
          "weight": 0,
          "weight_unit": "string",
          "cost_price": 0,
          "wholesale_price": [
            {
              "price": 0,
              "min_quantity": 0
            }
          ],
          "whole_prices": [
            {
              "price": 0,
              "min_quantity": 0
            }
          ],
          "retail_price": 0,
          "is_discount": true,
          "origin_price": 0,
          "extend": {
            "length": 0,
            "width": 0,
            "height": 0,
            "dimension_unit": "string",
            "origin_country_code": "string",
            "hs_code": "string"
          }
        }
      ],
      "mixed_wholesale": true,
      "product_type": "string",
      "brand": "string",
      "brief": "string",
      "inventory_quantity": 0,
      "price_min": 0,
      "price_max": 0,
      "compare_at_price_min": 0,
      "compare_at_price_max": 0,
      "published_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "sales": 0,
      "independent_seo": true,
      "url": "string",
      "available": true,
      "retail_price_min": 0,
      "retail_price_max": 0,
      "origin_price_min": 0,
      "origin_price_max": 0,
      "primary_image": {
        "src": "string",
        "width": 0,
        "height": 0,
        "alt": "string",
        "path": "string"
      },
      "tax_code": "string",
      "category_id": "string",
      "category": {
        "id": 0,
        "name": "string",
        "google_id": 0,
        "level": 0,
        "path": "string"
      }
    }
  }
}
```