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

# Update Price

> Fully overwrites the price; the request body is the same as creation. Updating an active price creates a new version and returns the new version ID; existing subscriptions stay bound to the old version and are not affected. Changing status, product, or currency is not supported. Plan name, plan description, and finite-term settings not exposed in price_plan keep their current values. When billing_dimension is empty, the current dimension, payment timing, and usage threshold are kept; when only billing_dimension is changed, payment timing is derived from the new dimension. Trial period units support day / week / month; when has_trial is set to false, trial_type and trial_amount are reset while the trial period unit and length are kept.

Fully overwrites the price; the request body is the same as creation. Updating an active price creates a new version and returns the new version ID; existing subscriptions stay bound to the old version and are not affected. Changing status, product, or currency is not supported. Plan name, plan description, and finite-term settings not exposed in price\_plan keep their current values. When billing\_dimension is empty, the current dimension, payment timing, and usage threshold are kept; when only billing\_dimension is changed, payment timing is derived from the new dimension. Trial period units support day / week / month; when has\_trial is set to false, trial\_type and trial\_amount are reset while the trial period unit and length are kept.


## OpenAPI

````yaml openapi/v1-en.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: Subscription
    description: 订阅
  - name: Price
    description: 商品定价方案
  - name: Trade
    description: 交易单
  - name: Payment
    description: 支付流水
  - name: Checkout Session
    description: 结账会话
  - name: Customer
    description: 顾客
  - name: Customer Portal
    description: 顾客门户
