> ## Documentation Index
> Fetch the complete documentation index at: https://developers.unbridaled.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Watch Variants

> Query the watch marketplace using filters, free-text search, and pagination.

`filter_variant_options` accepts any watch attribute key (e.g. `brand`,
`model`, `style`, `case_material`, `dial_color`) — see
`/api/v3/product_filters?product_type=watch` for the current set of
supported keys and their allowed values.

The `vendor_id` filter is reserved for internal admin use and is
rejected for merchant/API-key callers.



## OpenAPI

````yaml post /api/v3/product_variants/watches/query
openapi: 3.1.0
info:
  title: Unbridaled Marketplace Merchant API v3
  description: Developer API to integrate with Unbridaled Marketplace (v3)
  version: 3.0.0
servers:
  - url: https://api-staging.unbridaled.ai
    description: Sandbox API
  - description: Production API
    url: https://api.unbridaled.ai
security:
  - apikeyAuth: []
tags:
  - name: Diamonds
  - name: Inventory
  - name: Orders
  - name: Product Variants
  - name: Products
  - name: Merchant Templates
  - name: Merchant Addresses
  - name: Profit Margins
  - name: Defaults
paths:
  /api/v3/product_variants/watches/query:
    post:
      tags:
        - Product Variants
      summary: Query Watch Variants
      description: >-
        Query the watch marketplace using filters, free-text search, and
        pagination.


        `filter_variant_options` accepts any watch attribute key (e.g. `brand`,

        `model`, `style`, `case_material`, `dial_color`) — see

        `/api/v3/product_filters?product_type=watch` for the current set of

        supported keys and their allowed values.


        The `vendor_id` filter is reserved for internal admin use and is

        rejected for merchant/API-key callers.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  type: string
                  description: >-
                    Search query to filter by SKU, vendor SKU, product
                    title/description, brand, model, or reference number.
                filter_variant_options:
                  type: object
                  description: >-
                    Watch attribute filters, e.g. {"brand": "Rolex"}. See
                    /api/v3/product_filters?product_type=watch for supported
                    keys/values.
                product_id:
                  type: array
                  items:
                    type: string
                  description: Product ID(s) to filter by.
                id:
                  type: array
                  items:
                    type: string
                  description: Variant ID(s) to filter by.
                has_media:
                  type: boolean
                returnable:
                  type: boolean
                wholesale_price_min:
                  type: number
                wholesale_price_max:
                  type: number
                retail_price_min:
                  type: number
                retail_price_max:
                  type: number
                include_unavailable:
                  type: boolean
                  default: false
                  description: >-
                    Include sold/out-of-stock variants. Always true when `id` is
                    provided.
                currency_code:
                  type: string
                  default: USD
                  description: Currency code for price conversion (e.g. USD, EUR, GBP).
                offset:
                  type: integer
                  default: 0
                limit:
                  type: integer
                  default: 50
                order_by:
                  type: string
                  default: created_on
                order:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: desc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  variants:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        sku:
                          type: string
                        product_type:
                          type: string
                        wholesale_price:
                          type: number
                        retail_price:
                          type: number
                        quantity:
                          type: number
                        variant_options:
                          type: object
                        filter_variant_options:
                          type: object
                  offset:
                    type: integer
                  limit:
                    type: integer
                  total:
                    type: integer
components:
  securitySchemes:
    apikeyAuth:
      type: http
      scheme: bearer

````