如何通过Metadata筛选Stripe结账会话？（多商户平台场景）

一、核心筛选逻辑 #

1. 买家端获取购买记录 #

Stripe结账会话默认自带customer关联字段（创建会话时需传入买家对应的Stripe Customer ID），直接通过该字段筛选即可，无需依赖自定义metadata。

2. 卖家端获取售出记录 #

利用你已在metadata中存储的seller_id，通过Stripe API的metadata专属筛选语法过滤会话。

二、代码实现示例（以Node.js SDK为例） #

1. 买家购买记录查询方法 #

async function getBuyerCheckoutList(buyerStripeCustomerId) {
  const sessions = await stripe.checkout.sessions.list({
    customer: buyerStripeCustomerId,
    status: 'complete', // 仅返回已完成交易，可按需调整状态
    limit: 100, // Stripe单次返回上限100条，需分页则循环调用
  });

  // 格式化返回前端所需字段
  return sessions.data.map(session => ({
    sessionId: session.id,
    orderId: session.metadata.order_id,
    totalAmount: session.amount_total / 100, // 转换为元（Stripe以分为单位）
    createTime: new Date(session.created * 1000),
    sellerId: session.metadata.seller_id,
    buyerEmail: session.customer_details?.email
  }));
}

2. 卖家售出记录查询方法 #

async function getSellerCheckoutList(sellerId) {
  const sessions = await stripe.checkout.sessions.list({
    'metadata[seller_id]': sellerId, // 关键：通过metadata字段精准筛选
    status: 'complete',
    limit: 100,
  });

  return sessions.data.map(session => ({
    sessionId: session.id,
    orderId: session.metadata.order_id,
    totalAmount: session.amount_total / 100,
    createTime: new Date(session.created * 1000),
    buyerEmail: session.customer_details?.email
  }));
}

三、关键注意事项 #

• 会话创建时的必填配置：
  • 买家端：创建结账会话必须传入customer参数（关联买家的Stripe Customer对象），否则无法通过该字段筛选。
  • 卖家端：确保metadata.seller_id存储为字符串类型（Stripe metadata仅支持字符串值）。
• 状态筛选：建议保留status: 'complete'过滤无效会话，若需展示未支付/取消状态，可移除该条件或指定其他状态（如open、expired）。
• 分页处理：若交易记录超过100条，需通过starting_after参数循环调用API，直到返回数据为空。
• 性能优化：高交易量平台建议定期将Stripe会话数据同步到自有数据库，后续查询直接从本地库获取，减少API调用开销。

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