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

# 编辑定价

> 全量覆盖编辑定价方案，请求体与创建一致。编辑生效中定价会生成新版本并返回新版本 ID，已有订阅仍绑定旧版本不受影响；不支持修改状态、所属商品、币种。price_plan 中未暴露的计划名称、计划描述、有限期配置保留当前值。billing_dimension 留空时保留当前维度、付费时机与用量阈值；仅修改 billing_dimension 时付费时机按新维度推导。试用期单位支持 day / week / month；has_trial 置为 false 时 trial_type、trial_amount 重置，试用期单位与时长保留。

全量覆盖编辑定价方案，请求体与创建一致。编辑生效中定价会生成新版本并返回新版本 ID，已有订阅仍绑定旧版本不受影响；不支持修改状态、所属商品、币种。price\_plan 中未暴露的计划名称、计划描述、有限期配置保留当前值。billing\_dimension 留空时保留当前维度、付费时机与用量阈值；仅修改 billing\_dimension 时付费时机按新维度推导。试用期单位支持 day / week / month；has\_trial 置为 false 时 trial\_type、trial\_amount 重置，试用期单位与时长保留。


## OpenAPI

````yaml openapi/v1-zh.yaml POST /api/v1/prices/{price_id}
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/prices/{price_id}:
    post:
      tags:
        - 商品定价
      summary: 编辑定价
      description: >-
        全量覆盖编辑定价方案，请求体与创建一致。编辑生效中定价会生成新版本并返回新版本
        ID，已有订阅仍绑定旧版本不受影响；不支持修改状态、所属商品、币种。price_plan
        中未暴露的计划名称、计划描述、有限期配置保留当前值。billing_dimension 留空时保留当前维度、付费时机与用量阈值；仅修改
        billing_dimension 时付费时机按新维度推导。试用期单位支持 day / week / month；has_trial 置为
        false 时 trial_type、trial_amount 重置，试用期单位与时长保留。
      operationId: v1-price-update-price
      parameters:
        - name: price_id
          in: path
          description: 定价方案 ID
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/HeaderRequestID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePriceRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePriceResponse'
components:
  parameters:
    HeaderRequestID:
      name: Request-Id
      in: header
      description: 请求的唯一标识符
      required: true
      schema:
        type: string
        default: 008e3967-a1b5-48bb-be14-d5bff5092e61
  schemas:
    UpdatePriceRequest:
      required:
        - price_id
        - name
        - billing_type
        - description
        - price_type
      type: object
      properties:
        price_id:
          type: string
          description: 定价方案 ID
        name:
          type: string
          description: 定价方案名称
        billing_type:
          type: string
          description: 计费类型：one_time-一次性 / recurring-周期性
        price_val:
          type: string
          description: 一次性支付价格，当 billing_type 为 one_time 时必填
        description:
          type: string
          description: 定价描述
        has_trial:
          type: boolean
          description: >-
            是否启用试用期。置为 false 时 trial_type、trial_amount 重置为默认值，trial_period
            的单位与时长保留
        trial_period:
          allOf:
            - $ref: '#/components/schemas/TrialPeriod'
          description: >-
            试用期配置；has_trial 为 true 时必填。trial_period_unit 目前仅支持 day，不传按 day
            保存；has_trial 为 false 时可不传，原试用时长保留
        price_plan:
          allOf:
            - $ref: '#/components/schemas/CreatePricePlan'
          description: 定价计划，当 billing_type 为 recurring 时必填
        price_type:
          type: string
          description: 定价价格结构，取值之一：flat_price | package_price | tiers_price
        usage_amount:
          type: string
          description: 资源包用量（套餐含量），当 price_type 为 package_price 时必填
        usage_unit:
          type: string
          description: 用量单位，当 price_type 为 package_price 时必填
        features:
          type: array
          items:
            $ref: '#/components/schemas/CreatePriceFeature'
          description: 定价权益列表
        model_type:
          type: string
          description: 定价模型二级类型（已废弃）
        billing_threshold:
          type: string
          description: 扣费金额阈值（已废弃，改用 usage_threshold）
        trial_type:
          type: integer
          description: 试用类型：0-免费试用 | 1-付费试用
          format: int32
        trial_amount:
          type: string
          description: 试用价格，当 trial_type 为 1（付费试用）时必填
        payment_timing:
          type: string
          description: |-
            付费时机：prepaid / postpaid。
             billing_dimension 也留空时保留当前值；billing_dimension 显式传入而本字段留空时，按新维度推导（quantity→prepaid，usage→postpaid）
        billing_dimension:
          type: string
          description: 计费维度：quantity / usage；留空保留当前维度
        usage_threshold:
          type: string
          description: 用量阈值；留空时保留当前值（不支持通过本接口清空）
        once_trial:
          type: boolean
          description: 试用期是否限制每个客户仅可享受一次。不传保留当前值；仅在 has_trial 为 true 时生效
      description: |-
        编辑定价方案请求（全量覆盖：请求体与创建一致；币种取定价自身币种，不可修改；
         price_plan 中契约未暴露的计划名称、计划描述、有限期配置（is_infinite / billing_cycle_count）保留当前值）
    UpdatePriceResponse:
      type: object
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
        data:
          $ref: '#/components/schemas/UpdatePriceResponse_Data'
      description: 编辑定价方案响应
    TrialPeriod:
      type: object
      properties:
        trial_period_unit:
          type: string
          description: 试用期单位，必填，如：day、week、month等
        trial_period_count:
          type: integer
          description: 试用期数量，必填，如：7天、1个月等
          format: int32
      description: TrialPeriod - 试用期配置
    CreatePricePlan:
      type: object
      properties:
        base_price_val:
          type: string
          description: 基础价格，计划的基础定价
        billing_cycle_unit:
          type: string
          description: >-
            计费周期单位，取值之一：day、week、month、quarter、year、custom、customer-initiated、over_threshold（custom
            配合 billing_cycle_interval_unit/billing_cycle_interval 表达每 N 单位）
        price_tiers:
          type: array
          items:
            $ref: '#/components/schemas/CreatePriceTier'
          description: 阶梯定价明细，不同周期的具体价格
        price_usage_tiers:
          type: array
          items:
            $ref: '#/components/schemas/PriceUsageTier'
          description: 阶梯定价明细，不同用量区间的具体价格
        price_tier_type:
          type: string
          description: >-
            价格阶梯类型，取值之一：common | volume | grading；common 用于一口价与资源包，volume 与
            grading 用于按量计费（用量侧，billing_dimension=usage）
        usage_unit_price:
          type: string
          description: 用量单价
        quantity_tier_type:
          type: string
          description: >-
            购买量侧阶梯子型，取值之一：common | volume | grading；price_type=tiers_price 且
            billing_dimension=quantity 时必填
        quantity_tiers:
          type: array
          items:
            $ref: '#/components/schemas/QuantityTier'
          description: 购买量侧阶梯配置；price_type=tiers_price 且 billing_dimension=quantity 时必填
        usage_tiers:
          type: array
          items:
            $ref: '#/components/schemas/UsageTier'
          description: >-
            用量侧阶梯配置（含每档固定费 flat_amount）；price_type=tiers_price 且
            billing_dimension=usage 时必填，替代旧字段 price_usage_tiers
        billing_cycle_interval_unit:
          type: string
          description: REQ-7053008206 自定义周期时间单位：day/week/month/quarter/year；非 custom 时为空
        billing_cycle_interval:
          type: integer
          description: REQ-7053008206 间隔乘数 N：标准周期恒 1；custom 时 ∈[2,365]
          format: int32
      description: 创建定价时的定价计划
    CreatePriceFeature:
      type: object
      properties:
        product_feature_id:
          type: string
          description: 商品权益 ID
        value:
          type: string
          description: 权益数值，默认为 0
        display:
          type: boolean
          description: 是否在定价详情中展示该权益。不传默认为 true
      description: 创建定价权益
    UpdatePriceResponse_Data:
      type: object
      properties:
        price_id:
          type: string
          description: 定价方案 ID
        price_version_id:
          type: string
          description: 编辑后的定价当前版本 ID（生效中定价编辑会生成新版本）
      description: 编辑定价方案响应
    CreatePriceTier:
      type: object
      properties:
        billing_cycle_index:
          type: integer
          description: 计费周期索引，表示第几个周期
          format: int32
        price_val:
          type: string
          description: 价格值，该周期的具体价格
      description: 创建定价阶梯
    PriceUsageTier:
      type: object
      properties:
        usage_min:
          type: string
          description: 用量下限
        usage_max:
          type: string
          description: 用量上限
        current_tier_amount:
          type: string
          description: 当前阶梯金额
      description: 按用量阶梯定价明细（旧结构，存量只读兼容；新建按用量阶梯改用 UsageTier）
    QuantityTier:
      type: object
      properties:
        quantity_min:
          type: string
          description: 该档下限（闭区间起点）；对齐列 quantity_min
        quantity_max:
          type: string
          description: 该档上限（闭区间终点）；空表示 ∞（最后一档）；对齐列 quantity_max
        unit_price:
          type: string
          description: 该档单价
        flat_amount:
          type: string
          description: 该档固定费，默认 0（与定价存储 flat_amount 同名）
      description: >-
        按购买量/席位阶梯定价明细（quantity_tiers[]，price_type=tiers_price 且
        billing_dimension=quantity 时透出/必填）
         区间字段名对齐 MySQL pgs_price_quantity_tier.quantity_min/quantity_max
    UsageTier:
      type: object
      properties:
        usage_min:
          type: string
          description: 该档下限（闭区间起点）；对齐列 usage_min
        usage_max:
          type: string
          description: 该档上限（闭区间终点）；空表示 ∞（最后一档）；对齐列 usage_max
        unit_price:
          type: string
          description: 该档单价
        flat_amount:
          type: string
          description: 该档固定费，默认 0（与定价存储 flat_amount 同名）
      description: >-
        按用量阶梯定价明细（usage_tiers[]，price_type=tiers_price 且 billing_dimension=usage
        时透出/必填）
         区间字段名对齐 MySQL pgs_price_usage_tier.usage_min/usage_max
  securitySchemes:
    sec0:
      type: http
      description: 'Bearer API Key 鉴权。格式：Authorization: Bearer {your_api_key}'
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.