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

# 列出訂閱



## OpenAPI

````yaml /api-reference/openapi.yaml get /subscriptions
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:
    get:
      tags:
        - Subscriptions
      summary: 列出訂閱
      operationId: listSubscriptions
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - active
              - cancelled
              - paused
          description: 篩選訂閱狀態
        - name: customer_id
          in: query
          schema:
            type: integer
          description: 篩選特定客戶的訂閱
      responses:
        '200':
          description: 訂閱列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1
      description: 頁碼
    per_page:
      name: per_page
      in: query
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
      description: 每頁筆數（最大 100）
  schemas:
    SubscriptionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    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
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        from:
          type: integer
        last_page:
          type: integer
        per_page:
          type: integer
        to:
          type: integer
        total:
          type: integer
  responses:
    Unauthorized:
      description: 未認證或 Token 無效
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthenticated.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum Token
      description: |
        使用 Laravel Sanctum Token 進行認證。

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

````