openapi: 3.0.3
info:
  title: Omnivore Product API
  description: API for managing products in the Omnivore marketplace integration platform
  version: 2.0.0
  contact:
    name: Omnivore Support
    url: https://omnivore.com.au

servers:
  - url: https://m1.omnivore.com.au/v2
    description: Production cluster m1
  - url: https://m2.omnivore.com.au/v2
    description: Production cluster m2
  - url: https://test.omnivore.com.au/v2
    description: Testing environment

security:
  - clientCredentials: []

paths:
  /retailer/{retailer_code}/product/create:
    post:
      summary: Create Product
      description: Creates a new product for the specified retailer
      operationId: createProduct
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/RetailerCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Product created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          description: Not authorized due to either invalid authentication credentials or this client does not have access to the requested resource.
        '406':
          description: A valid product cannot be extracted from the data provided, generally because it's missing one of the required fields.
        '409':
          description: A product with this sku already exists.
        '500':
          description: Internal server error.

  /retailer/{retailer_code}/product/update:
    post:
      summary: Update Product
      description: Updates an existing product identified by SKU for the specified retailer
      operationId: updateProduct
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/RetailerCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Product updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          description: Not authorized due to either invalid authentication credentials or this client does not have access to the requested resource.
        '406':
          description: A valid product cannot be extracted from the data provided, generally because it's missing one of the required fields.
        '409':
          description: A product with this sku already exists.
        '500':
          description: Internal server error.

  /retailer/{retailer_code}/marketplace/{marketplace_code}/products/list:
    get:
      summary: List Marketplace Products
      description: |
        Returns a paginated list of products as they are configured for a specific
        marketplace (e.g. eBay, Amazon).
        
        Each product includes its **listing status**, any **error messages** preventing
        it from going live, and the full variant data with marketplace-specific fields
        such as `marketplace_sku` and `epid`.
        
        ## Filtering
        - Use `error=no_errors` to return only products with no listing issues.
        - Use `error=all_errors` to return products that have listing errors, thus are not listed on the marketplace.
        - Use `error=specific error` to return products that have that specific listing error, eg `error=unmapped+categories` to see all products that have not been mapped to marketplace categories
        - Use `last_updated_since` for incremental sync — returns only products
          changed since the given date-time.
      operationId: listMarketplaceProducts
      tags:
        - Marketplace Products
      parameters:
        - $ref: '#/components/parameters/RetailerCode'
        - $ref: '#/components/parameters/MarketplaceCode'
        - name: offset
          in: query
          description: Number of products to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: max
          in: query
          description: Maximum number of products to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: active
          in: query
          description: Filter by active status
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          description: Field to sort results by
          required: false
          schema:
            type: string
            enum:
              - sku
              - id
              - date_created
              - last_updated
            default: sku
        - name: order
          in: query
          description: Sort order direction
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - name: error
          in: query
          description: Filter products by error status. Use 'no_errors' to return only products with no listing errors.
          required: false
          schema:
            type: string
            enum:
              - no_errors
              - all_errors
              - actual error text
        - name: last_updated_since
          in: query
          description: Filter products last updated at or after this date-time (ISO 8601 format)
          required: false
          schema:
            type: string
            format: date-time
            example: "2026-01-02T03:04:05Z"
      responses:
        '200':
          description: List of marketplace products retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceProductListResponse'
        '401':
          description: Not authorized due to either invalid authentication credentials or this client does not have access to the requested resource.


  /retailer/{retailer_code}/products/bulkUpdate:
    post:
      summary: Bulk Update Products
      description: |
        Creates or updates up to 100 products in a single request.

        Each product is identified by its `sku`. If a product with the given SKU
        already exists it will be updated; otherwise a new product will be created.
        Products that are present in the system but absent from the payload are
        **not** deactivated — use `active: false` to explicitly deactivate a product.

        The maximum number of products accepted in one request is **100**.
      operationId: bulkUpdateProducts
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/RetailerCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkProductRequest'
      responses:
        '200':
          description: Bulk update completed. Check individual product results for per-item outcomes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkProductUpdateResponse'
        '401':
          description: Not authorized due to either invalid authentication credentials or this client does not have access to the requested resource.

  /retailer/{retailer_code}/inventory/bulkUpdate:
    post:
      summary: Bulk Update Inventory
      description: |
        Updates prices and/or quantities for up to 100 products in a single request.

        This is a lightweight alternative to the full bulk product update — only
        `sell_price`, `rrp_price`, and `quantity` can be changed. Fields that are
        omitted from a variant are left unchanged, so the client can update just
        prices, just quantities, or both in the same call.

        The maximum number of products accepted in one request is **100**.
      operationId: bulkUpdateInventory
      tags:
        - Inventory
      parameters:
        - $ref: '#/components/parameters/RetailerCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkInventoryRequest'
      responses:
        '200':
          description: Bulk inventory update completed. Check individual product results for per-item outcomes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInventoryUpdateResponse'
        '401':
          description: Not authorized due to either invalid authentication credentials or this client does not have access to the requested resource.

  /retailer/{retailer_code}/inventory/list:
    get:
      summary: List Inventory
      description: |
        Returns a paginated list of products containing only pricing and quantity
        data — a lightweight alternative to the full product list.

        Useful for reconciling stock levels and prices without transferring the
        full product payload.
      operationId: listInventory
      tags:
        - Inventory
      parameters:
        - $ref: '#/components/parameters/RetailerCode'
        - name: offset
          in: query
          description: Number of products to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: max
          in: query
          description: Maximum number of products to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: active
          in: query
          description: Filter by active status
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          description: Field to sort results by
          required: false
          schema:
            type: string
            enum:
              - sku
              - id
            default: sku
        - name: order
          in: query
          description: Sort order direction
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
      responses:
        '200':
          description: Inventory list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryListResponse'
        '401':
          description: Not authorized due to either invalid authentication credentials or this client does not have access to the requested resource.

  /retailer/{retailer_code}/products/list:
    get:
      summary: List Products
      description: Retrieves a paginated list of products for the specified retailer
      operationId: listProducts
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/RetailerCode'
        - name: offset
          in: query
          description: Number of products to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: max
          in: query
          description: Maximum number of products to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: active
          in: query
          description: Filter by active status
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          description: Field to sort results by
          required: false
          schema:
            type: string
            enum:
              - sku
              - name
              - id
            default: sku
        - name: order
          in: query
          description: Sort order direction
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
      responses:
        '200':
          description: List of products retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
        '401':
          description: Not authorized due to either invalid authentication credentials or this client does not have access to the requested resource.

