> ## 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.

# 取消订阅

> 安排有效订阅在当前计费周期结束时取消。

请使用属于目标组织、且为全部权限或勾选了 `sales:subscriptions:write` 权限的 API 密钥进行认证。

* 在当前计费周期结束时取消。买家在 `currentPeriodEnd` 前仍可使用，`cancelAtPeriodEnd` 变为 `true`。
* Anyway 会向买家发送取消确认邮件，并触发常规的订阅 Webhook，无需你另行发送。
* 可安全重试：对已安排取消的订阅再次调用，返回 `200` 和相同的响应内容。
* 响应与[查看订阅记录](https://docs.anyway.sh/zh/api-reference/endpoint/get-subscription.md)返回的订阅对象相同。

| 状态码 | 错误码 | 含义 |
| - | - | - |
| `403` | `INSUFFICIENT_SCOPE` | 密钥缺少 `sales:subscriptions:write`。 |
| `404` | | 订阅 ID 不存在，或属于其他组织。 |
| `409` | `SUBSCRIPTION_NOT_CANCELABLE` | 订阅不是有效状态（待支付、已暂停、已取消、已过期或已结束）。 |
| `500` | `INTERNAL_ERROR` | 我方内部错误。取消可能已生效，可安全重试。 |
| `502` | `PROVIDER_ERROR` | 支付服务商调用失败。取消可能未生效，可安全重试。 |


## OpenAPI

````yaml api-reference/openapi.json POST /v1/subscriptions/{id}/cancel
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/subscriptions/{id}/cancel:
    post:
      tags:
        - subscriptions
      summary: Cancel a subscription at period end
      description: >-
        Cancels an active subscription at the end of the current billing period;
        the buyer keeps access until `currentPeriodEnd`. Calling it again on a
        subscription already set to cancel returns 200 with the same body.
        Requires Full access or the `sales:subscriptions:write` permission.
      parameters:
        - description: Subscription ID
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-merchantapi_SubscriptionResponse
        '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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '409':
          description: >-
            Conflict. The subscription is not active
            (SUBSCRIPTION_NOT_CANCELABLE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '500':
          description: >-
            Internal Server Error (INTERNAL_ERROR). The cancel may have taken
            effect; retrying is safe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '502':
          description: >-
            Bad Gateway. The payment provider call failed (PROVIDER_ERROR); the
            cancel may not have taken effect, retrying is safe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
      security:
        - APIKeyAuth: []
components:
  schemas:
    response.ApiResponse-merchantapi_SubscriptionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/merchantapi.SubscriptionResponse'
        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
    merchantapi.SubscriptionResponse:
      type: object
      properties:
        amountCents:
          type: integer
        billingInterval:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
        cancelAtPeriodEnd:
          type: boolean
        canceledAt:
          type: string
        createdAt:
          type: string
        currency:
          type: string
        currentPeriodEnd:
          type: string
        customerEmail:
          type: string
        customerId:
          type: string
        endedAt:
          type: string
        id:
          description: 'Deprecated: use subscriptionId.'
          type: string
          deprecated: true
        initialOrderId:
          type: string
        latestOrderId:
          type: string
        productId:
          type: string
        productName:
          type: string
        status:
          type: string
        subscriptionId:
          type: string
        updatedAt:
          type: string
    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.