UCP Discount

中文摘要：在 UCP checkout session 上应用/核对折扣码,并读取 totals 里的折扣行。用户有优惠码、 或商家有促销要在成单前减免时用。对应能力 dev.ucp.shopping.discount;折扣以 totals 中 type:"discount" 的条目体现。

When to use / 何时使用

• The user supplies a promo / coupon code.
• A merchant promotion should apply automatically and you need to confirm it landed.
• You're verifying the final total reflects the expected reduction before completing.

Discounts are part of the checkout session — applied via PUT /checkout-sessions/{id} and reflected in totals. 折扣是 session 的一部分,通过 PUT 应用、在 totals 体现。

UCP mapping / UCP 映射

Capability dev.ucp.shopping.discount. A successful discount appears in the session totals array as an entry with type: "discount" (a negative amount), and the total entry recomputes accordingly. Invalid codes return a messages entry (severity: recoverable) rather than failing the whole session.

Fields / 字段

Apply (on the session via PUT): include the code in the discount field the merchant's schema declares (commonly a discounts / promo_codes array — confirm against the merchant's schema URL in its UCP profile). 具体字段名以商家 profile 的 schema 为准。

Result — `totals[]` entry:

{ "type": "discount", "display_text": "SAVE10", "amount": -2380 }   // negative, minor units

And the recomputed total:

{ "type": "total", "display_text": "Total", "amount": 25942 }

Workflow / 工作流

1. Collect the code from the user (or detect an auto-promo).
2. `PUT` the session including the discount code (full-replace — keep all other fields).
3. Check `messages` — an invalid/expired code yields a recoverable message; tell the user.
4. Read the `totals` type:"discount" line and the new type:"total"; confirm the reduction.
5. Show the user the savings + final total before complete. The AP2 mandate binds to the

post-discount total.

Edge cases & failure modes / 边界与失败

• Invalid/expired code → recoverable message; don't claim a discount that didn't apply.
• Code not stackable → applying a second may remove the first; re-read totals.
• Discount changes the total after consent → re-confirm; never complete an AP2 mandate

bound to a pre-discount amount.

• Schema variance → the exact discount field name is merchant-declared; read its schema.
• Forgot to resend on PUT → discount dropped (full-replace semantics).

Worked example / 示例

Subtotal €238, user enters "SAVE10".

1. PUT session with full body + SAVE10.
2. No error message → totals gains {type:"discount", display_text:"SAVE10", amount:-2380}.
3. New total recomputed (e.g. 25942 incl. tax). Show "−€23.80, total €259.42", then complete

with a PaymentMandate bound to 25942.

References / 参考

• UCP checkout REST (totals/discount): https://ucp.dev/specification/checkout-rest/
• Capability list: https://ucp.dev/specification/
• Parent: ucp-checkout-session