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

# List Products Post Endpoint



## OpenAPI

````yaml /api-reference/openapi/foundation-portal.json post /api/v1/merchants/{merchant_id}/products
openapi: 3.1.0
info:
  title: Depict Foundation Portal API
  version: 1.0.0
  description: >-
    REST API behind the Depict Foundation merchant portal: merchants, products,
    collections, curation, metrics, analytics and search insights. All endpoints
    require an Auth0-issued bearer token.
servers:
  - url: ''
security: []
paths:
  /api/v1/merchants/{merchant_id}/products:
    post:
      tags:
        - Products
      summary: List Products Post Endpoint
      operationId: list_products_post_endpoint_api_v1_merchants__merchant_id__products_post
      parameters:
        - name: merchant_id
          in: path
          required: true
          schema:
            type: string
            title: Merchant Id
        - name: locale
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Locale
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ListProductsRequest'
              default:
                limit: 50
                sort_by: revenue_desc
                include_metrics: false
                shopper_facing_only: false
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicListProductsResult'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - Auth0: []
components:
  schemas:
    ListProductsRequest:
      properties:
        locale_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Locale Id
        market:
          anyOf:
            - type: string
            - type: 'null'
          title: Market
        market_group_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Market Group Id
        limit:
          type: integer
          maximum: 100
          minimum: 1
          title: Limit
          default: 50
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Cursor
        sort_by:
          allOf:
            - $ref: '#/components/schemas/SortOption'
          default: revenue_desc
        search:
          anyOf:
            - type: string
            - type: 'null'
          title: Search
        filters:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/GenericFilterValue'
              type: object
            - type: 'null'
          title: Filters
        include_metrics:
          type: boolean
          title: Include Metrics
          default: false
        shopper_facing_only:
          type: boolean
          title: Shopper Facing Only
          default: false
      type: object
      title: ListProductsRequest
    DynamicListProductsResult:
      properties:
        products:
          items:
            $ref: '#/components/schemas/ListedProduct'
          type: array
          title: Products
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        has_more:
          type: boolean
          title: Has More
          default: false
        sort_options:
          items:
            $ref: '#/components/schemas/SortOptionItem'
          type: array
          title: Sort Options
        stats:
          $ref: '#/components/schemas/ProductListingStats'
      type: object
      required:
        - products
        - sort_options
        - stats
      title: DynamicListProductsResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SortOption:
      type: string
      enum:
        - relevance
        - created_at_asc
        - created_at_desc
        - sale_price_asc
        - sale_price_desc
        - title_asc
        - title_desc
        - clicks_asc
        - clicks_desc
        - views_asc
        - views_desc
        - sold_asc
        - sold_desc
        - revenue_asc
        - revenue_desc
        - ctr_asc
        - ctr_desc
        - str_asc
        - str_desc
        - inventory_asc
        - inventory_desc
      title: SortOption
    GenericFilterValue:
      properties:
        values:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Values
        paths:
          anyOf:
            - items:
                items:
                  type: string
                type: array
              type: array
            - type: 'null'
          title: Paths
        operator:
          type: string
          enum:
            - or
            - and
          title: Operator
          default: or
        min_value:
          anyOf:
            - type: number
            - type: 'null'
          title: Min Value
        max_value:
          anyOf:
            - type: number
            - type: 'null'
          title: Max Value
      type: object
      title: GenericFilterValue
    ListedProduct:
      properties:
        main_product_id:
          type: string
          title: Main Product Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        main_image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Main Image Url
        hover_image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Hover Image Url
        metadata:
          items:
            oneOf:
              - $ref: '#/components/schemas/OnSaleMetadata'
              - $ref: '#/components/schemas/LowStockMetadata'
              - $ref: '#/components/schemas/OutOfStockMetadata'
              - $ref: '#/components/schemas/NewInMetadata'
              - $ref: '#/components/schemas/InactiveMetadata'
              - $ref: '#/components/schemas/LimitedAvailabilityMetadata'
              - $ref: '#/components/schemas/BestsellerMetadata'
              - $ref: '#/components/schemas/TrendingMetadata'
              - $ref: '#/components/schemas/SlowMoverMetadata'
              - $ref: '#/components/schemas/StarProductMetadata'
            discriminator:
              propertyName: type
              mapping:
                bestseller:
                  $ref: '#/components/schemas/BestsellerMetadata'
                inactive:
                  $ref: '#/components/schemas/InactiveMetadata'
                limited_availability:
                  $ref: '#/components/schemas/LimitedAvailabilityMetadata'
                low_stock:
                  $ref: '#/components/schemas/LowStockMetadata'
                new_in:
                  $ref: '#/components/schemas/NewInMetadata'
                on_sale:
                  $ref: '#/components/schemas/OnSaleMetadata'
                out_of_stock:
                  $ref: '#/components/schemas/OutOfStockMetadata'
                slow_mover:
                  $ref: '#/components/schemas/SlowMoverMetadata'
                star_product:
                  $ref: '#/components/schemas/StarProductMetadata'
                trending:
                  $ref: '#/components/schemas/TrendingMetadata'
          type: array
          title: Metadata
        metrics:
          anyOf:
            - $ref: '#/components/schemas/ProductMetrics'
            - type: 'null'
        is_auto_hidden:
          type: boolean
          title: Is Auto Hidden
          default: false
        hidden_in_market_groups:
          items:
            type: string
          type: array
          title: Hidden In Market Groups
          default: []
        hidden_in_markets:
          items:
            $ref: '#/components/schemas/HiddenVisibilityLocation'
          type: array
          title: Hidden In Markets
          default: []
      type: object
      required:
        - main_product_id
        - title
        - main_image_url
        - hover_image_url
        - metadata
      title: ListedProduct
    SortOptionItem:
      properties:
        id:
          type: string
          title: Id
        label:
          type: string
          title: Label
        selected:
          type: boolean
          title: Selected
      type: object
      required:
        - id
        - label
        - selected
      title: SortOptionItem
    ProductListingStats:
      properties:
        all_products:
          type: integer
          title: All Products
        all_out_of_stock:
          type: integer
          title: All Out Of Stock
        all_low_stock:
          type: integer
          title: All Low Stock
        total_products:
          type: integer
          title: Total Products
        out_of_stock:
          type: integer
          title: Out Of Stock
        low_stock:
          type: integer
          title: Low Stock
        on_sale:
          type: integer
          title: On Sale
        new_in:
          type: integer
          title: New In
        inactive:
          type: integer
          title: Inactive
        bestseller:
          type: integer
          title: Bestseller
        trending:
          type: integer
          title: Trending
        slow_mover:
          type: integer
          title: Slow Mover
        star_product:
          type: integer
          title: Star Product
      type: object
      required:
        - all_products
        - all_out_of_stock
        - all_low_stock
        - total_products
        - out_of_stock
        - low_stock
        - on_sale
        - new_in
        - inactive
        - bestseller
        - trending
        - slow_mover
        - star_product
      title: ProductListingStats
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    OnSaleMetadata:
      properties:
        type:
          type: string
          enum:
            - on_sale
          const: on_sale
          title: Type
          default: on_sale
        min_percentage:
          type: integer
          title: Min Percentage
        max_percentage:
          type: integer
          title: Max Percentage
      type: object
      required:
        - min_percentage
        - max_percentage
      title: OnSaleMetadata
    LowStockMetadata:
      properties:
        type:
          type: string
          enum:
            - low_stock
          const: low_stock
          title: Type
          default: low_stock
        sizes_in_stock:
          type: integer
          title: Sizes In Stock
        sizes_total:
          type: integer
          title: Sizes Total
      type: object
      required:
        - sizes_in_stock
        - sizes_total
      title: LowStockMetadata
    OutOfStockMetadata:
      properties:
        type:
          type: string
          enum:
            - out_of_stock
          const: out_of_stock
          title: Type
          default: out_of_stock
      type: object
      title: OutOfStockMetadata
    NewInMetadata:
      properties:
        type:
          type: string
          enum:
            - new_in
          const: new_in
          title: Type
          default: new_in
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
      type: object
      title: NewInMetadata
    InactiveMetadata:
      properties:
        type:
          type: string
          enum:
            - inactive
          const: inactive
          title: Type
          default: inactive
      type: object
      title: InactiveMetadata
    LimitedAvailabilityMetadata:
      properties:
        type:
          type: string
          enum:
            - limited_availability
          const: limited_availability
          title: Type
          default: limited_availability
        hidden_market_count:
          type: integer
          title: Hidden Market Count
        total_market_count:
          type: integer
          title: Total Market Count
      type: object
      required:
        - hidden_market_count
        - total_market_count
      title: LimitedAvailabilityMetadata
    BestsellerMetadata:
      properties:
        type:
          type: string
          enum:
            - bestseller
          const: bestseller
          title: Type
          default: bestseller
        meta_data:
          type: number
          title: Meta Data
        n_days:
          type: integer
          title: N Days
      type: object
      required:
        - meta_data
        - n_days
      title: BestsellerMetadata
    TrendingMetadata:
      properties:
        type:
          type: string
          enum:
            - trending
          const: trending
          title: Type
          default: trending
        meta_data:
          type: number
          title: Meta Data
        n_days:
          type: integer
          title: N Days
      type: object
      required:
        - meta_data
        - n_days
      title: TrendingMetadata
    SlowMoverMetadata:
      properties:
        type:
          type: string
          enum:
            - slow_mover
          const: slow_mover
          title: Type
          default: slow_mover
        meta_data:
          type: number
          title: Meta Data
        n_days:
          type: integer
          title: N Days
      type: object
      required:
        - meta_data
        - n_days
      title: SlowMoverMetadata
    StarProductMetadata:
      properties:
        type:
          type: string
          enum:
            - star_product
          const: star_product
          title: Type
          default: star_product
        meta_data:
          type: number
          title: Meta Data
        n_days:
          type: integer
          title: N Days
      type: object
      required:
        - meta_data
        - n_days
      title: StarProductMetadata
    ProductMetrics:
      properties:
        clicks:
          type: integer
          title: Clicks
          default: 0
        prev_clicks:
          type: integer
          title: Prev Clicks
          default: 0
        views:
          type: integer
          title: Views
          default: 0
        prev_views:
          type: integer
          title: Prev Views
          default: 0
        sold:
          type: integer
          title: Sold
          default: 0
        prev_sold:
          type: integer
          title: Prev Sold
          default: 0
        revenue:
          anyOf:
            - type: number
            - type: 'null'
          title: Revenue
          default: 0
        prev_revenue:
          anyOf:
            - type: number
            - type: 'null'
          title: Prev Revenue
          default: 0
        revenue_currency:
          type: string
          title: Revenue Currency
          default: ''
        inventory:
          type: integer
          title: Inventory
          default: 0
        click_through_rate:
          type: number
          title: Click Through Rate
          default: 0
        prev_click_through_rate:
          type: number
          title: Prev Click Through Rate
          default: 0
        sell_through_rate:
          type: number
          title: Sell Through Rate
          default: 0
        prev_sell_through_rate:
          type: number
          title: Prev Sell Through Rate
          default: 0
        add_to_carts:
          type: integer
          title: Add To Carts
          default: 0
        prev_add_to_carts:
          type: integer
          title: Prev Add To Carts
          default: 0
      type: object
      title: ProductMetrics
    HiddenVisibilityLocation:
      properties:
        market_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Market Id
        market_group_id:
          type: string
          title: Market Group Id
        source:
          type: string
          title: Source
        scope:
          anyOf:
            - type: string
            - type: 'null'
          title: Scope
      type: object
      required:
        - market_group_id
        - source
      title: HiddenVisibilityLocation
  securitySchemes:
    Auth0:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            openid: OpenID Connect
            profile: User profile
            email: User email
          authorizationUrl: https://depict.eu.auth0.com/oauth/authorize
          tokenUrl: https://depict.eu.auth0.com/oauth/token
      x-tokenName: id_token

````