PAYATHON 2026

如何通过 API 暂停 Kill Bill subscription？

支付小周

明确结论

Kill Bill 支持暂停 subscription，但一般不是通过 update entitlement，而是为 subscription 添加一个 blocking state。

暂停时可以分别控制：

  • entitlement：停止向客户提供服务或商品；
  • billing：停止生成新的周期性费用；
  • subscription change：禁止在暂停期间变更套餐。

恢复时，调用相应的 unblock 接口即可。配送任务是否停止，则需要业务系统根据 Kill Bill 中的 entitlement 状态自行处理。Kill Bill 管理的是订阅、权益和计费状态，不会直接控制配送流程。

暂停 subscription

常见的 REST API 调用如下：

POST /1.0/kb/subscriptions/{subscriptionId}/block

请求体使用 BlockingState：

{
  "stateName": "PAUSED",
  "service": "delivery-service",
  "isBlockChange": true,
  "isBlockEntitlement": true,
  "isBlockBilling": true
}

对应的 curl 示例：

curl -X POST \
  'http://localhost:8080/1.0/kb/subscriptions/6f2d2d90-0000-0000-0000-000000000000/block' \
  -u 'admin:password' \
  -H 'Content-Type: application/json' \
  -H 'X-Killbill-ApiKey: bob' \
  -H 'X-Killbill-ApiSecret: lazar' \
  -H 'X-Killbill-CreatedBy: delivery-service' \
  -H 'X-Killbill-Reason: Customer holiday pause' \
  -d '{
    "stateName": "PAUSED",
    "service": "delivery-service",
    "isBlockChange": true,
    "isBlockEntitlement": true,
    "isBlockBilling": true
  }'

各字段应根据实际业务目标设置：

字段作用
isBlockEntitlement暂停客户享有的服务权益
isBlockBilling暂停后续计费
isBlockChange禁止在暂停期间变更 subscription
stateName业务状态名称，例如 PAUSED
service创建该状态的业务服务名称

如果只暂停配送但继续收费，可以将 isBlockBilling 设为 false。对于“客户度假，期间不配送也不收费”这类场景，一般应同时阻止 entitlement 和 billing。

恢复 subscription

通常通过 subscription 的 unblock 接口恢复：

DELETE /1.0/kb/subscriptions/{subscriptionId}/block

例如：

curl -X DELETE \
  'http://localhost:8080/1.0/kb/subscriptions/6f2d2d90-0000-0000-0000-000000000000/block' \
  -u 'admin:password' \
  -H 'X-Killbill-ApiKey: bob' \
  -H 'X-Killbill-ApiSecret: lazar' \
  -H 'X-Killbill-CreatedBy: delivery-service' \
  -H 'X-Killbill-Reason: Customer returned from holiday'

解除 blocking state 后，subscription 会继续使用原来的产品、套餐和订阅关系，无需重新创建。

不同 Kill Bill 版本的 unblock 路径、日期参数和请求形式可能略有不同，应以当前部署版本生成的 OpenAPI 文档为准。通常需要查找以下方法：

addSubscriptionBlockingState
unblockSubscription

延后到指定日期暂停

如果暂停需要在未来某天生效，可以使用当前 Kill Bill 版本支持的 requestedDate 或 effectiveDate 参数。例如，某些版本允许：

POST /1.0/kb/subscriptions/{subscriptionId}/block?requestedDate=2026-10-01

日期参数放在查询字符串还是 BlockingState 请求体中，取决于使用的 Kill Bill 版本和客户端库，不能假定所有版本都采用相同形式。

恢复也可以按同样的方式安排，在计划恢复日期执行 unblock。实际使用中，更常见的是由业务系统保存恢复时间，再通过定时任务在到期后调用解除阻塞接口。

注意计费边界

暂停 billing 时，需要确认以下行为：

  • 暂停从当前时间生效，还是从下一个账单周期生效；
  • 已生成的 invoice 是否仍需支付；
  • 当前计费周期是否需要按比例退款；
  • 恢复后是沿用原账单日期，还是重新计算计费周期；
  • 暂停期间的 usage 数据是否仍会上报和计费。

Blocking state 主要控制后续的 entitlement 和 billing，并不会自动撤销已经生成的 invoice。如果需要退款、作废 invoice 或增加 credit，还要另外调用支付或 invoice 相关 API。

Entitlement 和 subscription 的区别

entitlement 并不是 subscription 的另一个名称：

  • subscription 表示客户订阅的产品及其生命周期；
  • entitlement 表示客户当前是否有权使用该产品或服务；
  • billing 表示是否继续对该 subscription 计费。

Kill Bill 分别管理这几个维度，所以暂停功能并不是普通的 subscription 更新字段。Blocking state 可以同时或单独控制这些状态。对于配送订阅，业务系统还需要监听相应的状态或事件，在 entitlement 被阻止后停止生成配送订单，并在解除阻止后恢复配送。

备注：内容仅供参考。