components:
  securitySchemes:
    clientCredentials:
      type: apiKey
      in: header
      name: X-OMNIVORE-CLIENT-ID
      description: Client ID for API authentication (must be used together with X-OMNIVORE-CLIENT-SECRET)
    clientSecret:
      type: apiKey
      in: header
      name: X-OMNIVORE-CLIENT-SECRET
      description: Client secret for API authentication

  parameters:
    RetailerCode:
      name: retailer_code
      in: path
      description: Unique identifier code for the retailer
      required: true
      schema:
        type: string
        maxLength: 255

    MarketplaceCode:
      name: marketplace_code
      in: path
      description: Unique identifier code for the marketplace (e.g., 'ebay' for eBay Australia, 'amazonau' for Amazon AU)
      required: true
      schema:
        type: string
        maxLength: 255
        enum:
          - ebay
          - amazonau
          - trademe

  schemas:
    Product:
      type: object
      description: Product data for create, update, and response operations
      required:
        - sku
        - name
        - description
        - active
        - images
        - variants
      properties:
        id:
          type: integer
          description: Internal product identifier
          readOnly: true
          example: 123
        sku:
          type: string
          description: Stock Keeping Unit - unique product identifier. Must be unique across all your products.
          maxLength: 255
          example: "TEST1"
        name:
          type: string
          description: Product display name
          maxLength: 255
          example: "Test 1 Minimal Product"
        url:
          type: string
          description: URL to the product page on the retailer's website
          maxLength: 2000
          format: uri
          nullable: true
          example: "https://example.com/products/test-product"
        short_description:
          type: string
          description: Brief product description for listings and summaries
          maxLength: 4000
          example: "A brief description of the product"
        description:
          type: string
          description: Full product description
          example: "A product with the minimum necessary amount of data"
        brand:
          type: string
          description: Product brand name (defaults to retailer name if not provided)
          maxLength: 255
          example: "Polaroid"
        active:
          type: boolean
          description: Whether the product is active and available for sale
          example: true
        condition:
          type: string
          description: Product condition
          maxLength: 255
          enum:
            - new
            - used
            - refurbished
          default: new
          example: "new"
        images:
          type: array
          description: List of product image URLs
          minItems: 1
          items:
            type: string
            format: uri
            maxLength: 2000
          example:
            - "https://example.com/image1.jpg"
        attributes:
          type: array
          description: Custom product attributes as name-value pairs
          items:
            $ref: '#/components/schemas/NameValue'
        categories:
          type: array
          description: Product categories
          items:
            $ref: '#/components/schemas/Category'
        variants:
          type: array
          description: Product variants (SKUs with pricing and inventory)
          minItems: 1
          items:
            $ref: '#/components/schemas/Variant'

    Variant:
      type: object
      description: Product variant with pricing and inventory
      required:
        - sku
        - sell_price
        - quantity
      properties:
        id:
          type: integer
          description: Internal variant identifier
          readOnly: true
          example: 6769
        sku:
          type: string
          description: Variant Stock Keeping Unit - unique variant identifier. Must be unique across this product's variants.
          maxLength: 255
          example: "RED"
        upc:
          type: string
          description: Universal Product Code (12-digit barcode)
          maxLength: 255
          nullable: true
          example: "123456789012"
        ean:
          type: string
          description: European Article Number (13-digit barcode)
          maxLength: 255
          nullable: true
          example: "0123456789012"
        isbn:
          type: string
          description: International Standard Book Number
          maxLength: 255
          nullable: true
          example: "978-3-16-148410-0"
        mpn:
          type: string
          description: Manufacturer Part Number
          maxLength: 255
          nullable: true
          example: "test2-red"
        sell_price:
          $ref: '#/components/schemas/Price'
        rrp_price:
          $ref: '#/components/schemas/Price'
        quantity:
          type: integer
          description: Available inventory quantity
          minimum: 0
          example: 17
        options:
          type: array
          description: Variant options (e.g., size, color)
          items:
            $ref: '#/components/schemas/NameValue'
        weight:
          type: string
          description: Product weight in kilograms. Do not include units.
          maxLength: 255
          nullable: true
          example: "0.5"
        width:
          type: string
          description: Product width (include units in value)
          maxLength: 255
          nullable: true
          example: "20 cm"
        length:
          type: string
          description: Product length (include units in value)
          maxLength: 255
          nullable: true
          example: "10 cm"
        height:
          type: string
          description: Product height (include units in value)
          maxLength: 255
          nullable: true
          example: "30 cm"
        shipping_options:
          type: array
          description: Available shipping methods for this variant
          items:
            type: string
            maxLength: 255
          example:
            - "express"
            - "standard"
        images:
          type: array
          description: Variant-specific image URLs
          items:
            type: string
            format: uri
            maxLength: 2000
          example:
            - "https://example.com/variant-image.jpg"

    Price:
      type: object
      description: Price information with tax details
      required:
        - with_tax
        - tax
        - currency
      properties:
        with_tax:
          type: string
          description: Price including tax
          example: "22.00"
        without_tax:
          type: string
          description: Price excluding tax (calculated automatically)
          readOnly: true
          example: "20.00"
        tax:
          type: string
          description: Tax amount
          example: "2.00"
        currency:
          type: string
          description: ISO 4217 currency code
          minLength: 3
          maxLength: 3
          example: "AUD"

    NameValue:
      type: object
      description: Generic name-value pair used for attributes and variant options
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: Attribute or option name
          maxLength: 255
        value:
          type: string
          description: Attribute or option value
          maxLength: 255

    Category:
      type: object
      description: Product category
      required:
        - code
        - name
      properties:
        code:
          type: string
          description: Unique category code
          maxLength: 255
          example: "nature"
        name:
          type: string
          description: Category display name
          maxLength: 255
          example: "Nature"
        path:
          type: string
          description: Full category path (e.g., "Parent > Child > Grandchild")
          maxLength: 255
          nullable: true
          example: "Home > Nature"
        parent_code:
          type: string
          description: Parent category code for hierarchical categories
          maxLength: 255
          nullable: true
          example: "home"

    ProductListResponse:
      type: object
      description: Paginated list of products
      properties:
        retailer:
          $ref: '#/components/schemas/Retailer'
        total_count:
          type: integer
          description: Total number of products matching the filter criteria
          minimum: 0
          example: 150
        current_count:
          type: integer
          description: Number of products in the current response
          minimum: 0
          example: 100
        filter:
          type: object
          description: Applied filter criteria
          properties:
            active:
              type: string
              description: Active filter value as string
              example: "true"
        sort:
          type: string
          description: Field used for sorting
          example: "sku"
        order:
          type: string
          description: Sort order direction
          enum:
            - asc
            - desc
          example: "asc"
        offset:
          type: integer
          description: Number of products skipped (pagination offset)
          minimum: 0
          example: 0
        max:
          type: integer
          description: Maximum products per page
          minimum: 1
          example: 100
        products:
          type: array
          description: List of products
          items:
            $ref: '#/components/schemas/Product'

    Retailer:
      type: object
      description: Retailer information
      properties:
        code:
          type: string
          description: Unique retailer code
          maxLength: 255
          example: "test-store"
        name:
          type: string
          description: Retailer display name
          maxLength: 255
          example: "Test Store"
        currency:
          type: string
          description: Default currency for the retailer (ISO 4217)
          minLength: 3
          maxLength: 3
          example: "AUD"

    Error:
      type: object
      description: Error response
      properties:
        error:
          type: string
          description: Error code
          example: "invalid_request"
        message:
          type: string
          description: Human-readable error message
          example: "The 'sku' field is required"
        details:
          type: object
          description: Additional error details
          additionalProperties: true

    Marketplace:
      type: object
      description: Marketplace information
      properties:
        code:
          type: string
          description: Unique marketplace code
          maxLength: 255
          example: "ebay"
        name:
          type: string
          description: Marketplace display name
          maxLength: 255
          example: "eBay Australia"
        currency:
          type: string
          description: Default currency for the marketplace (ISO 4217)
          minLength: 3
          maxLength: 3
          example: "AUD"
        integration_status:
          type: string
          description: Current status of the marketplace integration
          maxLength: 255
          example: "active"

    MarketplaceProductListResponse:
      type: object
      description: Paginated list of products listed on a marketplace
      properties:
        retailer:
          $ref: '#/components/schemas/Retailer'
        marketplace:
          $ref: '#/components/schemas/Marketplace'
        total_count:
          type: integer
          description: Total number of products matching the filter criteria
          minimum: 0
          example: 2
        current_count:
          type: integer
          description: Number of products in the current response
          minimum: 0
          example: 2
        sort:
          type: string
          description: Field used for sorting
          example: "sku"
        order:
          type: string
          description: Sort order direction
          enum:
            - asc
            - desc
          example: "asc"
        offset:
          type: integer
          description: Number of products skipped (pagination offset)
          minimum: 0
          example: 0
        max:
          type: integer
          description: Maximum products per page
          minimum: 1
          example: 100
        products:
          type: array
          description: List of marketplace products
          items:
            $ref: '#/components/schemas/MarketplaceProduct'

    MarketplaceProduct:
      type: object
      description: Product as listed on a marketplace
      properties:
        marketplace_code:
          type: string
          description: Code of the marketplace this product is listed on
          maxLength: 255
          example: "ebay"
        id:
          type: integer
          description: Internal marketplace product identifier
          example: 1853
        sku:
          type: string
          description: Product SKU
          maxLength: 255
          example: "TEST1"
        date_created:
          type: string
          format: date-time
          description: Date and time the marketplace product was created
          example: "2026-02-25T21:18:20+11:00"
        last_updated:
          type: string
          format: date-time
          description: Date and time the marketplace product was last updated
          example: "2026-02-25T21:18:21+11:00"
        url:
          type: string
          format: uri
          description: URL to the product listing on the marketplace
          maxLength: 2000
          nullable: true
        listing_id:
          type: string
          description: Marketplace-assigned listing identifier
          maxLength: 255
          nullable: true
        name:
          type: string
          description: Product display name
          maxLength: 255
          example: "Test 1 Minimal Product"
        description:
          type: string
          description: Full product description
          example: "A product with the minimum necessary amount of data"
        brand:
          type: string
          description: Product brand name
          maxLength: 255
          example: "Test Store"
        active:
          type: boolean
          description: Whether the product is active on the marketplace
          example: true
        error:
          type: string
          description: Listing error message, if the product has a marketplace issue
          nullable: true
          example: "shipping options missing"
        condition:
          type: string
          description: Marketplace-specific condition code
          maxLength: 255
          example: "1000"
        images:
          type: array
          description: List of product image URLs
          items:
            type: string
            format: uri
            maxLength: 2000
          example:
            - "https://example.com/image1.jpg"
        categories:
          type: array
          description: Product categories
          items:
            $ref: '#/components/schemas/Category'
        variants:
          type: array
          description: Marketplace product variants
          items:
            $ref: '#/components/schemas/MarketplaceVariant'

    MarketplaceVariant:
      type: object
      description: Product variant as listed on a marketplace
      properties:
        id:
          type: integer
          description: Internal marketplace variant identifier
          example: 8431
        marketplace_sku:
          type: string
          description: Variant SKU on the marketplace
          maxLength: 255
          example: "TEST1"
        active:
          type: boolean
          description: Whether the variant is active on the marketplace
          example: true
        upc:
          type: string
          description: Universal Product Code (12-digit barcode)
          maxLength: 255
          nullable: true
          example: "123456789012"
        ean:
          type: string
          description: European Article Number (13-digit barcode)
          maxLength: 255
          nullable: true
          example: "0123456789013"
        isbn:
          type: string
          description: International Standard Book Number
          maxLength: 255
          nullable: true
        mpn:
          type: string
          description: Manufacturer Part Number
          maxLength: 255
          nullable: true
          example: "test2-red"
        sell_price:
          $ref: '#/components/schemas/Price'
        rrp_price:
          $ref: '#/components/schemas/Price'
        quantity:
          type: integer
          description: Available inventory quantity
          minimum: 0
          example: 1
        options:
          type: array
          description: Variant options (e.g., colour, size)
          items:
            $ref: '#/components/schemas/NameValue'
        weight:
          type: string
          description: Product weight in kilograms. Do not include units.
          maxLength: 255
          nullable: true
          example: "0.5"
        length:
          type: string
          description: Product length (include units in value)
          maxLength: 255
          nullable: true
          example: "10 cm"
        height:
          type: string
          description: Product height (include units in value)
          maxLength: 255
          nullable: true
          example: "30 cm"
        width:
          type: string
          description: Product width (include units in value)
          maxLength: 255
          nullable: true
          example: "20 cm"
        shipping_method:
          type: string
          description: Shipping method configured for this variant on the marketplace
          maxLength: 255
          nullable: true
          example: "basic"
        epid:
          type: string
          description: eBay Product Identifier (ePID), used for eBay listings
          maxLength: 255
          nullable: true
        images:
          type: array
          description: Variant-specific image URLs
          items:
            type: string
            format: uri
            maxLength: 2000
          example:
            - "https://example.com/variant-image.jpg"

    BulkProductRequest:
      type: object
      description: Request body for the bulk product update endpoint
      required:
        - products
      properties:
        products:
          type: array
          description: List of products to create or update. Maximum 100 items.
          maxItems: 100
          minItems: 1
          items:
            $ref: '#/components/schemas/Product'

    BulkProductResult:
      type: object
      description: Per-product outcome from a bulk update operation
      properties:
        id:
          type: integer
          description: Internal product identifier
          example: 1224
        sku:
          type: string
          description: Product SKU
          maxLength: 255
          example: "TEST1"
        result:
          type: string
          description: |
            Outcome for this product. Possible values include `created`, `updated`,
            `deactivated`, `no change`, and `error`.
          maxLength: 255
          example: "updated"

    BulkProductUpdateResponse:
      type: object
      description: Response from the bulk product update endpoint
      properties:
        retailer:
          $ref: '#/components/schemas/Retailer'
        total_count:
          type: integer
          description: Total number of products submitted in the request
          minimum: 0
          example: 2
        products_created:
          type: integer
          description: Number of products that were newly created
          minimum: 0
          example: 0
        products_updated:
          type: integer
          description: Number of products that were updated
          minimum: 0
          example: 2
        products_deactivated:
          type: integer
          description: Number of products that were deactivated
          minimum: 0
          example: 0
        errors:
          type: integer
          description: Number of products that could not be processed due to errors
          minimum: 0
          example: 0
        products:
          type: array
          description: Per-product results
          items:
            $ref: '#/components/schemas/BulkProductResult'

    InventoryVariant:
      type: object
      description: |
        Variant data containing only pricing and quantity fields.
        Used for both the bulk inventory update request and the inventory list response.
      properties:
        id:
          type: integer
          description: Internal variant identifier
          readOnly: true
          example: 6769
        sku:
          type: string
          description: Variant Stock Keeping Unit
          maxLength: 255
          example: "RED"
        sell_price:
          $ref: '#/components/schemas/Price'
        rrp_price:
          $ref: '#/components/schemas/Price'
        quantity:
          type: integer
          description: Available inventory quantity
          minimum: 0
          example: 17

    InventoryProduct:
      type: object
      description: |
        Product data containing only pricing and quantity fields.
        Used for both the bulk inventory update request and the inventory list response.
      properties:
        id:
          type: integer
          description: Internal product identifier
          readOnly: true
          example: 1224
        sku:
          type: string
          description: Product SKU
          maxLength: 255
          example: "TEST1"
        variants:
          type: array
          description: Variant pricing and inventory data
          items:
            $ref: '#/components/schemas/InventoryVariant'

    BulkInventoryRequest:
      type: object
      description: Request body for the bulk inventory update endpoint
      required:
        - products
      properties:
        products:
          type: array
          description: |
            List of products with variant pricing and/or quantity to update.
            Maximum 100 items. Omitted fields within a variant are left unchanged.
          maxItems: 100
          minItems: 1
          items:
            $ref: '#/components/schemas/InventoryProduct'

    BulkInventoryUpdateResponse:
      type: object
      description: Response from the bulk inventory update endpoint
      properties:
        retailer:
          $ref: '#/components/schemas/Retailer'
        total_count:
          type: integer
          description: Total number of products submitted in the request
          minimum: 0
          example: 2
        products_updated:
          type: integer
          description: Number of products whose inventory was changed
          minimum: 0
          example: 0
        products_not_changed:
          type: integer
          description: Number of products where the submitted values matched existing data (no update needed)
          minimum: 0
          example: 2
        errors:
          type: integer
          description: Number of products that could not be processed due to errors
          minimum: 0
          example: 0
        products:
          type: array
          description: Per-product results
          items:
            $ref: '#/components/schemas/BulkProductResult'

    InventoryListResponse:
      type: object
      description: Paginated list of products with pricing and quantity data only
      properties:
        retailer:
          $ref: '#/components/schemas/Retailer'
        total_count:
          type: integer
          description: Total number of products matching the filter criteria
          minimum: 0
          example: 2
        current_count:
          type: integer
          description: Number of products in the current response
          minimum: 0
          example: 2
        filter:
          type: object
          description: Applied filter criteria
          properties:
            active:
              type: string
              description: Active filter value as string
              example: "true"
        sort:
          type: string
          description: Field used for sorting
          example: "sku"
        order:
          type: string
          description: Sort order direction
          enum:
            - asc
            - desc
          example: "asc"
        offset:
          type: integer
          description: Number of products skipped (pagination offset)
          minimum: 0
          example: 0
        max:
          type: integer
          description: Maximum products per page
          minimum: 1
          example: 100
        products:
          type: array
          description: List of products with inventory data
          items:
            $ref: '#/components/schemas/InventoryProduct'