stripe 官方 api 不提供直接获取“最新单条用量记录”的端点，但可通过分页查询用量记录摘要（usagerecordsummary），并按时间倒序排列后取首条，间接实现该目标。
stripe 官方 api 不提供直接获取“最新单条用量记录”的端点，但可通过分页查询用量记录摘要（usagerecordsummary），并按时间倒序排列后取首条，间接实现该目标。
在 Stripe 的用量计量（Usage-Based Billing）体系中，UsageRecord 本身是不可直接检索的临时事件——它仅用于向订阅项（SubscriptionItem）上报用量，并触发计费逻辑；而真正可供查询、聚合与审计的是其对应的用量记录摘要（UsageRecordSummary）。该资源由 Stripe 自动按小时/天聚合生成，包含 period.start、period.end、total_usage 等关键字段，且默认按 created 时间降序排列。
因此，要获取“最近一次上报的用量记录所对应的摘要”，正确做法是调用 SubscriptionItem 下的用量摘要列表接口，并显式指定 limit=1 与 order=desc（PHP SDK 默认即为降序）：
\Stripe\Stripe::setApiKey('sk_test_...');
try {
$summaries = \Stripe\UsageRecordSummary::all([
'subscription_item' => 'si_xxx', // 替换为你的 subscription_item ID
'limit' => 1,
'expand' => ['data.price'], // 可选：展开关联 Price 对象
]);
if ($summaries->data) {
$latestSummary = $summaries->data[0];
echo "最新用量周期：{$latestSummary->period->start} – {$latestSummary->period->end}\n";
echo "总用量：{$latestSummary->total_usage}\n";
echo "创建时间：". date('Y-m-d H:i:s', $latestSummary->created) . "\n";
} else {
echo "暂无用量记录摘要。\n";
}
} catch (\Stripe\Exception\ApiErrorException $e) {
error_log("Stripe API 错误: " . $e->getMessage());
}⚠️ 重要注意事项：
- UsageRecordSummary 是聚合视图，不是原始 UsageRecord。原始上报记录（如 createUsageRecord() 调用）无法通过公开 API 回溯；
- 摘要数据通常在用量发生后 10–30 分钟内生成，存在轻微延迟，请勿在上报后立即查询；
- 若需精确追踪每次脚本执行的用量（例如每小时上报一次），建议在本地数据库或缓存中持久化 timestamp 和 quantity，将 Stripe 作为计费权威源，而非审计日志源；
- limit=1 配合默认降序可确保高效获取最新摘要，避免拉取全量数据造成性能与配额浪费。
✅ 总结：虽然 Stripe 不支持直接 GET /v1/usage_records/latest，但 UsageRecordSummary::all(['limit' => 1]) 是生产环境中稳定、高效且符合设计意图的替代方案。结合本地状态管理，即可构建健壮的用量监控与对账流程。
