> ## 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促销对象与折扣规则配置完整规范，详解Promotion字段定义与状态生命周期管理，涵盖amount_off固定金额、percent_off百分比折扣和free_shipping免运费三种优惠类型，以及active_period生效周期、applies_to商品关联和Checkout折扣码处理机制

# 促销数据管理

ACP支持通过REST API管理促销数据。促销只能通过API提交，不支持SFTP文件上传。

## 5.1 Promotion对象

| 字段              | 类型            | 必填 | 说明       |
| --------------- | ------------- | -- | -------- |
| `id`            | string        | 是  | 促销唯一标识   |
| `title`         | string        | 是  | 促销名称     |
| `description`   | string        | 否  | 促销详细描述   |
| `status`        | enum          | 是  | 促销状态     |
| `active_period` | DateTimeRange | 否  | 生效时间范围   |
| `benefits`      | Benefit\[]    | 是  | 折扣类型列表   |
| `applies_to`    | ProductTarget | 否  | 适用商品范围   |
| `url`           | URI string    | 否  | 促销详情页URL |

### 促销状态

| 状态          | 说明       |
| ----------- | -------- |
| `draft`     | 草稿，未生效   |
| `scheduled` | 已排期，等待生效 |
| `active`    | 当前生效中    |
| `expired`   | 已过期      |
| `disabled`  | 手动禁用     |

### 生效时间范围

`active_period` 使用 DateTimeRange 类型，包含 `start_time` 和 `end_time` 两个字段：

```json theme={null}
{
  "active_period": {
    "start_time": "2026-04-01T00:00:00Z",
    "end_time": "2026-04-30T23:59:59Z"
  }
}
```

### 适用商品

`applies_to` 使用 ProductTarget 类型指定促销适用的商品：

```json theme={null}
{
  "applies_to": {
    "product_id": "prod_001",
    "variant_ids": ["var_001_black", "var_001_white"]
  }
}
```

如果不指定 `variant_ids`，促销适用于该商品的所有变体。

## 5.2 三种折扣类型

### 固定金额折扣（AmountOffBenefit）

```json theme={null}
{
  "type": "amount_off",
  "amount_off": {
    "amount": 1000,
    "currency": "USD"
  }
}
```

减免固定金额。上例表示减免10.00 USD（金额使用minor units，即分）。

### 百分比折扣（PercentOffBenefit）

```json theme={null}
{
  "type": "percent_off",
  "percent_off": 20
}
```

按百分比减免。上例表示打八折（减免20%）。

### 免运费（FreeShippingBenefit）

```json theme={null}
{
  "type": "free_shipping"
}
```

免除运费。无需额外参数。

## 5.3 完整的Promotion示例

```json theme={null}
{
  "id": "promo_summer_2026",
  "title": "Summer Sale - 25% Off Electronics",
  "description": "All electronics 25% off during summer promotion",
  "status": "scheduled",
  "active_period": {
    "start_time": "2026-06-01T00:00:00Z",
    "end_time": "2026-08-31T23:59:59Z"
  },
  "benefits": [
    {
      "type": "percent_off",
      "percent_off": 25
    }
  ],
  "applies_to": {
    "product_id": "prod_electronics_bundle",
    "variant_ids": ["var_laptop_001", "var_tablet_001"]
  },
  "url": "https://store.example.com/summer-sale"
}
```

## 5.4 API提交方式

促销通过PATCH端点进行upsert操作：

```http theme={null}
PATCH /product_feeds/:feed_id/promotions
Content-Type: application/json
Authorization: Bearer api_key_123

{
  "promotions": [
    {
      "id": "promo_summer_2026",
      "title": "Summer Sale",
      "status": "active",
      "benefits": [
        {
          "type": "percent_off",
          "percent_off": 25
        }
      ]
    }
  ]
}
```

按 `id` 匹配：已有则更新，不存在则创建。

## 5.5 Checkout Session中的折扣处理

当AI代理创建Checkout Session时，促销折扣通过以下字段传递。

### 折扣码

```json theme={null}
{
  "codes": ["SUMMER25", "WELCOME10"]
}
```

`codes` 数组包含用户提供的折扣码。

### 已应用的折扣（AppliedDiscount）

| 字段            | 类型            | 说明                           |
| ------------- | ------------- | ---------------------------- |
| `id`          | string        | 折扣标识                         |
| `code`        | string        | 折扣码                          |
| `coupon`      | Coupon        | 优惠券详情                        |
| `amount`      | Price         | 折扣金额                         |
| `automatic`   | boolean       | 是否自动应用                       |
| `start`       | datetime      | 生效时间                         |
| `end`         | datetime      | 结束时间                         |
| `method`      | enum          | `each`（逐件折扣）或 `across`（总额折扣） |
| `priority`    | number        | 优先级（数字越小优先级越高）               |
| `allocations` | Allocation\[] | 分配到各行项目的明细                   |

### Coupon对象

```json theme={null}
{
  "coupon": {
    "name": "Summer 25% Off",
    "percent_off": 25,
    "duration": "repeating",
    "max_redemptions": 1000,
    "times_redeemed": 342
  }
}
```

Coupon支持 `percent_off`（百分比折扣）或 `amount_off`（固定金额折扣）两种模式。

### 被拒绝的折扣（RejectedDiscount）

如果折扣码无效或不适用，会出现在 `rejected` 数组中：

```json theme={null}
{
  "rejected": [
    {
      "code": "EXPIRED_CODE",
      "reason": "Coupon has expired"
    }
  ]
}
```

### 完整的折扣结构示例

```json theme={null}
{
  "codes": ["SUMMER25"],
  "applied": [
    {
      "id": "disc_001",
      "code": "SUMMER25",
      "coupon": {
        "name": "Summer Sale",
        "percent_off": 25
      },
      "amount": {
        "amount": 2500,
        "currency": "USD"
      },
      "automatic": false,
      "method": "across",
      "priority": 1,
      "allocations": []
    }
  ],
  "rejected": []
}
```

## 5.6 最佳实践

| 实践        | 说明                             |
| --------- | ------------------------------ |
| 使用稳定的促销ID | 更新促销时保持ID不变                    |
| 设置明确的时间范围 | 避免促销长期处于active状态               |
| 及时更新状态    | 过期促销标记为 `disabled` 或 `expired` |
| 测试折扣计算    | 验证minor units的金额计算正确           |
| 指定适用商品    | 通过 `applies_to` 精确控制促销范围       |
| 价格一致性     | 促销价格必须和网站实际优惠一致                |

***

**下一章**: [第6章：数据质量最佳实践](/zh/book-4/ch6-data-quality) — ID稳定性、URL规范、禁止内容