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

# 取消訂閱

> 取消訂閱並自動產生取消事件 (`cancel`)。

### cancelled_at 預設行為
若未提供 `cancelled_at`，將使用**當前時間**。




## OpenAPI

````yaml /api-reference/openapi.yaml put /subscriptions/{id}/cancel
openapi: 3.0.3
info:
  title: 帳獸 Zangsho API
  description: |
    帳獸（Zangsho）是一個專為亞洲電商與 SaaS 企業設計的營收分析平台。

    ## 🔐 認證

    使用 **Bearer Token** 進行 API 認證。Token 可在商家後台的「API 設定」頁面取得。

    ```bash
    curl -H "Authorization: Bearer YOUR_API_TOKEN" \
         https://api.zangsho.com/v1/customers
    ```

    ## ⏱️ 頻率限制

    | 限制類型 | 額度 | 說明 |
    |---------|------|------|
    | 已認證請求 | 3,600 次/小時 | 依商家 ID 計算 |
    | 未認證請求 | 10 次/分鐘 | 依 IP 計算 |

    每個回應都包含以下 headers：
    - `X-RateLimit-Limit`: 限制額度
    - `X-RateLimit-Remaining`: 剩餘次數
    - `X-RateLimit-Reset`: 重置時間 (Unix timestamp)

    ## 📦 批次匯入

    - 每次請求最多 **100 筆**
    - 採用**部分成功策略**（不全部回滾）
    - 回傳 `created`/`updated`/`skipped`/`failed` 詳細結果
    - ⚠️ **批次匯入不觸發 Webhook**（僅記錄 Activity Log），如需觸發 Webhook 請使用單筆 API

    ## 🕐 時間格式

    所有時間欄位使用 **ISO 8601 格式（UTC）**，例如：`2026-01-09T08:00:00Z`

    商家需自行將本地時間轉換為 UTC 後傳入。
  version: 1.0.0
  contact:
    name: Zangsho Support
    email: support@zangsho.com
  x-logo:
    url: https://zangsho.com/logo.png
    altText: 帳獸 Zangsho Logo
servers:
  - url: https://api.zangsho.com/v1
    description: Production
  - url: http://zangsho.test:81/api/v1
    description: Development
security:
  - bearerAuth: []
tags:
  - name: Customers
    description: |
      客戶管理 API

      客戶是所有分析的基礎，包含 LTV（客戶終身價值）、訂單歷史等資訊。
  - name: Orders
    description: |
      訂單管理 API

      訂單是營收分析的核心，支援批次匯入歷史資料。
  - name: Subscriptions
    description: |
      訂閱管理 API

      訂閱用於計算 MRR（月經常性收入）、Churn Rate 等 SaaS 指標。
  - name: Subscription Events
    description: |
      訂閱事件 API

      記錄訂閱的升級、降級、取消等事件，用於分析客戶旅程。
paths:
  /subscriptions/{id}/cancel:
    put:
      tags:
        - Subscriptions
      summary: 取消訂閱
      description: |
        取消訂閱並自動產生取消事件 (`cancel`)。

        ### cancelled_at 預設行為
        若未提供 `cancelled_at`，將使用**當前時間**。
      operationId: cancelSubscription
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelSubscriptionRequest'
            example:
              cancelled_at: '2026-01-09T00:00:00Z'
              reason: no_longer_needed
      responses:
        '200':
          description: 訂閱取消成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    CancelSubscriptionRequest:
      type: object
      properties:
        cancelled_at:
          type: string
          format: date-time
          description: 取消時間（未提供則使用當前時間）
        reason:
          type: string
          description: 取消原因
          example: no_longer_needed
    SubscriptionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Subscription'
    Subscription:
      type: object
      properties:
        id:
          type: integer
        customer_id:
          type: integer
        status:
          type: string
          enum:
            - active
            - cancelled
            - paused
        plan_name:
          type: string
        mrr:
          type: string
          description: 月經常性收入
        billing_cycle:
          type: string
        source:
          type: string
          enum:
            - api
            - inferred
          description: |
            資料來源：
            - `api`：透過 API 建立
            - `inferred`：系統從訂單推導
        started_at:
          type: string
          format: date-time
        current_period_start:
          type: string
          format: date-time
        cancelled_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: 未認證或 Token 無效
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthenticated.
    NotFound:
      description: 資源不存在
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Resource not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum Token
      description: |
        使用 Laravel Sanctum Token 進行認證。

        Token 可在商家後台的「API 設定」頁面取得。

````