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

# 更新支付链接

> 修改支付链接的标题、描述或成功跳转地址。

请使用属于该支付链接所在组织、且为全部权限或勾选了 `products:payment_links:write` 权限（控制台中“可创建和修改”下的**支付链接**）的 API 密钥进行认证。只有 `Owner` 和 `Admin` 角色可以授予该权限。

* `linkId` 是你组织内的支付链接 ID，例如[读取产品支付链接](https://docs.anyway.sh/zh/api-reference/endpoint/get-product-payment-links.md)返回的条目。
* 请求体包含 `title`、`description` 和 `successUrl`，均为可选。只有你传入的字段会被修改。
* `successUrl` 是绝对 HTTPS 地址。传空字符串可清除，此时客户看到 Anyway 的收据页。
* 价格、货币和计费方式无法修改。若要以其他价格销售，请[创建新的支付链接](https://docs.anyway.sh/zh/api-reference/endpoint/create-product-payment-link.md)。
* 响应为更新后的完整链接（无论是否处于启用状态），结构与[读取产品支付链接](https://docs.anyway.sh/zh/api-reference/endpoint/get-product-payment-links.md)中的条目相同。
* 未知字段会被拒绝，返回 `400`。该接口没有 `Idempotency-Key`。

| 状态码 | 错误码 | 含义 |
| - | - | - |
| `400` | | 校验失败：`successUrl` 不是绝对 HTTPS 地址、未知字段，或值过长（`title` 最多 255 个字符，`description` 最多 2000，`successUrl` 最多 1000）。 |
| `401` | | API 密钥缺失或无效。 |
| `403` | `INSUFFICIENT_SCOPE` | 密钥缺少 `products:payment_links:write`。 |
| `404` | | 支付链接不存在，或属于其他组织。 |
| `413` | `PAYLOAD_TOO_LARGE` | 请求体超过 64 KiB。 |


## OpenAPI

````yaml api-reference/openapi.json PATCH /v1/payment-links/{linkId}
openapi: 3.0.3
info:
  description: >-
    Organization-scoped commerce API for merchant backends: create and manage
    checkout sessions, and query commerce records.
  title: Anyway Merchant API
  contact: {}
  version: '1.0'
  x-source: anyway-backend-go
servers:
  - url: https://merchant-api-prod.anyway.sh
security: []
paths:
  /v1/payment-links/{linkId}:
    patch:
      tags:
        - products
      summary: Update a payment link
      description: >-
        Changes a payment link's title, description or success URL; only the
        fields you send change. The response is the full link, active or not.
        Requires Full access or the `products:payment_links:write` permission.
        Price, currency and billing can't be changed; create a new payment link
        instead. `successUrl` must be an absolute HTTPS URL; an empty string
        clears it. Unknown request fields return 400. There is no
        Idempotency-Key.
      parameters:
        - description: Payment link ID
          name: linkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: Fields to change
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/product.UpdatePaymentLinkRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-product_PaymentLinkResponse
        '400':
          description: >-
            Bad Request. A successUrl that is not an absolute HTTPS URL, an
            unknown field, or a value that is too long (title 255, description
            2000, successUrl 1000).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '403':
          description: >-
            Forbidden. The API key lacks the required permission
            (INSUFFICIENT_SCOPE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '404':
          description: >-
            Not Found. The payment link does not exist or belongs to another
            organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '413':
          description: Request body larger than 64 KiB (`PAYLOAD_TOO_LARGE`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
      security:
        - APIKeyAuth: []
components:
  schemas:
    product.UpdatePaymentLinkRequest:
      type: object
      properties:
        title:
          type: string
          maxLength: 255
          description: New title shown on the pay page
        description:
          type: string
          maxLength: 2000
          description: New description shown on the pay page
        successUrl:
          type: string
          maxLength: 1000
          description: >-
            Absolute HTTPS URL to send the customer to after paying. Send an
            empty string to clear it.
    response.ApiResponse-product_PaymentLinkResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/product.PaymentLinkResponse'
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    response.ApiResponse-any:
      type: object
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    product.PaymentLinkResponse:
      type: object
      properties:
        amount:
          type: number
          nullable: true
        createdAt:
          type: string
        currency:
          type: string
        flexibleAmount:
          type: boolean
        isActive:
          type: boolean
        name:
          type: string
        paymentLinkUrl:
          type: string
        pricingId:
          type: string
        pricingType:
          type: string
        provider:
          type: string
        title:
          type: string
        description:
          type: string
        minAmount:
          type: number
          nullable: true
        maxAmount:
          type: number
          nullable: true
        successUrl:
          type: string
          description: >-
            Where the customer is sent after paying. Empty when the Anyway
            receipt is used.
    response.ErrorDetail:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    APIKeyAuth:
      description: 'Merchant API key (format: ak_BASE64)'
      type: apiKey
      name: X-API-Key
      in: header

````

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