> ## 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 post /subscriptions/events
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/events:
    post:
      tags:
        - Subscription Events
      summary: 建立訂閱事件
      description: 手動記錄訂閱事件（升級、降級、取消等）。
      operationId: createSubscriptionEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionEventRequest'
            example:
              customer_email: customer@example.com
              event_type: upgrade
              old_amount: '500.00'
              new_amount: '990.00'
              amount_change: '490.00'
              old_plan: Basic
              new_plan: Pro
              occurred_at: '2026-01-09T00:00:00Z'
      responses:
        '201':
          description: 事件建立成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEventResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    CreateSubscriptionEventRequest:
      type: object
      required:
        - customer_email
        - event_type
        - amount_change
        - occurred_at
      properties:
        customer_email:
          type: string
          format: email
          description: 客戶 Email
        event_type:
          type: string
          enum:
            - created
            - upgrade
            - downgrade
            - cancel
            - reactivated
          description: 事件類型
        amount_change:
          type: string
          description: MRR 變化金額
          example: '490.00'
        occurred_at:
          type: string
          format: date-time
          description: 事件發生時間
        old_amount:
          type: string
          description: 變更前金額
        new_amount:
          type: string
          description: 變更後金額
        old_plan:
          type: string
          description: 變更前方案
        new_plan:
          type: string
          description: 變更後方案
        metadata:
          type: object
    SubscriptionEventResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SubscriptionEvent'
    SubscriptionEvent:
      type: object
      properties:
        id:
          type: integer
        customer_id:
          type: integer
        event_type:
          type: string
          enum:
            - created
            - upgrade
            - downgrade
            - cancel
            - reactivated
        source:
          type: string
          enum:
            - api
            - inferred
        old_amount:
          type: string
        new_amount:
          type: string
        amount_change:
          type: string
        old_plan:
          type: string
        new_plan:
          type: string
        occurred_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: 未認證或 Token 無效
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthenticated.
    ValidationError:
      description: 驗證錯誤
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: The given data was invalid.
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
          example:
            message: The given data was invalid.
            errors:
              email:
                - The email field is required.
                - The email must be a valid email address.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum Token
      description: |
        使用 Laravel Sanctum Token 進行認證。

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

````