Novos Recursos
1. Suporte a Analytics de Terceiros
Acompanhe o comportamento dos clientes no Storefront, Checkout e Portal do Cliente com Google Analytics 4, Google Tag Manager e Meta Pixel. Adicione seus IDs de acompanhamento em Configurações → Analytics para começar a coletar eventos de e-commerce.
Plataformas Compatíveis
| 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 e view_item_list são enviados automaticamente às suas plataformas de analytics conforme os clientes navegam e concluem compras.
Compatível com Storefront, Checkout hospedado, Checkout em overlay/inline e Portal do Cliente.
2. Personalização do Tema do Checkout
Customize a aparência do checkout por meio do parâmetro customization.theme_config ao criar sessões de checkout. Configure cores, fontes, raio das bordas e texto dos botões para os modos claro e escuro.
Opções de Configuração
| Property | Description |
|---|
light / dark | Schemes de cores para cada modo |
font_primary_url | URL de fonte personalizada |
font_size | xs, sm, md, lg, xl, 2xl |
radius | Raio de borda (por exemplo, 8px) |
pay_button_text | Texto personalizado do botão |
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. Evitar Troca de Plano em Caso de Falha no Pagamento
Novo parâmetro on_payment_failure para mudanças de plano de assinatura controla o comportamento quando o pagamento falha.
| Mode | Behavior |
|---|
prevent_change | Mantém a assinatura no plano atual até o pagamento ser concluído com sucesso |
apply_change | Aplica a mudança de plano imediatamente independentemente do resultado do pagamento (padrão) |
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_pro',
proration_billing_mode: 'prorated_immediately',
on_payment_failure: 'prevent_change'
});
Use prevent_change para upgrades críticos em que deseja garantir o pagamento antes de conceder acesso a recursos premium.
Atualizações da API
API de Razão Financeira
Novo endpoint GET /balances/ledger para recuperar as entradas do razão da sua conta com filtros e paginação.
| Parameter | Description |
|---|
created_at_gte / created_at_lte | Filtrar por intervalo de datas |
event_type | Filtrar por payment, refund, dispute, payout etc. |
currency | Filtrar por código de moeda |
reference_object_id | Filtrar por ID específico de pagamento/reembolso/disputa |
Resposta de Pagamento: refund_status
Adicionado campo refund_status à resposta GET /payments/{paymentId} para verificar rapidamente se um pagamento foi reembolsado sem consultar separadamente o endpoint de reembolsos.
