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

# /2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/random-products

> Get a random sample of the recommendable products of a merchant, as held in the product cache. The sample is pre-selected when the catalog is imported: repeated calls return the same products until the next import. The result can be empty when the cache holds no recommendable product for the merchant.



## OpenAPI

````yaml https://api.criteo.com/2027-01/marketingsolutions/open-api-specifications.json get /2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/random-products
openapi: 3.0.1
info:
  title: Criteo API
  description: Criteo API - MarketingSolutions
  version: 2027-01
servers:
  - url: https://api.criteo.com
security:
  - oauth: []
tags:
  - name: Advertiser
  - name: Analytics
  - name: Audience
  - name: Campaign
  - name: Catalog
  - name: Creative
  - name: Gateway
  - name: Reco
paths:
  /2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/random-products:
    get:
      tags:
        - Catalog
      summary: >-
        /2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/random-products
      description: >-
        Get a random sample of the recommendable products of a merchant, as held
        in the product cache. The sample is pre-selected when the catalog is
        imported: repeated calls return the same products until the next import.
        The result can be empty when the cache holds no recommendable product
        for the merchant.
      operationId: GetCatalogRandomProducts
      parameters:
        - name: limit
          in: query
          description: Maximum number of products to return.
          required: true
          schema:
            maximum: 500
            minimum: 1
            type: integer
            format: int32
        - name: merchant-id
          in: path
          description: Identifies the merchant whose catalog products are read.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The random sample of recommendable products of the merchant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendableCatalogProductListResponse'
      security:
        - oauth:
            - MarketingSolutions_Catalog_Read
