如何使用 PHP API 更新 Chargify 的 next_billing_at？

2026-10-24数据小陈

结论

可以通过 Chargify API 修改订阅的下一次计费时间。多数情况下，问题不在日期格式，而在请求体结构。next_billing_at 必须放在 subscription 对象中，不能直接作为 JSON 的顶层字段发送。

正确的请求结构

更新 Chargify 订阅时，请使用类似下面的 JSON：

{
  "subscription": {
    "next_billing_at": "2013-04-20T02:52:17-04:00"
  }
}

对应的 PHP 代码如下：

$requestArr = array(
    'subscription' => array(
        'next_billing_at' => '2013-04-20T02:52:17-04:00'
    )
);

try {
    $connector->requestUpdateSubscription(
        $thisSubscriptionID,
        json_encode($requestArr),
        'JSON'
    );
} catch (ChargifyValidationException $cve) {
    echo $cve->getMessage();
}

更新已有订阅时，通常不必再次传入 customer_id，因为订阅 ID 已经确定了要修改的订阅。

为什么原来的代码没有生效

原请求生成的 JSON 是：

{
  "customer_id": "12345",
  "next_billing_at": "2013-04-20T02:52:17-04:00"
}

这里的 next_billing_at 没有放在 subscription 节点内，Chargify 可能会忽略这个嵌套位置不正确的字段。部分 API 或客户端版本不会因此抛出验证异常，所以请求没有报错，并不表示字段已经更新。

检查更新结果

更新完成后，重新获取订阅，并检查返回对象中的 next_assessment_at：

$subscriptionUpdated = $connector->getSubscriptionsByID(
    $thisSubscriptionID
);

$newBillingDate = $subscriptionUpdated->next_assessment_at;

echo "new next billing date is {$newBillingDate}\n";

更新请求使用的参数名是 next_billing_at，订阅响应中表示下一次评估或计费时间的字段则可能是 next_assessment_at。两者用在不同位置。不要把查询字段也改成 next_billing_at，除非当前 API 版本的响应明确包含该字段。

日期格式

建议使用包含时区的 ISO 8601 时间：

2013-04-20T02:52:17-04:00

也可以按照当前 Chargify API 版本支持的格式使用 UTC：

2013-04-20T06:52:17Z

如果只传入：

2013-04-20

由于缺少具体时间和时区，可能产生歧义。即使某些版本接受纯日期，显式提供完整时间也更稳妥。

注意事项

next_billing_at 必须位于 subscription 对象内。
新时间通常需要晚于当前时间，并处于订阅当前状态允许调整的计费范围内。
修改计费日期可能影响立即计费、试用期、余额结转或组件计费。实际行为取决于 Chargify/Maxio 当前的 API 规则和站点配置。
如果字段正确嵌套后仍未更新，请记录并检查客户端返回的 HTTP 状态码和原始响应体。这个 PHP 客户端可能只在遇到特定错误时抛出 ChargifyValidationException。
Chargify-PHP-Client 是较早的第三方客户端。如果它的请求封装与当前 API 不兼容，可以直接发送 PUT /subscriptions/{id}.json 请求，并沿用相同的 subscription 嵌套结构。