Paddle

Paddle 为 SaaS、AI、应用、软件和数字产品提供 Merchant of Record（MoR）结账、订阅、发票、税务与买家账单支持。接入时最容易犯的错误，是把 Subscription 当成唯一事实来源：订阅描述持续计费关系，真正的首购、续费、升级补差、退款和发票都落在一笔笔 Transaction 上。

用 Product、Price 和 Item 表达真实套餐

Product 说明卖什么，Price 定义金额、币种、周期、试用和数量，Transaction Item 则记录某次交易实际包含的价格与数量。例如“Pro 月付 + 5 个席位”应由周期价格和数量组成；一次性设置费或附加项可作为另一项加入交易。不要只在本地保存“Pro”字符串，应保存 product_id、price_id、数量与内部权益版本。

地区定价可使用自动币种转换或 country-specific price override。更新覆盖列表时，API 需要提交希望保留的完整列表，遗漏的现有覆盖会被移除；批量改价前应先读取当前 Price，生成差异并在沙箱复核目标国家和币种。

Transaction 状态决定何时交付、何时对账

首次周期结账会产生 Subscription，此后续费、套餐变化和一次性附加费用还会生成新的 Transaction。只保留 subscription_id，会让每期金额、税费、退款和发票无法还原。

升级前先预览按比例计费

套餐、附加项或席位数量变化可能立即生效、下次续费生效，或本次不收费。产品界面在确认前应展示新套餐、实际数量、生效日、剩余周期抵扣、当前应付和下次续费金额，再由后端提交变更。不要先提升权限后猜测补差是否成功。

“Pro 5 席升级 Pro 8 席”的处理顺序

1. 读取最新 Subscription 和 Items，避免用旧缓存覆盖刚发生的变化。
2. 预览带有目标数量及明确 proration billing mode 的变更结果。
3. 把当前应付、抵扣和下次续费金额显示给客户确认。
4. 提交后等待实际 Transaction 结果，再把本地席位从 5 调整为 8。
5. 若付款失败，保留原有已付权益并提示恢复支付，不制造“已升级但未付款”的状态。

Webhook 消费器必须能处理乱序和重放

每条通知有唯一 notification_id 和发生时间 occurred_at；投递顺序不保证与业务发生顺序一致。接收端应使用原始请求体和 Paddle-Signature 验签，保存通知后尽快响应，再按 notification_id 幂等处理。收到较旧事件时，不应直接覆盖新状态，而要比较 occurred_at 或重新读取当前 Transaction / Subscription。

• 初购：transaction.paid 与 transaction.completed 各触发什么动作。
• 续费：成功、past_due、恢复付款和最终取消是否符合宽限政策。
• 变更：升级、降级、席位增减和暂停后的金额与权限是否一致。
• 恢复：同一通知重复发送、事件乱序、处理器短暂 500 后是否能自愈。
• 财务：发票号、税额、平台费用、收入和退款是否可按 Transaction 追溯。

Paddle 作为买家侧销售方处理其覆盖市场的 VAT、GST 与销售税，但开发者仍要处理所在地收入、公司或个人税务。费率、保留金、审核和结算条件应以正式账户为准；收款模式选择可参考 独立开发者收款平台对比。访问地址：https://www.paddle.com/