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

# 更新订阅计划

Localpayment 允许您修改现有订阅计划，以适应定价策略、账单周期或服务内容的变更。本指南详细介绍了如何通过 Localpayment 的 API 更新订阅计划，确保现有订阅能够按照新条款或您配置的策略继续有效。

## 开始之前

请确保您已备好：

> [card] [API凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)
>
> 用于身份验证的有效 API 凭据和访问令牌。

> [card] [账户设置](https://docs.localpayment.com/zh/docs/make-your-first-test-payment.md)
>
> 为您的目标国家/地区正确设置账户并进行业务验证。

> [card] [IP白名单](https://docs.localpayment.com/zh/docs/dashboard-whitelist-your-ips.md)
>
> 将服务器 IP 地址加入 API 访问白名单。

> [card] [Webhook endpoint](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置 webhook URL 以接收付款通知。

***

## 步骤 1：更新订阅计划

要修改现有订阅计划，请向[更新订阅计划](https://docs.localpayment.com/zh/reference/update-subscription-plan)endpoint 发送 `PATCH` 请求。

### 关键请求参数

该请求需要几个关键参数：

| 参数 | 说明 | 必需的 |
| - | - | - |
| `amount` | 更新后的账单金额 | ❌ |
| `autoRecurring` | 更新自动定期计费配置 | ❌ |
| `autoRecurring.repetitions` | 更新后的计费周期数（按需定期收费请使用 `0`） | ❌ |
| `autoRecurring.type` | 更新后的计费频率单位（按需定期收费请使用 `custom`） | ❌ |

### 支持的计费频率

> [card] 每日
>
> 更新为每日计费。非常适合正在过渡到按日计费模式的服务。
>
> 发送 `autoRecurring.type` 属性，值为：`day`

> [card] 月度
>
> 改为按月结算。这是为了统一各产品线的结算周期。
>
> 发送 `autoRecurring.type` 属性，值为：`month`

> [card] 定制（按需）
>
> 升级为按需计费。适用于向基于使用量的定价模式过渡。
>
> 发送 `autoRecurring.type` 属性，值为：`custom`

### 示例请求

以下是一个使用 `curl` 的示例：

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request PATCH \
  --url 'https://api.stage.localpayment.com/api/subscriptions/plan/{internalId}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 150,
    "autoRecurring": {
      "repetitions": 1,
      "type": "month"
    }
  }'
```

查看请求中所有[可用参数](https://docs.localpayment.com/zh/reference/update-subscription-plan)。

***

## 步骤 2：处理响应

### 成功响应

订阅计划更新成功后，会返回当前状态的确认信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "internalId": "106e9aff-96da-42e9-a9e1-4dee207e6073",
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan was update"
    }
}
```

### 关键响应字段

| 参数 | 说明 | 用例 |
| - | - | - |
| `internalId` | Localpayment 的唯一计划标识符。 | 请确认您已更新正确的计划。 |
| `status.code` | 当前计划状态代码。 | 确认更新后该计划仍然有效。 |
| `status.description` | 人类可读的状态描述。 | 在管理界面中显示状态。 |
| `status.detail` | 详细状态信息。 | 确认更新操作成功。 |

### 错误响应

订阅计划更新失败时，您将收到详细的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "400",
    "description": "REJECTED",
    "detail": "amount must be greater than or equal to 1"
  }
}
```

***

## 步骤 3：跟踪交易状态

订阅计划更新后，可通过以下方式监控其状态：

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 交易状态变更时接收实时通知。最适用于生产环境。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

| 代码 | 状态 | 说明 |
| :- | :- | :- |
| `100` | `ACTIVE` | 该计划已生效，可供订阅关联使用。 |
| `400` | `REJECTED` | 由于验证错误或参数无效，计划更新失败。 |

> [!NOTE]
>
> **完整参考**
>
> 请查看我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)，了解所有状态代码。

***

## 测试您的集成

### 测试场景

请确认您的集成方案能够处理以下场景：

1. **金额更新成功**：使用有效的金额值修改计划价格。
2. **计费频率变更**：从每月计费更新为每日计费或自定义计费。
3. **部分更新**：仅修改特定字段，无需发送完整数据。
4. **验证错误**：使用无效金额、缺少必填字段或不支持的频率进行测试。
5. **不存在的计划**：尝试更新一个不存在的计划。
6. **身份验证失败**：使用无效或过期的访问令牌进行测试。

***

## 后续步骤

更新订阅计划后，您可能需要执行其他操作：

> [card] [创建新的订阅计划](https://docs.localpayment.com/zh/docs/create-a-subscription-plan.md)
>
> 为不同的价格等级或服务等级设置额外的订阅计划。

> [card] [使用更新后的计划创建订阅](https://docs.localpayment.com/zh/docs/create-a-subscription.md)
>
> 使用更新后的套餐创建新的订阅来测试更改。

> [card] [获取订阅计划详情](https://docs.localpayment.com/zh/docs/get-subscription-plan.md)
>
> 获取更新后的计划信息，以核实所有变更是否已应用。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.