v1.101.0 (2026年6月2日) - Dodo Payments Documentation

新功能

1. 订阅支付重试

现在可以自动重试失败的续订付款以恢复收入，无需进行集成工作。从设置 → 恢复中启用，设置恢复窗口，Dodo Payments将按照智能计划重试续订，直到成功或窗口关闭。

设置	描述	默认
启用支付重试	自动重试失败的订阅续订付款以恢复收入。	关闭（选择加入）
恢复窗口（天）	在放弃之前重试失败付款的时间长度（1–30）。	13

工作原理

订阅续订付款失败，订阅转移到on_hold。
如果拒绝是可重试的（例如资金不足或临时网络错误等软拒绝），则自动安排下一次尝试。
重试在会话外按退避计划进行，由您的恢复窗口限制。
第一次重试成功时，订阅返回到active，下一次账单日期照常提前。

重试计划 重试逐渐退避，以失败发票创建的时间为锚。只要在您的恢复窗口内，就会进行最多8次尝试：

尝试	上一次后的延迟
1	12 小时
2	24 小时
3	48 小时
4	72 小时
5	96 小时
6	120 小时
7	7天
8	7天

仅重试软拒绝（例如资金不足、一般拒绝、处理或网络错误）。硬拒绝立即结束重试链，因为重试不会改变结果。

这补充了现有的恢复工具——订阅亏损邮件提醒客户更新他们的付款方式，而支付重试则是静默重试现有的方法。它们协同工作效果很好。了解更多：订阅支付重试 | 订阅亏损

2. 业务按比例计算设置

现在可以在业务层面一次性设置默认升级和降级行为，而不是在每次计划变更时传递按比例分配参数。只要客户从客户门户更改其计划，这些默认值就会适用，并且您可以为每个产品集合覆盖它们。

每个方向（升级和降级）都有两个独立控件，加上一个共享的付款失败政策：

设置	字段	默认（升级）	默认（降级）
新计划开始时	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
客户如何收费	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
如果客户付款失败	`on_payment_failure`	`apply_change`	`apply_change`

新计划开始时 (effective_at)

值	行为
`immediately`	客户立即切换到新计划。
`next_billing_date`	客户在当前计划上继续，直到下一个账单日期，然后切换到新计划。

客户如何收费 (proration_billing_mode)

值	行为
`prorated_immediately`	根据当前账单周期剩余时间，现在按比例收费。
`full_immediately`	此时立即全额收取新计划价格。
`difference_immediately`	仅收取新计划与当前计划之间的价格差。
`do_not_bill`	此时不收取任何费用，任何调整将在下次发票中应用。

如果客户付款失败 (on_payment_failure)

值	行为
`prevent_change`	如果付款未通过，客户保持在当前计划上。
`apply_change`	即使付款未通过，也将客户切换到新计划。您可以稍后收取费用。

每个集合的覆盖 每个产品集合可以覆盖这些默认值中的任何一个。每个字段都是独立的——保持在从业务继承即可遵循业务默认值，或者设置明确的值以仅为该集合覆盖。

每个设置按以下顺序解析：

per-request value (Change Plan API) → collection field (if set) → business field → system default

传递给更改计划 API 的每个请求值 (proration_billing_mode, effective_at, on_payment_failure) 始终优先于集合和业务默认设置。新设置仅更改未提供明确值时的情况——这适用于所有客户门户计划更改。

了解更多：订阅升级和降级 | 产品集合

3. 为B2B发票收集企业名称

B2B客户现在可以在发票上显示其法定企业名称，而不是买家的个人姓名。当在结账时提供有效的税号时，您还可以收集相关的customer_business_name，以便发票反映购买实体。

当客户在结账时选择以企业名义购买时，将提示他们输入企业名称和税号。只有当所有三个条件都满足时，企业名称才会出现在发票上：

交易是B2B (b2b = true)
存在tax_id
提供了非空的customer_business_name

否则将使用客户的个人姓名。 在结账时收集 直接设置customer_business_name，和/或启用allow_customer_editing_business_name以允许客户输入或编辑它与他们的税号一起在结账页面上：

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_abc', quantity: 1 }],
  customer: { email: 'buyer@acme.com' },
  tax_id: 'GB123456789',
  customer_business_name: 'Acme Corp Ltd',
  feature_flags: {
    allow_tax_id: true,
    allow_customer_editing_business_name: true // let the customer enter/edit it
  },
  return_url: 'https://yoursite.com/return'
});

它的适用范围

表面	字段	备注
结账会话	`customer_business_name`, `feature_flags.allow_customer_editing_business_name`	最大250个字符；标识默认值为`false`
付款	`customer_business_name`	最大250个字符
订阅	`customer_business_name`	通过`PATCH /subscriptions/{id}` 设置或清除

customer_business_name 不能在没有 tax_id 的情况下设置。发送没有税号的企业名称将被拒绝。清除tax_id也将清除企业名称，因为两者在发票上是耦合的。

周围的空白会被裁剪，而仅空白值被视为明确清除——因此存储的数据始终与发票上的渲染匹配。

了解更多：B2B支付 | 发票管理 | 结账会话

错误修复和改进

平台各处的小错误修复和稳定性改进。

​新功能

​1. 订阅支付重试

​2. 业务按比例计算设置

​3. 为B2B发票收集企业名称

​错误修复和改进

新功能

1. 订阅支付重试

2. 业务按比例计算设置

3. 为B2B发票收集企业名称

错误修复和改进