新功能
1. 第三方分析支持
通过 Google Analytics 4、Google Tag Manager 和 Meta Pixel 跟踪 Storefront、Checkout 和 Customer Portal 中的客户行为。在 Settings → Analytics 中添加您的跟踪 ID 以开始收集电子商务事件。
支持的平台
| Platform | ID Format |
|---|
| Google Analytics 4 | G-XXXXXXXXXX |
| Google Tag Manager | GTM-XXXXXXX |
| Meta Pixel | Numeric (10-20 digits) |
purchase、add_payment_info、view_item 和 view_item_list 这样的事件会自动发送到您的分析平台。
支持 Storefront、托管 Checkout、覆盖/嵌入式 Checkout 以及 Customer Portal。
2. 结账主题自定义
在创建结账会话时通过 customization.theme_config 参数自定义结账外观。可配置浅色和深色模式下的颜色、字体、边框半径以及按钮文本。
配置选项
| Property | Description |
|---|
light / dark | 各模式的配色方案 |
font_primary_url | 自定义字体 URL |
font_size | xs、sm、md、lg、xl、2xl |
radius | 边框半径（例如 8px） |
pay_button_text | 自定义按钮文本 |
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'prod_123', quantity: 1 }],
customization: {
theme_config: {
radius: '8px',
pay_button_text: 'Complete Purchase',
light: { button_primary: '#0066ff', text_primary: '#1a1a1a' },
dark: { button_primary: '#3385ff', text_primary: '#ffffff' }
}
},
return_url: 'https://yoursite.com/return'
});
3. 付款失败时防止更改方案
新的 on_payment_failure 参数用于订阅方案更改，在付款失败时控制行为。
| Mode | Behavior |
|---|
prevent_change | 在付款成功前保持当前方案 |
apply_change | 无论付款结果如何立即应用方案更改（默认） |
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_pro',
proration_billing_mode: 'prorated_immediately',
on_payment_failure: 'prevent_change'
});
对于您希望在授予高级功能访问前确保付款成功的关键升级，请使用 prevent_change。
API 更新
余额分类账 API
新增 GET /balances/ledger 端点，可通过筛选和分页获取账户的分类账条目。
| Parameter | Description |
|---|
created_at_gte / created_at_lte | 按日期范围筛选 |
event_type | 按 payment、refund、dispute、payout 等筛选 |
currency | 按货币代码筛选 |
reference_object_id | 按特定付款/退款/争议 ID 筛选 |
付款响应：refund_status
在 GET /payments/{paymentId} 响应中新增 refund_status 字段，可快速检查付款是否已退款，而无需单独查询退款端点。