paths:
  /api/v1/prices/{price_id}:
    post:
      tags:
        - Price
      summary: Update Price
      description: >-
        Fully overwrites the price; the request body is the same as creation.
        Updating an active price creates a new version and returns the new
        version ID; existing subscriptions stay bound to the old version and are
        not affected. Changing status, product, or currency is not supported.
        Plan name, plan description, and finite-term settings not exposed in
        price_plan keep their current values. When billing_dimension is empty,
        the current dimension, payment timing, and usage threshold are kept;
        when only billing_dimension is changed, payment timing is derived from
        the new dimension. Trial period units support day / week / month; when
        has_trial is set to false, trial_type and trial_amount are reset while
        the trial period unit and length are kept.
      operationId: v1-price-update-price
      parameters:
        - name: price_id
          in: path
          description: Price 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: The unique identifier of the request
      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: Price ID
        name:
          type: string
          description: Price name
        billing_type:
          type: string
          description: 'Billing type: one_time - one-off / recurring - recurring'
        price_val:
          type: string
          description: One-time payment price, required when `billing_type` is one_time
        description:
          type: string
          description: Price description
        has_trial:
          type: boolean
          description: >-
            Whether trial period is enabled. When set to false, trial_type and
            trial_amount are reset to defaults; the unit and length of
            trial_period are kept
        trial_period:
          allOf:
            - $ref: '#/components/schemas/TrialPeriod'
          description: >-
            Trial period configuration; required when has_trial is true.
            trial_period_unit currently only supports day and defaults to day
            when omitted; may be omitted when has_trial is false, in which case
            the existing trial length is kept
        price_plan:
          allOf:
            - $ref: '#/components/schemas/CreatePricePlan'
          description: Price plan, required when `billing_type` is recurring
        price_type:
          type: string
          description: >-
            Price type, one of the following: flat_price | package_price |
            tiers_price
        usage_amount:
          type: string
          description: >-
            Package usage amount (included quantity), required when `price_type`
            is package_price
        usage_unit:
          type: string
          description: Usage unit, required when `price_type` is package_price
        features:
          type: array
          items:
            $ref: '#/components/schemas/CreatePriceFeature'
          description: Price features
        model_type:
          type: string
          description: Secondary price model type (deprecated)
        billing_threshold:
          type: string
          description: Billing amount threshold (deprecated, use usage_threshold instead)
        trial_type:
          type: integer
          description: 'Trial type: 0 - Free trial | 1 - Paid trial'
          format: int32
        trial_amount:
          type: string
          description: Trial amount, required when `trial_type` is 1 - Paid trial
        payment_timing:
          type: string
          description: |-
            Payment timing: prepaid / postpaid.
             When billing_dimension is also empty, the current value is kept; when billing_dimension is explicitly provided and this field is empty, it is derived from the new dimension (quantity→prepaid, usage→postpaid)
        billing_dimension:
          type: string
          description: >-
            Billing dimension: quantity / usage; empty keeps the current
            dimension
        usage_threshold:
          type: string
          description: >-
            Usage threshold; empty keeps the current value (clearing it via this
            API is not supported)
        once_trial:
          type: boolean
          description: >-
            Whether each customer can use the trial period only once. Omitted
            keeps the current value; only takes effect when has_trial is true
      description: >-
        Update price request (full overwrite: the request body is the same as
        creation; the currency is taken from the price itself and cannot be
        changed;
         plan name, plan description and finite-term settings (is_infinite / billing_cycle_count) in price_plan that are not exposed by the contract keep their current values)
    UpdatePriceResponse:
      type: object
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
        data:
          $ref: '#/components/schemas/UpdatePriceResponse_Data'
      description: Update price response
    TrialPeriod:
      type: object
      properties:
        trial_period_unit:
          type: string
          description: 'Trial period unit, required, such as: day, week, month, etc.'
        trial_period_count:
          type: integer
          description: 'Trial period count, required, such as: 7 days, 1 month, etc.'
          format: int32
      description: TrialPeriod - Trial period configuration
    CreatePricePlan:
      type: object
      properties:
        base_price_val:
          type: string
          description: Base price, base pricing of the plan
        billing_cycle_unit:
          type: string
          description: >-
            Billing cycle unit, one of the following: week, month, quarter,
            year, customer-initiated, over_threshold.
        price_tiers:
          type: array
          items:
            $ref: '#/components/schemas/CreatePriceTier'
          description: Tiered pricing details, specific prices for different cycles
        price_usage_tiers:
          type: array
          items:
            $ref: '#/components/schemas/PriceUsageTier'
          description: Tiered pricing details, specific prices for different usage amounts
        price_tier_type:
          type: string
          description: >-
            price tier type, one of the following: common | volume | grading,
            common for flat price and package price, volume and grading for
            based_on_usage price
        usage_unit_price:
          type: string
          description: usage unit price
        quantity_tier_type:
          type: string
          description: >-
            Quantity-side tier subtype, one of: common | volume | grading.
            Required when price_type=tiers_price and billing_dimension=quantity.
        quantity_tiers:
          type: array
          items:
            $ref: '#/components/schemas/QuantityTier'
          description: >-
            Quantity-side tier configuration. Required when
            price_type=tiers_price and billing_dimension=quantity.
        usage_tiers:
          type: array
          items:
            $ref: '#/components/schemas/UsageTier'
          description: >-
            Usage-side tier configuration (includes per-tier flat_amount).
            Required when price_type=tiers_price and billing_dimension=usage;
            replaces the legacy price_usage_tiers field.
        billing_cycle_interval_unit:
          type: string
          description: >-
            REQ-7053008206 Custom cycle time unit: day/week/month/quarter/year;
            empty when not custom
        billing_cycle_interval:
          type: integer
          description: >-
            REQ-7053008206 Interval multiplier N: always 1 for standard cycles;
            within [2,365] when custom
          format: int32
      description: Pricing plan for create price
    CreatePriceFeature:
      type: object
      properties:
        product_feature_id:
          type: string
          description: Product feature ID
        value:
          type: string
          description: Feature value, default value is 0
        display:
          type: boolean
          description: >-
            Whether to display this feature on the price detail page. Defaults
            to true when omitted
      description: Create price feature
    UpdatePriceResponse_Data:
      type: object
      properties:
        price_id:
          type: string
          description: Price ID
        price_version_id:
          type: string
          description: >-
            Current price version ID after the update (updating an active price
            creates a new version)
      description: Update price response
    CreatePriceTier:
      type: object
      properties:
        billing_cycle_index:
          type: integer
          description: Billing cycle index, indicating which cycle
          format: int32
        price_val:
          type: string
          description: Price value, specific price for this cycle
      description: Create price tier
    PriceUsageTier:
      type: object
      properties:
        usage_min:
          type: string
          description: Usage minimum
        usage_max:
          type: string
          description: Usage maximum
        current_tier_amount:
          type: string
          description: Current tier amount
      description: Tiered pricing details for usage
    QuantityTier:
      type: object
      properties:
        quantity_min:
          type: string
          description: >-
            Lower bound of this tier (inclusive); maps to the quantity_min
            column
        quantity_max:
          type: string
          description: >-
            Upper bound of this tier (inclusive); empty means unlimited (last
            tier); maps to the quantity_max column
        unit_price:
          type: string
          description: Unit price for this tier
        flat_amount:
          type: string
          description: >-
            Flat fee for this tier, defaults to 0 (same name as the flat_amount
            column in pricing storage)
      description: Pricing tier for the quantity (seat) dimension
    UsageTier:
      type: object
      properties:
        usage_min:
          type: string
          description: Lower bound of this tier (inclusive); maps to the usage_min column
        usage_max:
          type: string
          description: >-
            Upper bound of this tier (inclusive); empty means unlimited (last
            tier); maps to the usage_max column
        unit_price:
          type: string
          description: Unit price for this tier
        flat_amount:
          type: string
          description: >-
            Flat fee for this tier, defaults to 0 (same name as the flat_amount
            column in pricing storage)
      description: Pricing tier for the usage dimension
  securitySchemes:
    sec0:
      type: http
      description: >-
        Bearer API Key authentication. Format: Authorization: Bearer
        {your_api_key}
      scheme: bearer

````

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