跳转到主要内容

​
促销数据管理

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

​
5.1 Promotion对象

字段类型必填说明
idstring是促销唯一标识
titlestring是促销名称
descriptionstring否促销详细描述
statusenum是促销状态
active_periodDateTimeRange否生效时间范围
benefitsBenefit[]是折扣类型列表
applies_toProductTarget否适用商品范围
urlURI string否促销详情页URL

​
促销状态

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

​
生效时间范围

active_period 使用 DateTimeRange 类型，包含 start_time 和 end_time 两个字段： 
{
  "active_period": {
    "start_time": "2026-04-01T00:00:00Z",
    "end_time": "2026-04-30T23:59:59Z"
  }
}

​
适用商品

applies_to 使用 ProductTarget 类型指定促销适用的商品： 
{
  "applies_to": {
    "product_id": "prod_001",
    "variant_ids": ["var_001_black", "var_001_white"]
  }
}
如果不指定 variant_ids，促销适用于该商品的所有变体。

​
5.2 三种折扣类型

​
固定金额折扣（AmountOffBenefit）

{
  "type": "amount_off",
  "amount_off": {
    "amount": 1000,
    "currency": "USD"
  }
}
减免固定金额。上例表示减免10.00 USD（金额使用minor units，即分）。

​
百分比折扣（PercentOffBenefit）

{
  "type": "percent_off",
  "percent_off": 20
}
按百分比减免。上例表示打八折（减免20%）。

​
免运费（FreeShippingBenefit）

{
  "type": "free_shipping"
}
免除运费。无需额外参数。

​
5.3 完整的Promotion示例

{
  "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操作： 
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时，促销折扣通过以下字段传递。

​
折扣码

{
  "codes": ["SUMMER25", "WELCOME10"]
}
codes 数组包含用户提供的折扣码。

​
已应用的折扣（AppliedDiscount）

字段类型说明
idstring折扣标识
codestring折扣码
couponCoupon优惠券详情
amountPrice折扣金额
automaticboolean是否自动应用
startdatetime生效时间
enddatetime结束时间
methodenumeach（逐件折扣）或 across（总额折扣）
prioritynumber优先级（数字越小优先级越高）
allocationsAllocation[]分配到各行项目的明细

​
Coupon对象

{
  "coupon": {
    "name": "Summer 25% Off",
    "percent_off": 25,
    "duration": "repeating",
    "max_redemptions": 1000,
    "times_redeemed": 342
  }
}
Coupon支持 percent_off（百分比折扣）或 amount_off（固定金额折扣）两种模式。

​
被拒绝的折扣（RejectedDiscount）

如果折扣码无效或不适用，会出现在 rejected 数组中： 
{
  "rejected": [
    {
      "code": "EXPIRED_CODE",
      "reason": "Coupon has expired"
    }
  ]
}

​
完整的折扣结构示例

{
  "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章：数据质量最佳实践 — ID稳定性、URL规范、禁止内容