Discount 折扣扩展

基本信息

  • Capability Name：dev.ucp.shopping.discount
  • Version：2026-01-11
  • 官方规范：discount.md

概述

Discount 扩展允许商家声明支持结账会话的折扣码，并指定平台与商家之间如何共享折扣码。

关键特性：

  • 提交一个或多个折扣码
  • 接收已应用的折扣，包含可读标题和金额
  • 通过 messages[] 详细错误码传达被拒绝的代码
  • 与代码折扣一起显示自动折扣

依赖关系：

  • Checkout 能力

发现

商家在 Profile 中声明折扣支持：

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.discount",
        "version": "2026-01-11",
        "extends": "dev.ucp.shopping.checkout",
        "spec": "https://ucp.dev/specification/discount",
        "schema": "https://ucp.dev/schemas/shopping/discount.json"
      }
    ]
  }
}

Schema 结构

当此能力激活时，结账会扩展 discounts 对象。

折扣分配详情

applied 数组解释折扣如何计算和分配。

分配方法含义示例
each对每个符合条件的项目独立应用“每件商品10%折扣” → 10% × 商品价格
across按价值比例分配“订单减$10” → $60商品减$6，$40商品减$4

堆叠顺序

当应用多个折扣时，priority 表示计算顺序。数字越小优先应用：

购物车: $100
折扣 A (priority: 1): 20% off → $100 × 0.8 = $80
折扣 B (priority: 2): $10 off → $80 - $10 = $70

操作

折扣码通过标准结账创建/更新操作提交。

请求行为：

  • 替换语义：提交 discounts.codes 会替换之前提交的任何代码
  • 清除代码：发送空数组 "codes": [] 删除所有折扣码
  • 不区分大小写：商家不区分大小写匹配代码

响应行为：

  • discounts.applied 包含所有活动折扣（基于代码 + 自动）
  • 通过 messages[] 传达被拒绝的代码
  • 折扣金额反映在 totals[] 和 line_items[].discount 中

被拒绝的代码

当提交的折扣码无法应用时，商家通过 messages[] 数组传达：

{
  "messages": [
    {
      "type": "warning",
      "code": "discount_code_expired",
      "path": "$.discounts.codes[0]",
      "content": "代码 'SUMMER20' 于12月1日过期"
    }
  ]
}

被拒绝折扣的错误码：

代码描述
discount_code_expired代码已过期
discount_code_invalid代码未找到或格式错误
discount_code_already_applied代码已应用
discount_code_combination_disallowed不能与其他活动折扣组合
discount_code_user_not_logged_in代码需要认证用户
discount_code_user_ineligible用户不符合资格条件

自动折扣

商家可根据购物车内容、客户细分或促销规则自动应用折扣：

  • 出现在 discounts.applied 中，automatic: true 且无 code 字段
  • 无需平台操作即可应用
  • 平台无法移除
  • 为透明性显示（平台可向用户解释为何应用折扣）

对行项目和总计的影响

应用的折扣反映在核心结账字段中，使用两种不同的总计类型：

总计类型何时使用
items_discount分配给行项目的折扣 ($.line_items[*])
discount订单级别折扣（运费、费用、固定订单金额）

示例

订单级别折扣

请求：

{
  "discounts": {
    "codes": ["SAVE10"]
  }
}

响应：

{
  "discounts": {
    "codes": ["SAVE10"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "订单减$10",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "amount": 5000},
    {"type": "discount", "amount": 1000},
    {"type": "total", "amount": 4000}
  ]
}

被拒绝的折扣码

请求：

{
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"]
  }
}

响应：

{
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "订单减$10",
        "amount": 1000
      }
    ]
  },
  "messages": [
    {
      "type": "warning",
      "code": "discount_code_expired",
      "content": "代码 'EXPIRED50' 已于12月1日过期"
    }
  ]
}