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

# 数量变更试算

> 按给定数量只读试算下期预计金额，供席位变更前展示；仅 active 且 billing_dimension=quantity 订阅支持，无副作用

按给定数量只读试算下期预计金额，供席位变更前展示；仅 active 且 billing\_dimension=quantity 订阅支持，无副作用


## OpenAPI

````yaml openapi/v1-zh.yaml GET /api/v1/subscription/{subscription_id}/quantity-preview
openapi: 3.0.3
info:
  title: Subotiz API
  description: Subotiz OpenAPI
  version: 1.0.0
servers:
  - url: https://{api}.subotiz.com
    variables:
      api:
        default: api
security:
  - sec0: []
tags:
  - name: 折扣
    description: 折扣
  - name: 发票
    description: 发票
  - name: 退款
    description: 退款
  - name: 商品管理
    description: 商品管理
  - name: 订阅
    description: 订阅
  - name: 商品定价
    description: 商品定价方案
  - name: 交易单
    description: 交易单
  - name: 支付流水
    description: 支付流水
  - name: 结账会话
    description: 结账会话
  - name: 顾客
    description: 顾客
  - name: 顾客门户
    description: 顾客门户
  - name: Webhook
    description: Webhook
  - name: 争议
    description: 争议订单
paths:
  /api/v1/subscription/{subscription_id}/quantity-preview:
    get:
      tags:
        - 订阅
      summary: 数量变更试算
      description: 按给定数量只读试算下期预计金额，供席位变更前展示；仅 active 且 billing_dimension=quantity 订阅支持，无副作用
      operationId: v1-subscription-preview-subscription-quantity
      parameters:
        - name: subscription_id
          in: path
          description: 订阅 ID（path）
          required: true
          schema:
            type: string
        - name: quantity
          in: query
          description: 试算目标数量（query，1-999999999）
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/HeaderRequestID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewSubscriptionQuantityResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                code: system_error
                message: Internal server error.
components:
  parameters:
    HeaderRequestID:
      name: Request-Id
      in: header
      description: 请求的唯一标识符
      required: true
      schema:
        type: string
        default: 008e3967-a1b5-48bb-be14-d5bff5092e61
  schemas:
    PreviewSubscriptionQuantityResponse:
      type: object
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
        data:
          $ref: '#/components/schemas/PreviewSubscriptionQuantityResponse_Data'
      description: 数量变更试算响应
    BaseResponse:
      type: object
      properties:
        code:
          type: string
          description: 错误码
        message:
          type: string
          description: 错误详细信息
    PreviewSubscriptionQuantityResponse_Data:
      type: object
      properties:
        quantity:
          type: string
          description: 试算数量（回显）
        cycle_index:
          type: integer
          description: 所属计费期（subscription.cycle_index + 1）
          format: int32
        effective_at:
          type: string
          description: 生效时点（当前周期末）
        next_amount:
          type: string
          description: 下期预计金额（按 quantity 经 solution-billing Calculate 试算，供展示，非即时扣款）
        breakdown:
          type: array
          items:
            $ref: '#/components/schemas/TierBreakdown'
          description: 金额分档明细（Calculate breakdown 透传）
      description: 数量变更试算响应
    TierBreakdown:
      type: object
      properties:
        tier_order:
          type: integer
          description: 档序，从 1 开始
          format: uint32
        quantity_min:
          type: string
          description: 该档下限
        quantity_max:
          type: string
          description: 该档上限；空表示 ∞
        units_in_tier:
          type: string
          description: 落入该档的数量/用量
        unit_price:
          type: string
          description: 该档单价
        flat_amount:
          type: string
          description: 该档固定费（与定价存储 flat_amount 同名）
        subtotal:
          type: string
          description: 该档小计
      description: |-
        试算分档明细（tier_breakdown[]，仅发票/结账 Calculate 结果透出，非定价配置）
         区间字段统一用 quantity_min/quantity_max（无独立落库表；用量维度由父级 billing_dimension 解释）
  securitySchemes:
    sec0:
      type: http
      description: 'Bearer API Key 鉴权。格式：Authorization: Bearer {your_api_key}'
      scheme: bearer

````