> ## 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/create-a-subscription.md)endpoint 发送 `PATCH` 请求。

### 关键请求参数

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

| 参数 | 说明 |
| - | - |
| `amount` | 新的订阅金额 |
| `card` | 包含更新后支付详情的卡对象 |
| `autoRecurring` | 计费频率和重复设置 |
| `discount` | 应用于订阅的折扣配置 |
| `retry` | 扣款失败时的支付重试配置 |
| `dateToUpdate` | 变更生效的具体日期 |
| `suspension` | 订阅暂停设置 |
| `status` | 订阅状态变更（例如暂停/恢复） |

### 示例请求

以下是使用 `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/payin/subscriptions/{externalId} \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "dateToUpdate": "2025-10-28",
    "amount": 1600.00,

   "autoRecurring": {
        "repetitions": "2",
        "type": "hour"
    },

   "retry": {
    "repetitions": 2,
    "intervalUnit": "day",
    "intervalValue": 1
  }
}
'

```

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

***

## 步骤 2：处理响应

### 成功响应

更新成功后将返回修改后的订阅详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "564b161a-76ba-4a84-b5cf-583f2df8c377",
  "internalId": "52425bbd-b68b-4abc-9480-5ae88d53adb3",
  "status": {
    "code": "107",
    "description": "APPROVED",
    "detail": "Update subscription success"
  },
  "errors": []
}
```

### 关键响应字段

| 参数 | 说明 | 用例 |
| - | - | - |
| `status.code` | 当前订阅状态码。 | 状态监控。 |

### 错误响应

请求失败时，您将收到详细的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "400",
    "description": "ERROR",
    "detail": "Invalid operation"
  }
}
```

***

## 步骤 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)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

Localpayment API 提供各种状态代码，以在响应中指示付款的进度和结果。

| 代码 | 状态 | 说明 |
| :- | :- | :- |
| `107` | `APPROVED` | 更新已获批准并已应用。 |
| `400` | `ERROR` | 订阅更新已被拒绝。 |

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

***

## 测试您的集成

### 测试场景

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

1. **成功升级套餐**：提高订阅等级或金额。
2. **成功降级套餐**：降低订阅等级或金额。
3. **支付方式更新**：更改银行卡详情。
4. **客户信息更新**：修改客户详情。
5. **验证错误**：金额无效、缺少必填字段。
6. **状态更新**：Webhook 处理和状态轮询

***

## 后续步骤

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

> [card] [取消订阅](https://docs.localpayment.com/zh/docs/cancel-a-subscription.md)
>
> 当更新不足以满足需求时，终止有效订阅。

> [card] [处理订阅 Webhook](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置 Webhook 以接收订阅更新事件的通知。

> [card] [创建订阅计划](https://docs.localpayment.com/zh/docs/create-a-subscription-plan.md)
>
> 创建可在更新订阅时使用的新计划。


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