如何通过Stripe接口获取各计费周期的完整使用明细历史

Stripe 按计费周期查询详细使用记录实现方案 #

stripe.SubscriptionItem.list_usage_record_summaries 接口返回的是指定订阅项按周期聚合的用量汇总，本身不包含单条使用上报的明细数据，要获取明细需要结合订阅项ID和时间范围查询所有上报的使用记录，具体实现步骤如下：

• 第一步：先调用stripe.SubscriptionItem.list_usage_record_summaries获取你需要查询的目标计费周期的起止时间戳
  接口返回的每个summary对象里的period.start和period.end就是对应计费周期的精确起止时间，把这两个值存下来作为后续查询明细的时间过滤条件
• 第二步：调用stripe.SubscriptionItem.list_usage_records接口，传入对应订阅项ID和上一步拿到的时间范围参数，就能拿到该周期内所有上报的详细使用记录
  核心参数说明：
  • subscription_item: 目标订阅项的ID，和你调用汇总接口时传的ID保持一致
  • created[gte]: 对应计费周期的开始时间戳，填第一步拿到的period.start
  • created[lte]: 对应计费周期的结束时间戳，填第一步拿到的period.end
  • 可选参数limit：单次查询返回的最大条数，默认10，最大可以设为100，如果明细条数超过100需要用分页参数starting_after/ending_before做分页拉取
• 示例代码（Python）：

# 1. 先拿周期汇总里的时间范围
summaries = stripe.SubscriptionItem.list_usage_record_summaries(
  "si_xxx", # 替换为你的订阅项ID
)
# 假设我们取第一个周期的时间查明细
target_period = summaries.data[0].period

# 2. 查该周期的详细使用记录
usage_records = stripe.SubscriptionItem.list_usage_records(
  "si_xxx",
  created={
    "gte": target_period.start,
    "lte": target_period.end
  },
  limit=100
)

# usage_records.data 里就是该周期的所有明细使用记录，每条包含上报时间、用量值、唯一ID、元数据等信息

• 注意事项：
  • 只有你主动通过stripe.SubscriptionItem.create_usage_record上报的使用记录才会被保留查询，Stripe不会自动生成使用记录
  • 使用记录的保留时长和你的Stripe账户数据保留策略一致，默认至少保留12个月的历史数据
  • 如果是用量按层级定价的订阅，明细记录里的quantity之和和对应周期汇总的total_usage值是完全一致的，可以用来做数据校验

内容的提问来源于stack exchange，提问作者tahayk