components:
  schemas:
    RecommendableCatalogProductListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RecommendableCatalogProductResource'
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/CommonProblem'
          nullable: true
          readOnly: true
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/CommonProblem'
          nullable: true
          readOnly: true
      description: >-
        A list of RecommendableCatalogProduct resources in `data`, with the
        `warnings` and `errors` met while building it.
      nullable: true
    RecommendableCatalogProductResource:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/RecommendableCatalogProduct'
        id:
          type: string
          nullable: true
          example: ss-149559-1041
        type:
          type: string
          nullable: true
          example: RecommendableCatalogProduct
      description: >-
        One RecommendableCatalogProduct: its `id`, its `type` (always
        `RecommendableCatalogProduct`) and its content in `attributes`.
      nullable: true
    CommonProblem:
      type: object
      properties:
        code:
          type: string
          description: A machine-readable error code, expressed as a string value.
          nullable: true
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem
          nullable: true
        instance:
          type: string
          description: A URI that identifies the specific occurrence of the problem.
          nullable: true
        source:
          type: object
          additionalProperties:
            type: string
          description: >-
            A machine-readable structure to reference to the exact location(s)
            causing the error(s)
          nullable: true
        stackTrace:
          type: string
          nullable: true
        title:
          type: string
          description: A short human-readable description of the problem type
          nullable: true
        traceId:
          type: string
          description: The request correlation ID this problem comes from.
          nullable: true
        traceIdentifier:
          type: string
          description: >-
            The request correlation ID this problem comes from. (deprecated, use
            traceId instead)
          nullable: true
        type:
          enum:
            - unknown
            - access-control
            - authentication
            - authorization
            - availability
            - deprecation
            - quota
            - validation
          type: string
          description: The problem's category.
          nullable: true
      description: Common problem object.
    RecommendableCatalogProduct:
      type: object
      properties:
        additionalImageLinks:
          type: array
          items:
            type: string
            nullable: true
          description: Additional product image URLs.
          nullable: true
          example:
            - https://www.acmefr.example/images/149559_1041_square_2.jpg
        adult:
          type: boolean
          description: Whether the product is flagged as adult content.
          example: false
        adwordsGrouping:
          type: string
          description: >-
            Google Ads (AdWords) grouping label used for Shopping/CPC campaign
            grouping.
          nullable: true
          example: backpacks
        adwordsLabels:
          type: array
          items:
            type: string
            nullable: true
          description: Google Ads (AdWords) labels associated with the product.
          nullable: true
          example:
            - summer-sale
        adwordsRedirect:
          type: string
          description: >-
            Redirect URL used for the product link in CPS campaigns. The landing
            page URL is used when empty.
          nullable: true
          example: https://www.acmefr.example/r/ss-149559-1041
        ageGroup:
          $ref: '#/components/schemas/ProductAgeGroup'
        alternateIds:
          type: array
          items:
            type: string
            nullable: true
          description: >-
            Additional identifiers of the product (for example UPC variants),
            when supplied by the partner.
          nullable: true
          example:
            - ss-149559-1041-upc
        availability:
          $ref: '#/components/schemas/ProductAvailability'
        availabilityDate:
          type: string
          description: >-
            Date from which a preorder or backorder product becomes available,
            as provided by the partner.
          nullable: true
          example: '2026-10-01T00:00:00Z'
        badge:
          type: string
          description: URL of a badge image to display alongside the product.
          nullable: true
          example: https://www.acmefr.example/badges/bestseller.png
        begindate:
          type: string
          description: >-
            Start of the period during which the product is eligible for
            recommendation, paired with {enddate}.
          format: date-time
          nullable: true
          example: '2026-09-01T00:00:00.0000000+00:00'
        brand:
          type: string
          description: Product brand.
          nullable: true
          example: Samsonite
        category1:
          type: string
          description: First-level category, used by the recommendation engine.
          nullable: true
          example: Luggage & Bags
        category2:
          type: string
          description: Second-level category. Null when not applicable.
          nullable: true
          example: Backpacks
        category3:
          type: string
          description: Third-level category. Null when not applicable.
          nullable: true
          example: Laptop Backpacks
        color:
          type: string
          description: Product color.
          nullable: true
          example: Black
        condition:
          $ref: '#/components/schemas/ProductCondition'
        createdDate:
          type: string
          description: When the product was first created in the catalog.
          format: date-time
          nullable: true
          example: '2026-09-01T08:30:00.0000000+00:00'
        crossSellersProductId:
          type: string
          description: >-
            Key grouping all the seller offers of the same physical product
            across sellers. Drives the seller offer and buy box winner logic.
          nullable: true
          example: XPD-4481
        customLabel0:
          type: string
          description: Client-defined label for custom filtering and segmentation.
          nullable: true
          example: BACKPACK&BAG
        customLabel1:
          type: string
          description: Client-defined label, same as {customLabel0}.
          nullable: true
          example: summer
        customLabel2:
          type: string
          description: Client-defined label, same as {customLabel0}.
          nullable: true
          example: outlet
        customLabel3:
          type: string
          description: Client-defined label, same as {customLabel0}.
          nullable: true
          example: new-collection
        customLabel4:
          type: string
          description: Client-defined label, same as {customLabel0}.
          nullable: true
          example: premium
        deletedDate:
          type: string
          description: When the product was removed from the catalog, if it was.
          format: date-time
          nullable: true
          example: '2026-09-20T10:00:00.0000000+00:00'
        description:
          type: string
          description: Product description.
          nullable: true
          example: Round-shaped business casual backpack in leather.
        discount:
          type: number
          description: Discount amount used to display promotional pricing in ads.
          format: double
          nullable: true
          example: 15.5
        displayable:
          type: boolean
          description: >-
            Whether the product meets the basic display eligibility rules.
            Distinct from {recommendable}.
          example: true
        displayAdsId:
          type: string
          description: Identifier used for the display ads creative mapping.
          nullable: true
          example: da-149559-1041
        displayAdsLink:
          type: string
          description: Landing page URL used for display campaigns served through Google.
          nullable: true
          example: >-
            https://www.acmefr.example/sunfire/backpack/ss-149559-1041.html?src=display
        displayAdsTitle:
          type: string
          description: >-
            Shorter title used in display creatives when {name} does not fit the
            banner format.
          nullable: true
          example: Sunfire Backpack
        displayAdsValue:
          type: number
          description: >-
            Margin value used for margin-based bidding optimization, in local
            currency or as a rate.
          format: double
          nullable: true
          example: 0.35
        enddate:
          type: string
          description: >-
            End of the period during which the product is eligible for
            recommendation, paired with {begindate}.
          format: date-time
          nullable: true
          example: '2026-12-31T23:59:59.0000000+00:00'
        energyEfficiencyClass:
          type: string
          description: EU energy efficiency label class, where applicable.
          nullable: true
          example: A++
        excludedChannels:
          type: array
          items:
            type: string
            nullable: true
          description: >-
            Criteo channels the product is explicitly excluded from:
            {PERF_MEDIA}, {RM_ONSITE} or {RM_OFFSITE}.
          nullable: true
          example:
            - RM_OFFSITE
        expirationDate:
          type: string
          description: >-
            When the product stops being eligible for recommendation. Null when
            the partner gave none or gave a value that is not a date.
          format: date-time
          nullable: true
          example: '2026-12-31T23:59:59.0000000+00:00'
        extra:
          type: object
          additionalProperties:
            type: string
            nullable: true
          description: >-
            Free-form custom attributes of the product, by name. The names
            depend on the partner's catalog.
          nullable: true
        filters:
          type: object
          additionalProperties:
            type: string
            nullable: true
          description: >-
            Retailer-site search filters the product matches, by filter name.
            Values are JSON-encoded strings.
          nullable: true
        gender:
          $ref: '#/components/schemas/ProductGender'
        googleProductCategory:
          type: string
          description: Google product category, as a taxonomy path.
          nullable: true
          example: Luggage & Bags > Cosmetic & Toiletry Bags
        gtin:
          type: string
          description: Global Trade Item Number.
          nullable: true
          example: '5400520246585'
        hashedExternalId:
          type: integer
          description: Hash of {id}, computed by Criteo.
          format: int64
          example: 6482838394677175000
        id:
          type: string
          description: Product identifier as provided by the partner (external id).
          nullable: true
          example: ss-149559-1041
        imageUrl:
          type: string
          description: Primary product image URL.
          nullable: true
          example: https://www.acmefr.example/images/149559_1041_square_1.jpg
        inStock:
          type: boolean
          description: >-
            Whether the product is currently in stock, in its raw boolean form.
            See also {availability}.
          example: true
        itemGroupId:
          type: string
          description: >-
            Groups the variants of a product together. Null or empty for a
            standalone product.
          nullable: true
          example: ss-149559
        lastUpdateDate:
          type: string
          description: When the product was last updated by a catalog import.
          format: date-time
          nullable: true
          example: '2026-09-23T06:15:00.0000000+00:00'
        material:
          type: string
          description: Product material.
          nullable: true
          example: Leather
        mobileLink:
          type: string
          description: Mobile-optimized landing page URL.
          nullable: true
          example: https://m.acmefr.example/sunfire/backpack/ss-149559-1041.html
        mpn:
          type: string
          description: Manufacturer Part Number.
          nullable: true
          example: QT7*09001
        multipack:
          type: integer
          description: Number of identical products included when sold as a multipack.
          format: int32
          nullable: true
          example: 3
        name:
          type: string
          description: Product title.
          nullable: true
          example: Sunfire Backpack Black
        numberOfReviews:
          type: integer
          description: Number of reviews collected for the product.
          format: int32
          nullable: true
          example: 128
        pattern:
          type: string
          description: Product pattern.
          nullable: true
          example: Plain
        price:
          type: number
          description: >-
            Current price of the product, in the currency of the partner's
            account (no currency code is sent).
          format: double
          example: 342000
        productRating:
          type: string
          description: Average product rating.
          nullable: true
          example: '4.6'
        productType:
          type: string
          description: >-
            Merchandising category path matching the partner's own website
            architecture. May hold several comma-separated, quoted paths.
          nullable: true
          example: Backpacks > Sunfire
        productTypeKey:
          type: string
          description: Unique id or hierarchy key paired with {productType}.
          nullable: true
          example: bp-sunfire
        productUrl:
          type: string
          description: Product landing page URL.
          nullable: true
          example: https://www.acmefr.example/sunfire/backpack/ss-149559-1041.html
        promoText:
          type: string
          description: Promotional text associated with the product.
          nullable: true
          example: Free shipping this week
        promotionId:
          type: string
          description: Identifier of the single promotion applied to the product.
          nullable: true
          example: PROMO-2026-09
        promotionIds:
          type: array
          items:
            type: string
            nullable: true
          description: Identifiers of all the promotions applied to the product.
          nullable: true
          example:
            - PROMO-2026-09
            - FREESHIP
        recommendable:
          type: boolean
          description: Whether the product is currently eligible for recommendation.
          example: true
        retailPrice:
          type: number
          description: Price before discount.
          format: double
          nullable: true
          example: 399000
        salePriceEffectiveDate:
          type: string
          description: >-
            Period during which a sale price is valid, as start/end separated by
            a slash.
          nullable: true
          example: 2026-09-01T00:00:00Z/2026-09-30T23:59:59Z
        sellerId:
          type: string
          description: >-
            Identifier of the marketplace seller offering the product, if
            applicable.
          nullable: true
          example: seller-77
        sellerName:
          type: string
          description: Name of the marketplace seller offering the product, if applicable.
          nullable: true
          example: Bag World
        sizes:
          type: array
          items:
            type: string
            nullable: true
          description: Available sizes.
          nullable: true
          example:
            - One Size
        smallImageUrl:
          type: string
          description: Thumbnail-sized version of the product image URL.
          nullable: true
          example: https://www.acmefr.example/images/149559_1041_small.jpg
        unitPricingBaseMeasure:
          type: string
          description: 'Denominator unit for unit pricing: the value followed by its unit.'
          nullable: true
          example: 100ml
        unitPricingMeasure:
          type: string
          description: >-
            Measure and dimension of the product used for unit pricing: the
            value followed by its unit.
          nullable: true
          example: 750ml
      description: >-
        One product of a random sample of a partner's recommendable products: a
        curated, client-facing subset of the imported product held in the
        product cache. Fields only meaningful inside Criteo are not part of it.
      nullable: true
    ProductAgeGroup:
      enum:
        - newborn
        - infant
        - toddler
        - kids
        - adult
      type: string
      description: Age group a product targets, serialized as its lower-case name.
      example: newborn
      x-enumNames:
        - Newborn
        - Infant
        - Toddler
        - Kids
        - Adult
      x-enum-varnames:
        - Newborn
        - Infant
        - Toddler
        - Kids
        - Adult
    ProductAvailability:
      enum:
        - inStock
        - outOfStock
        - preorder
        - backorder
      type: string
      description: Stock availability of a product, serialized as its camelCase name.
      example: inStock
      x-enumNames:
        - InStock
        - OutOfStock
        - Preorder
        - Backorder
      x-enum-varnames:
        - InStock
        - OutOfStock
        - Preorder
        - Backorder
    ProductCondition:
      enum:
        - new
        - refurbished
        - used
      type: string
      description: Condition of a product, serialized as its lower-case name.
      example: new
      x-enumNames:
        - New
        - Refurbished
        - Used
      x-enum-varnames:
        - New
        - Refurbished
        - Used
    ProductGender:
      enum:
        - male
        - female
        - unisex
      type: string
      description: Gender a product targets, serialized as its lower-case name.
      example: male
      x-enumNames:
        - Male
        - Female
        - Unisex
      x-enum-varnames:
        - Male
        - Female
        - Unisex
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.criteo.com/oauth2/token
          scopes:
            MarketingSolutions_Analytics_Read: >-
              Grants Read access to the capabilities from the Analytics domain,
              for MarketingSolutions applications
            MarketingSolutions_Audience_Manage: >-
              Grants Manage access to the capabilities from the Audience domain,
              for MarketingSolutions applications
            MarketingSolutions_Audience_Read: >-
              Grants Read access to the capabilities from the Audience domain,
              for MarketingSolutions applications
            MarketingSolutions_Campaign_Manage: >-
              Grants Manage access to the capabilities from the Campaign domain,
              for MarketingSolutions applications
            MarketingSolutions_Campaign_Read: >-
              Grants Read access to the capabilities from the Campaign domain,
              for MarketingSolutions applications
            MarketingSolutions_Catalog_Read: >-
              Grants Read access to the capabilities from the Catalog domain,
              for MarketingSolutions applications
            MarketingSolutions_Creative_Manage: >-
              Grants Manage access to the capabilities from the Creative domain,
              for MarketingSolutions applications
            MarketingSolutions_Creative_Read: >-
              Grants Read access to the capabilities from the Creative domain,
              for MarketingSolutions applications
            MarketingSolutions_Reco_Manage: >-
              Grants Manage access to the capabilities from the Reco domain, for
              MarketingSolutions applications
            MarketingSolutions_Reco_Read: >-
              Grants Read access to the capabilities from the Reco domain, for
              MarketingSolutions applications
        authorizationCode:
          authorizationUrl: https://api.criteo.com/oauth2
          tokenUrl: https://api.criteo.com/oauth2/token
          scopes:
            MarketingSolutions_Analytics_Read: >-
              Grants Read access to the capabilities from the Analytics domain,
              for MarketingSolutions applications
            MarketingSolutions_Audience_Manage: >-
              Grants Manage access to the capabilities from the Audience domain,
              for MarketingSolutions applications
            MarketingSolutions_Audience_Read: >-
              Grants Read access to the capabilities from the Audience domain,
              for MarketingSolutions applications
            MarketingSolutions_Campaign_Manage: >-
              Grants Manage access to the capabilities from the Campaign domain,
              for MarketingSolutions applications
            MarketingSolutions_Campaign_Read: >-
              Grants Read access to the capabilities from the Campaign domain,
              for MarketingSolutions applications
            MarketingSolutions_Catalog_Read: >-
              Grants Read access to the capabilities from the Catalog domain,
              for MarketingSolutions applications
            MarketingSolutions_Creative_Manage: >-
              Grants Manage access to the capabilities from the Creative domain,
              for MarketingSolutions applications
            MarketingSolutions_Creative_Read: >-
              Grants Read access to the capabilities from the Creative domain,
              for MarketingSolutions applications
            MarketingSolutions_Reco_Manage: >-
              Grants Manage access to the capabilities from the Reco domain, for
              MarketingSolutions applications
            MarketingSolutions_Reco_Read: >-
              Grants Read access to the capabilities from the Reco domain, for
              MarketingSolutions applications

````