跳转到主要内容

​
商品数据格式

ACP的商品数据模型分为两层：Product（商品）和 Variant（变体）。每个Product必须包含至少一个Variant。

​
2.1 Feed Header（数据源头标识）

每个数据文件或API调用必须包含Feed Header，标识数据来源：
字段类型必填说明
feed_idstring是数据源唯一标识
account_idstring是商家账户ID
target_merchantstring是目标商家标识
target_countrystring是目标国家（ISO 3166-1 alpha-2，如 “US”、“CN”）

​
2.2 Product对象

字段类型必填说明
idstring是商品唯一标识，必须长期稳定不变
titlestring否商品标题
descriptionDescription否商品描述（支持多种格式）
urlURI string否商品页面URL
mediaMedia[]否商品图片/视频
variantsVariant[]是至少1个变体
ID稳定性: 商品ID在整个生命周期内必须保持不变。更换ID会导致ChatGPT丢失该商品的历史数据和推荐记录。

​
2.3 Variant对象（变体）

每个Variant代表商品的一个具体规格（如颜色/尺码组合）：
字段类型必填说明
idstring是变体唯一标识，必须稳定
titlestring是变体标题
descriptionDescription否变体专属描述
urlURI string否变体专属页面URL
barcodesBarcode[]否条形码（GTIN等）
pricePrice否当前销售价格
list_pricePrice否原价/划线价
unit_priceUnitPrice否单位价格（按重量/体积等）
availabilityAvailability否库存状态
categoriesCategory[]否商品分类
conditionstring[]否商品状态：new 或 secondhand
variant_optionsVariantOption[]否规格选项（颜色、尺码等）
mediaMedia[]否变体专属图片（第一张为主图）
sellerSeller否卖家信息（适用于平台型商家）

​
2.4 Price对象

所有价格使用ISO 4217最小货币单位（分/cents）： 
{
  "amount": 7999,
  "currency": "USD"
}
字段类型必填约束
amountinteger是大于等于0，单位为最小货币单位
currencystring是ISO 4217三字母代码（如 “USD”、“CNY”）
注意: $79.99 在ACP中表示为 7999，¥399 表示为 39900。日元等无小数货币直接使用面值。

​
2.5 Description对象

至少提供一种格式。推荐使用 plain：
字段类型说明
plainstring纯文本格式（推荐）
htmlstringHTML格式
markdownstringMarkdown格式

​
2.6 Availability对象

字段类型值
availablebooleantrue/false
statusstringin_stock / backorder / preorder / out_of_stock / discontinued
商品下架: 设置 is_eligible_search=false 或在下次全量快照中省略该商品。

​
2.7 Media对象

字段类型必填
typestring是（image 或 video）
urlURI string是
alt_textstring否
widthinteger否（像素）
heightinteger否（像素）
第一张图片是主图: 在media数组中，第一个 type: "image" 的条目会作为ChatGPT展示的主图。

​
2.8 Category对象

字段类型说明
valuestring分类名称
taxonomystring分类体系：merchant / google_product_category / shopify
支持的分类体系：
  • merchant: 商家自定义分类
  • google_product_category: Google商品分类标准
  • shopify: Shopify分类标准

​
2.9 VariantOption对象

用于描述变体的用户可见规格： 
{
  "name": "颜色",
  "value": "黑色"
}
常见选项：颜色、尺码、材质、容量等。

​
2.10 Seller对象（适用于平台型商家）

字段类型说明
namestring卖家名称
linksLink[]卖家相关链接
Link对象的 type 枚举：privacy_policy / terms_of_service / refund_policy / shipping_policy / faq 使用持久性公共URL: 卖家链接必须是稳定的、长期有效的公共URL。

​
2.11 Barcode对象

{
  "type": "gtin",
  "value": "0123456789012"
}

​
2.12 完整Product示例

{
  "id": "prod_running_shoe_001",
  "title": "经典跑步鞋",
  "description": {
    "plain": "轻量化设计跑步鞋，适合日常训练和短距离比赛"
  },
  "url": "https://store.example.com/products/running-shoe-001?utm_medium=feed",
  "media": [
    {
      "type": "image",
      "url": "https://store.example.com/images/shoe-main.jpg",
      "alt_text": "经典跑步鞋正面图"
    }
  ],
  "variants": [
    {
      "id": "var_shoe_001_black_42",
      "title": "经典跑步鞋 - 黑色 42码",
      "price": {
        "amount": 39900,
        "currency": "CNY"
      },
      "list_price": {
        "amount": 49900,
        "currency": "CNY"
      },
      "availability": {
        "available": true,
        "status": "in_stock"
      },
      "variant_options": [
        { "name": "颜色", "value": "黑色" },
        { "name": "尺码", "value": "42" }
      ],
      "categories": [
        { "value": "Running Shoes", "taxonomy": "google_product_category" },
        { "value": "运动鞋/跑步鞋", "taxonomy": "merchant" }
      ],
      "barcodes": [
        { "type": "gtin", "value": "6901234567890" }
      ]
    }
  ]
}
下一章: 文件上传集成 — SFTP推送规格、文件格式要求、分片策略