새로운 기능
1. 타사 분석 지원
Storefront, Checkout, Customer Portal 전반에서 Google Analytics 4, Google Tag Manager, Meta Pixel로 고객 행동을 추적하세요. 설정 → 분석에서 추적 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 | 테두리 반경(e.g., 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 업데이트
Balance Ledger 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 필드를 추가했습니다.
