新建下架商品，没有规格差异时写入 price 和 stock，系统会创建一条默认可售规格

POST/api/v1/catalogs/{id}/products

认证请求头 Authorization: Bearer <访问令牌>，访问令牌用设备码换取，不要向用户要密码、短信验证码或 API Key
权限商家，需要 product:write 才能修改商品、图片或店铺介绍

路径参数

path

idstring必填

目录 ID

路径示例

/api/v1/catalogs/cat_example/products

请求体

application/json

新建后默认下架，价格是整数分

titlestring必填

商品名称

coverstring | null

封面地址，或先上传后再写

fieldsobject

目录字段值，数字用 JSON 数字，是否用布尔

priceinteger

没有规格轴时写入，整数分

stockinteger | null

没有规格轴时写入，null 表示不限

skustring | null

没有规格轴时的 SKU，有规格轴时不要传

请求示例

{
  "title": "示例",
  "cover": null,
  "fields": {},
  "price": 159900,
  "stock": null,
  "sku": null
}

响应

201

application/json

成功时 code 为 200，资源在 data

idstring必填

商品 ID，以 prd_ 开头

catalog_idstring必填

目录 ID

titlestring必填

商品名称

statusenum<string>必填

上架状态

可选值: onoff

coverstring | null必填

封面地址

fieldsobject必填

目录字段值

schema_revisioninteger必填

字段定义版本

created_atstring必填

创建时间，ISO-8601

updated_atstring必填

更新时间，ISO-8601

deleted_atstring | null必填

软删除时间，未删除时为 null

axes[].idstring必填

规格轴 ID

axes[].keystring必填

规格轴 key

axes[].labelstring必填

规格轴名称

axes[].positioninteger必填

规格轴顺序

variants[].idstring必填

规格 ID

variants[].skustring | null必填

SKU

variants[].option_valuesobject必填

规格轴取值

variants[].priceinteger必填

整数分

variants[].stockinteger | null必填

库存，null 表示不限

variants[].statusenum<string>必填

是否可售

可选值: onoff

variants[].coverstring | null必填

规格封面

variants[].deletedboolean必填

是否已软删除

响应示例

{
  "id": "prd_example",
  "catalog_id": "cat_example",
  "title": "示例",
  "status": "on",
  "cover": "string",
  "fields": {},
  "schema_revision": 1,
  "created_at": "2026-05-16T00:00:00.000Z",
  "updated_at": "2026-05-16T00:00:00.000Z",
  "deleted_at": "2026-05-16T00:00:00.000Z",
  "axes": [
    {
      "id": "id_example",
      "key": "weight_g",
      "label": "示例",
      "position": 1
    }
  ],
  "variants": [
    {
      "id": "var_example",
      "sku": "string",
      "option_values": {},
      "price": 159900,
      "stock": null,
      "status": "on",
      "cover": "string",
      "deleted": true
    }
  ]
}