openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Product Variants
  description: |
    Nested management of product variants (size, plan tier, color, etc.).

    Available starting `v1.0.0-rc3`. See also: `products.yaml`.
  version: 1.0.0
servers:
- url: https://api.evoai.app
- url: http://localhost:3000
paths:
  /api/v1/products/{product_id}/variants:
    parameters:
    - { name: product_id, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      operationId: list-variants
      summary: List Variants
      description: Lists all variants of a product. Requires `products.read`.
      security: [{ userApiKey: [] }]
      responses:
        '200': { description: Variants retrieved successfully }
        '404': { description: Product not found }
    post:
      operationId: create-variant
      summary: Create Variant
      description: Creates a new variant under the product. Requires `products.update`.
      security: [{ userApiKey: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [variant]
              properties:
                variant:
                  type: object
                  required: [name]
                  properties:
                    name: { type: string, example: "Pro" }
                    sku: { type: string }
                    price_override: { type: number, format: float }
                    stock_quantity: { type: integer }
                    position: { type: integer }
                    attributes_data: { type: object, additionalProperties: true }
      responses:
        '201': { description: Variant created successfully }
        '422': { description: Validation error }
  /api/v1/products/{product_id}/variants/{id}:
    parameters:
    - { name: product_id, in: path, required: true, schema: { type: string, format: uuid } }
    - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    patch:
      operationId: update-variant
      summary: Update Variant
      description: Updates a variant. Requires `products.update`.
      security: [{ userApiKey: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                variant:
                  type: object
                  properties:
                    name: { type: string }
                    sku: { type: string }
                    price_override: { type: number, format: float }
                    stock_quantity: { type: integer }
                    position: { type: integer }
                    attributes_data: { type: object, additionalProperties: true }
      responses:
        '200': { description: Variant updated successfully }
        '422': { description: Validation error }
    delete:
      operationId: delete-variant
      summary: Delete Variant
      description: Deletes a variant. Returns 422 if the variant is referenced by pipeline items. Requires `products.delete`.
      security: [{ userApiKey: [] }]
      responses:
        '200': { description: Variant deleted successfully }
        '422': { description: Variant is in use and cannot be deleted }
components:
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token