CreatePriceRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/subotiz-com/json-schema/subotiz-com-create-price-request-schema.json",
  "title": "CreatePriceRequest",
  "description": "Create price request",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/subotiz-com-openapi.yml#/components/schemas/CreatePriceRequest",
  "required": [
    "name",
    "product_id",
    "product_version_id",
    "billing_type",
    "description",
    "price_type"
  ],
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Price name"
    },
    "product_id": {
      "type": "string",
      "description": "Associated product ID"
    },
    "product_version_id": {
      "type": "string",
      "description": "Product version ID"
    },
    "billing_type": {
      "type": "string",
      "description": "Billing type: one_time/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"
    },
    "trial_period": {
      "allOf": [
        {
          "$ref": "#/$defs/TrialPeriod"
        }
      ],
      "description": "Trial period configuration"
    },
    "price_plan": {
      "allOf": [
        {
          "$ref": "#/$defs/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 | based_on_usage"
    },
    "usage_amount": {
      "type": "string",
      "description": "Usage amount, required when `price_type` is based_on_usage or package_price"
    },
    "usage_unit": {
      "type": "string",
      "description": "Usage unit, required when `price_type` is based_on_usage or package_price"
    },
    "features": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CreatePriceFeature"
      },
      "description": "Price features"
    },
    "model_type": {
      "type": "string",
      "description": "Model type, one of the following: per_unit | tiers_price, required when `price_type` is based_on_usage"
    },
    "billing_threshold": {
      "type": "string",
      "description": "Billing threshold, required when `model_type` is per_unit"
    },
    "trial_type": {
      "type": "integer",
      "description": "Trial type, one of the following: 0 - Free trial | 1 - Paid trial",
      "format": "int32"
    },
    "trial_amount": {
      "type": "string",
      "description": "Trial amount, required when `trial_type` is 1 - Paid trial"
    },
    "status": {
      "type": "string",
      "description": "Status:\n - draft: Draft\n - active: Activated\n - frozen: Frozen"
    },
    "payment_timing": {
      "type": "string",
      "description": "Payment timing, one of: prepaid / postpaid. Defaults to prepaid.\n Mutually exclusive with the billing dimension this release: only (prepaid, quantity) and (postpaid, usage) are allowed; any other combination is rejected."
    },
    "billing_dimension": {
      "type": "string",
      "description": "Billing dimension, one of: quantity (by purchased quantity / seats) / usage (by consumption) / mixed (reserved, rejected this release). Defaults to quantity."
    },
    "usage_threshold": {
      "type": "string",
      "description": "Usage threshold (new semantics, replaces the amount-based billing_threshold). Set it on the postpaid usage route (billing_cycle_unit=over_threshold)."
    },
    "quantity_unit": {
      "type": "string",
      "description": "Quantity unit name (product-level, for display; defaults to \"unit\")"
    },
    "merchant_price_id": {
      "type": "string",
      "description": "Merchant-side price ID: merchant's own identifier for the price/SKU. Optional; unique per merchant; max length 100.\n Only allowed at creation time; updates/removals must be performed via Subotiz admin.\n Allowed charset: letters, digits, and _ - . : /; leading/trailing whitespace trimmed; inputs with spaces or other characters return 400."
    }
  },
  "$defs": {
    "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"
    },
    "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": "#/$defs/CreatePriceTier"
          },
          "description": "Tiered pricing details, specific prices for different cycles"
        },
        "price_usage_tiers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/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": "#/$defs/QuantityTier"
          },
          "description": "Quantity-side tier configuration. Required when price_type=tiers_price and billing_dimension=quantity."
        },
        "usage_tiers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/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"
    },
    "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"
    },
    "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"
    },
    "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"
    }
  }
}