> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v1.81.0（2026 年 2 月 6 日）

> 第三方分析、结账主题自定义、付款失败时防止更改方案以及余额分类账 API

## 新功能

### 1. **第三方分析支持**

通过 Google Analytics 4、Google Tag Manager 和 Meta Pixel 跟踪 Storefront、Checkout 和 Customer Portal 中的客户行为。在 **Settings → Analytics** 中添加您的跟踪 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` 这样的事件会自动发送到您的分析平台。

<Check>
  支持 Storefront、托管 Checkout、覆盖/嵌入式 Checkout 以及 Customer Portal。
</Check>

了解详情：[Third-Party Analytics](/features/analytics)

### 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`  | 自定义按钮文本                        |

```typescript theme={null}
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'
});
```

了解详情：[Checkout Theme Customization](/features/checkout#checkout-theme-customization)

### 3. **付款失败时防止更改方案**

新的 `on_payment_failure` 参数用于订阅方案更改，在付款失败时控制行为。

| Mode             | Behavior             |
| ---------------- | -------------------- |
| `prevent_change` | 在付款成功前保持当前方案         |
| `apply_change`   | 无论付款结果如何立即应用方案更改（默认） |

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});
```

<Tip>
  对于您希望在授予高级功能访问前确保付款成功的关键升级，请使用 `prevent_change`。
</Tip>

了解详情：[Handling Payment Failures](/developer-resources/subscription-upgrade-downgrade#handling-payment-failures)

## API 更新

### 余额分类账 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](/api-reference/balance-ledger/list-ledger-entries)

### 付款响应：`refund_status`

在 `GET /payments/{paymentId}` 响应中新增 `refund_status` 字段，可快速检查付款是否已退款，而无需单独查询退款端点。