Cashier 10 的 metered billing 应选择 Meters 还是 legacy metered us

2026-10-24支付阿杰

结论

应选择 legacy metered usage。

Cashier 10 的计量计费功能基于 Stripe 旧版 Usage Records API，例如 reportUsage() 和 reportUsageFor()。新式 Meters 使用另一套 Stripe Billing Meter API，不能直接使用 Cashier 10 的这些方法。

原因

两种计量方式使用的底层接口不同：

legacy metered usage：通过订阅项目提交 usage record，Cashier 10 原生支持这种方式。
Meters：通过 meter event 上报用量，是 Stripe 后来推出的计量模型。
Cashier 10 不会自动将 reportUsage() 转换为 meter event。
如果产品使用 Meters，调用 Cashier 10 的旧式用量上报方法通常无法按预期完成计费。

因此，如果要继续使用 Cashier 10 提供的计量计费封装，Stripe Price 应配置为旧式 metered usage。

配置步骤

在 Stripe Dashboard 中创建 Product 和 Price 时：

创建或选择一个 Product。
将 Price 设置为 recurring。
选择 usage-based pricing。
计量方式选择 legacy metered usage，不要选择新式 Meters。
根据业务需要设置用量聚合方式，例如求和或取最大值。
保存生成的 Price 或旧版 Plan 标识。
使用该标识通过 Cashier 创建订阅。
业务产生用量后，通过 Cashier 上报 usage record。

Stripe Dashboard 的具体界面名称可能会调整，但判断标准不变：Cashier 10 需要一个能够通过订阅项目的 Usage Records API 上报用量的 Price。

上报用量示例

只有一个计量项目时，可以使用 reportUsage()：

$subscription = $user->subscription('default');

$subscription->reportUsage(5);

如果订阅包含多个 Price，需要明确指定接收用量的计量项目：

$subscription = $user->subscription('default');

$subscription->reportUsageFor('price_metered', 5);

如果需要指定用量发生的时间，可以传入时间戳：

$subscription->reportUsage(5, now()->timestamp);

具体可用的方法签名应以项目安装的 Cashier 10 小版本为准。不同小版本和 Stripe SDK 版本可能使用 plan 或 price 作为标识名称，但底层仍是 legacy usage record 模型。

如果必须使用新式 Meters

如果现有 Stripe 产品已经配置为 Meters，就不应继续依赖 Cashier 10 的 reportUsage()。可以选择：

升级到明确支持 Stripe Meters 的 Cashier 版本。
绕过 Cashier 的用量上报封装，使用兼容版本的 Stripe SDK 直接发送 meter event。

伪代码结构如下。具体类名和参数必须以当前 Stripe PHP SDK 文档为准：

$stripe->billing->meterEvents->create([
    'event_name' => 'api_requests',
    'payload' => [
        'stripe_customer_id' => $user->stripe_id,
        'value' => '5',
    ],
]);

不要在同一个计量项目中混用新式 Meters 调用和 Cashier 10 的 reportUsage()，否则可能导致用量未计入账单、重复上报或账单聚合结果不一致。

注意事项

reportUsage() 上报的是用量，不会立即收费。Stripe 会根据 Price 的聚合规则和结算周期生成账单。
确认接收用量的订阅项目已经配置为 metered usage。
订阅包含多个项目时，应使用 reportUsageFor() 明确指定 Price，避免将用量记入错误的订阅项目。
重试上报时需要考虑幂等性，避免重复累计同一次业务用量。
如果准备长期使用 Stripe Meters，建议评估升级 Cashier，避免在 Cashier 10 上自行维护两套计量模型。