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

# 更新訂閱

> 更新訂閱資料。

### 自動事件觸發
根據 MRR 變化自動產生事件：
- MRR 增加 → 升級事件 (`upgrade`)
- MRR 減少 → 降級事件 (`downgrade`)




## OpenAPI

````yaml /api-reference/openapi.yaml put /subscriptions/{id}
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}:
    put:
      tags:
        - Subscriptions
      summary: 更新訂閱
      description: |
        更新訂閱資料。

        ### 自動事件觸發
        根據 MRR 變化自動產生事件：
        - MRR 增加 → 升級事件 (`upgrade`)
        - MRR 減少 → 降級事件 (`downgrade`)
      operationId: updateSubscription
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
      responses:
        '200':
          description: 訂閱更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    UpdateSubscriptionRequest:
      type: object
      properties:
        plan_name:
          type: string
        mrr:
          type: string
        billing_cycle:
          type: string
          enum:
            - monthly
            - quarterly
            - semi-annual
            - yearly
        current_period_start:
          type: string
          format: date-time
    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 設定」頁面取得。

````