如何判断 Chargify Statement 是否为 Paid

2026-10-24支付小周

结论

判断 Chargify Statement 是否为 Paid，应查看 settled_at 字段：

settled_at 有时间值：Statement 已结清，状态为 Paid
settled_at 为 null：Statement 尚未结清，状态为 Unpaid

不要只用 ending_balance_in_cents === 0 判断付款状态。这个字段表示周期结束时的账户余额，不能直接代表 Statement 是否已付款。

为什么 Ending Balance 不为 0 仍可能是 Paid

ending_balance_in_cents 有三种可能：

大于 0：客户仍有欠款
等于 0：余额正好结清
小于 0：客户账户中有 credit，也就是商家欠客户款项，或客户有可用于抵扣的余额

所以，当 Ending Balance 为负数时，虽然它不等于 0，但客户并没有应付余额，Statement 仍可能显示为 Paid。

Statement 的余额也可能受付款、退款、credits、调整和后续账户活动影响。只根据余额数值推断状态，结果可能与 Chargify 记录的结清状态不一致。

判断示例

假设 Statement API 返回：

{
  "statement": {
    "id": 123456,
    "starting_balance_in_cents": 0,
    "ending_balance_in_cents": -500,
    "settled_at": "2024-01-15T10:30:00-05:00"
  }
}

这里的 ending_balance_in_cents 虽然是 -500，但 settled_at 已有值，因此该 Statement 应判断为 Paid。

JavaScript 示例：

function getStatementStatus(statement) {
  return statement.settled_at ? "paid" : "unpaid";
}

const status = getStatementStatus(response.statement);

PHP 示例：

function getStatementStatus(array $statement): string
{
    return !empty($statement['settled_at']) ? 'paid' : 'unpaid';
}

如果业务中还要显示当前余额，可以分别处理状态和余额：

function normalizeStatement(statement) {
  return {
    status: statement.settled_at ? "paid" : "unpaid",
    balanceInCents: statement.ending_balance_in_cents,
    hasCredit: statement.ending_balance_in_cents < 0
  };
}

注意事项

settled_at 是 Chargify 认定 Statement 已结清的时间。与自行比较 ending_balance_in_cents 相比，它更适合用于判断状态。

如果实际 API 响应中没有 settled_at，请先确认：

查询的是 Statement 详情接口，而不是仅返回部分字段的列表或报表接口；
当前使用的 Chargify／Maxio API 版本是否仍会返回旧版 Statement 字段；
响应是否被本地模型、SDK 或中间服务裁剪过。

如果无法取得 settled_at，可以用 ending_balance_in_cents <= 0 近似判断“当前没有应付余额”，但这个结果不一定与 Chargify 界面中的 Paid 状态完全一致。需要与后台展示严格一致时，应以 API 返回的结清字段或当前版本提供的正式状态字段为准。