新機能
1. サードパーティ分析のサポート
Google Analytics 4、Google Tag Manager、Meta Pixel を使用して、ストアフロント、チェックアウト、カスタマーポータル全体で顧客の行動をトラッキングできます。設定 → 分析にトラッキング ID を追加すると、e コマースイベントの収集が開始されます。
サポート対象プラットフォーム
| 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、ホスト型チェックアウト、重ね合わせ/インラインチェックアウト、およびカスタマーポータルでサポートされています。
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 フィールドを追加し、返金エンドポイントを別途問い合わせることなく支払いが返金されたかどうかを迅速に確認できるようになりました。
