v1.81.0 (February 6, 2026)

타사 분석, 체크아웃 테마 사용자 지정, 결제 실패 시 요금제 변경 방지, Balance Ledger API

​

새로운 기능

​

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로 필터링

자세히 알아보기: Balance Ledger API

​

결제 응답: refund_status

환불 엔드포인트를 별도로 조회하지 않고도 결제가 환불되었는지 빠르게 확인할 수 있도록 GET /payments/{paymentId} 응답에 refund_status 필드를 추가했습니다.