New Features
1. Third-Party Analytics Support
Track customer behavior across Storefront, Checkout, and Customer Portal with Google Analytics 4, Google Tag Manager, and Meta Pixel. Add your tracking IDs in Settings → Analytics to start collecting e-commerce events.
Supported Platforms
| 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, and view_item_list are automatically sent to your analytics platforms as customers browse and complete purchases.
Supported on Storefront, hosted Checkout, overlay/inline Checkout, and Customer Portal.
2. Checkout Theme Customization
Customize checkout appearance via the customization.theme_config parameter when creating checkout sessions. Configure colors, fonts, border radius, and button text for both light and dark modes.
Configuration Options
| Property | Description |
|---|
light / dark | Color schemes for each mode |
font_primary_url | Custom font URL |
font_size | xs, sm, md, lg, xl, 2xl |
radius | Border radius (e.g., 8px) |
pay_button_text | Custom 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. Prevent Plan Change on Payment Failure
New on_payment_failure parameter for subscription plan changes controls behavior when payment fails.
| Mode | Behavior |
|---|
prevent_change | Keep subscription on current plan until payment succeeds |
apply_change | Apply plan change immediately regardless of payment outcome (default) |
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_pro',
proration_billing_mode: 'prorated_immediately',
on_payment_failure: 'prevent_change'
});
Use prevent_change for critical upgrades where you want to ensure payment before granting access to premium features.
API Updates
Balance Ledger API
New GET /balances/ledger endpoint to retrieve your account’s ledger entries with filtering and pagination.
| Parameter | Description |
|---|
created_at_gte / created_at_lte | Filter by date range |
event_type | Filter by payment, refund, dispute, payout, etc. |
currency | Filter by currency code |
reference_object_id | Filter by specific payment/refund/dispute ID |
Payment Response: refund_status
Added refund_status field to GET /payments/{paymentId} response to quickly check if a payment has been refunded without querying the refunds endpoint separately.
