如何通过Stripe API获取用户订阅历史与计划历程（含改版前用户）

直接从**订阅（Subscriptions）和发票（Invoices）**API入手，比通过Payment Intents倒推更准确，以下是具体步骤：

核心思路 #

Stripe的订阅记录本身会留存所有版本（包括已取消、已过期的），每个版本对应一次计划变更（如升级、降级、订阅/取消）；而发票则对应每个计费周期的实际计费计划，两者结合就能按时间顺序还原完整的订阅历程。

步骤1：拉取用户所有订阅记录（含历史版本） #

调用stripe.subscriptions.list接口，获取该用户所有状态的订阅，包括已取消、已过期的：

const subscriptions = await stripe.subscriptions.list({
  customer: 'cus_XXX', // 替换为目标用户的Stripe Customer ID
  status: 'all', // 拉取所有状态的订阅，而非仅活跃状态
  expand: ['data.items.data.price'] // 直接展开关联的Price对象，拿到计划信息
});

// 按订阅生效时间升序排序，得到计划变更的时间线
const sortedSubscriptions = subscriptions.data.sort((a, b) => a.start_date - b.start_date);

每个订阅对象的关键字段：

• start_date：订阅生效的时间戳（对应计划开始的时间）
• canceled_at：订阅取消的时间戳（若未取消则为null）
• items.data[0].price：该订阅对应的计划（Basic/Premium）信息，包含id、nickname等字段
• current_period_start/current_period_end：当前计费周期的起止时间

步骤2：拉取用户所有发票并按计费周期排序 #

调用stripe.invoices.list接口，获取用户所有发票，按计费周期的起始时间排序：

const invoices = await stripe.invoices.list({
  customer: 'cus_XXX',
  limit: 100, // 根据用户订阅时长调整，最多100条/次，需分页可循环调用
  expand: ['data.subscription', 'data.lines.data.price'] // 展开关联的订阅和Price
});

// 按计费周期起始时间升序排序，还原每个周期的实际计划
const sortedInvoices = invoices.data.sort((a, b) => a.period_start - b.period_start);

发票的关键作用：

• 验证订阅记录的计划信息：每个发票的lines.data[0].price就是该计费周期用户实际使用的计划
• 补充订阅空档期：部分场景（如试用、免费订阅）可能没有订阅记录，但会生成发票，需纳入历程

步骤3：合并数据构建完整历程 #

1. 先基于sortedSubscriptions梳理出计划变更的关键节点：

   • 第一个订阅的start_date是用户首次订阅的时间
   • 后续每个订阅的start_date对应计划升级/降级的生效时间
   • 每个订阅的结束时间为canceled_at（若存在）或当前时间

2. 再用sortedInvoices补全每个时间区间内的计费细节：

   • 每个发票的period_start/period_end对应该周期的服务时间，与订阅的时间区间一一对应
   • 若遇到订阅记录缺失的情况（如早期未创建订阅仅生成发票），直接用发票的Price信息填充计划历程

解决Price ID排序问题的关键 #

不要单独提取发票行项目的Price ID排序，而是先按发票的period_start排序，再提取对应Price。因为发票的计费周期与订阅的生效周期完全绑定，按周期时间排序后，Price的顺序就是用户实际使用计划的时间顺序。

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