> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP商品数据模型字段规范

> ACP商品数据对象完整字段规范，详解Product商品与Variant变体的层级结构、Price价格minor units表示法、Media图片视频资源配置、Availability库存状态管理和Category分类体系，帮助开发者正确构建符合ACP规范要求的商品数据模型

# 商品数据格式

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

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

每个数据文件或API调用必须包含Feed Header，标识数据来源：

| 字段                | 类型     | 必填 | 说明                                   |
| ----------------- | ------ | -- | ------------------------------------ |
| `feed_id`         | string | 是  | 数据源唯一标识                              |
| `account_id`      | string | 是  | 商家账户ID                               |
| `target_merchant` | string | 是  | 目标商家标识                               |
| `target_country`  | string | 是  | 目标国家（ISO 3166-1 alpha-2，如 "US"、"CN"） |

## 2.2 Product对象

| 字段            | 类型          | 必填    | 说明                  |
| ------------- | ----------- | ----- | ------------------- |
| `id`          | string      | 是     | 商品唯一标识，**必须长期稳定不变** |
| `title`       | string      | 否     | 商品标题                |
| `description` | Description | 否     | 商品描述（支持多种格式）        |
| `url`         | URI string  | 否     | 商品页面URL             |
| `media`       | Media\[]    | 否     | 商品图片/视频             |
| `variants`    | Variant\[]  | **是** | 至少1个变体              |

**ID稳定性**: 商品ID在整个生命周期内必须保持不变。更换ID会导致ChatGPT丢失该商品的历史数据和推荐记录。

## 2.3 Variant对象（变体）

每个Variant代表商品的一个具体规格（如颜色/尺码组合）：

| 字段                | 类型               | 必填 | 说明                        |
| ----------------- | ---------------- | -- | ------------------------- |
| `id`              | string           | 是  | 变体唯一标识，必须稳定               |
| `title`           | string           | 是  | 变体标题                      |
| `description`     | Description      | 否  | 变体专属描述                    |
| `url`             | URI string       | 否  | 变体专属页面URL                 |
| `barcodes`        | Barcode\[]       | 否  | 条形码（GTIN等）                |
| `price`           | Price            | 否  | 当前销售价格                    |
| `list_price`      | Price            | 否  | 原价/划线价                    |
| `unit_price`      | UnitPrice        | 否  | 单位价格（按重量/体积等）             |
| `availability`    | Availability     | 否  | 库存状态                      |
| `categories`      | Category\[]      | 否  | 商品分类                      |
| `condition`       | string\[]        | 否  | 商品状态：`new` 或 `secondhand` |
| `variant_options` | VariantOption\[] | 否  | 规格选项（颜色、尺码等）              |
| `media`           | Media\[]         | 否  | 变体专属图片（第一张为主图）            |
| `seller`          | Seller           | 否  | 卖家信息（适用于平台型商家）            |

## 2.4 Price对象

所有价格使用**ISO 4217最小货币单位**（分/cents）：

```json theme={null}
{
  "amount": 7999,
  "currency": "USD"
}
```

| 字段         | 类型      | 必填 | 约束                           |
| ---------- | ------- | -- | ---------------------------- |
| `amount`   | integer | 是  | 大于等于0，单位为最小货币单位              |
| `currency` | string  | 是  | ISO 4217三字母代码（如 "USD"、"CNY"） |

**注意**: \$79.99 在ACP中表示为 `7999`，¥399 表示为 `39900`。日元等无小数货币直接使用面值。

## 2.5 Description对象

至少提供一种格式。推荐使用 `plain`：

| 字段         | 类型     | 说明         |
| ---------- | ------ | ---------- |
| `plain`    | string | 纯文本格式（推荐）  |
| `html`     | string | HTML格式     |
| `markdown` | string | Markdown格式 |

## 2.6 Availability对象

| 字段          | 类型      | 值                                                                       |
| ----------- | ------- | ----------------------------------------------------------------------- |
| `available` | boolean | true/false                                                              |
| `status`    | string  | `in_stock` / `backorder` / `preorder` / `out_of_stock` / `discontinued` |

**商品下架**: 设置 `is_eligible_search=false` 或在下次全量快照中省略该商品。

## 2.7 Media对象

| 字段         | 类型         | 必填                   |
| ---------- | ---------- | -------------------- |
| `type`     | string     | 是（`image` 或 `video`） |
| `url`      | URI string | 是                    |
| `alt_text` | string     | 否                    |
| `width`    | integer    | 否（像素）                |
| `height`   | integer    | 否（像素）                |

**第一张图片是主图**: 在media数组中，第一个 `type: "image"` 的条目会作为ChatGPT展示的主图。

## 2.8 Category对象

| 字段         | 类型     | 说明                                                      |
| ---------- | ------ | ------------------------------------------------------- |
| `value`    | string | 分类名称                                                    |
| `taxonomy` | string | 分类体系：`merchant` / `google_product_category` / `shopify` |

支持的分类体系：

* **merchant**: 商家自定义分类
* **google\_product\_category**: Google商品分类标准
* **shopify**: Shopify分类标准

## 2.9 VariantOption对象

用于描述变体的用户可见规格：

```json theme={null}
{
  "name": "颜色",
  "value": "黑色"
}
```

常见选项：颜色、尺码、材质、容量等。

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

| 字段      | 类型      | 说明     |
| ------- | ------- | ------ |
| `name`  | string  | 卖家名称   |
| `links` | Link\[] | 卖家相关链接 |

Link对象的 `type` 枚举：`privacy_policy` / `terms_of_service` / `refund_policy` / `shipping_policy` / `faq`

**使用持久性公共URL**: 卖家链接必须是稳定的、长期有效的公共URL。

## 2.11 Barcode对象

```json theme={null}
{
  "type": "gtin",
  "value": "0123456789012"
}
```

## 2.12 完整Product示例

```json theme={null}
{
  "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" }
      ]
    }
  ]
}
```

***

**下一章**: [文件上传集成](/zh/book-4/ch3-file-upload) — SFTP推送规格、文件格式要求、分片策略