> ## 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/products/search

> Get specific products of a merchant from the product cache, by their external ids. This is a read: it is a POST only because the ids travel in the body. Ids that match no product of the merchant are left out of the response, so the result can be empty or shorter than the request.



## OpenAPI

````yaml https://api.criteo.com/2027-01/marketingsolutions/open-api-specifications.json post /2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search
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/products/search:
    post:
      tags:
        - Catalog
      summary: >-
        /2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search
      description: >-
        Get specific products of a merchant from the product cache, by their
        external ids. This is a read: it is a POST only because the ids travel
        in the body. Ids that match no product of the merchant are left out of
        the response, so the result can be empty or shorter than the request.
      operationId: SearchCatalogProductsByExternalIds
      parameters:
        - name: merchant-id
          in: path
          description: Identifies the merchant whose catalog products are read.
          required: true
          schema:
            type: string
      requestBody:
        description: The external ids to look up, between 1 and 500.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductsByExternalIdsRequest'
        required: true
        x-bodyName: request
      responses:
        '200':
          description: The products of the merchant that match the given external ids.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductByExternalIdListResponse'
      security:
        - oauth:
            - MarketingSolutions_Catalog_Read
components:
  schemas:
    ProductsByExternalIdsRequest:
      required:
        - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ProductsByExternalIdsRequestData'
      description: Request to look up products of a merchant by their external ids.
      nullable: true
    ProductByExternalIdListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProductByExternalIdResource'
          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 ProductByExternalId resources in `data`, with the `warnings`
        and `errors` met while building it.
      nullable: true
    ProductsByExternalIdsRequestData:
      required:
        - attributes
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/ProductsByExternalIdsRequestAttributes'
        type:
          type: string
          description: Kind of resource looked up. Not read by the API.
          nullable: true
          example: ProductByExternalId
      description: The lookup to perform, in the resource envelope of the API.
      nullable: true
    ProductByExternalIdResource:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/ProductByExternalId'
        id:
          type: string
          nullable: true
          example: ss-146119-1726
        type:
          type: string
          nullable: true
          example: ProductByExternalId
      description: >-
        One ProductByExternalId: its `id`, its `type` (always
        `ProductByExternalId`) 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.
    ProductsByExternalIdsRequestAttributes:
      required:
        - externalIds
      type: object
      properties:
        externalIds:
          maxItems: 500
          minItems: 1
          type: array
          items:
            type: string
            nullable: true
          description: >-
            External ids of the products, as given in the partner's feed. Not
            empty, at most 500. Ids that match no product of the merchant are
            left out of the response, without an error.
          nullable: true
          example:
            - ss-146119-1726
            - ss-163828-1041
      description: The external ids of the products to look up.
      nullable: true
    ProductByExternalId:
      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
        beginEligibleDate:
          type: string
          description: >-
            Start of the period during which the product is eligible for
            recommendation, paired with {endEligibleDate}.
          format: date-time
          nullable: true
          example: '2026-09-01T00:00:00.0000000+00:00'
        blockedDate:
          type: string
          description: >-
            When the product was blocked from recommendation. Null when the
            product is not blocked.
          format: date-time
          nullable: true
          example: '2026-09-15T12:00:00.0000000+00:00'
        blockedMatch:
          type: string
          description: >-
            The keyword, value or id that matched the blocking rule. Null when
            the product is not blocked.
          nullable: true
          example: counterfeit
        blockedType:
          $ref: '#/components/schemas/ProductBlockedType'
        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
        endEligibleDate:
          type: string
          description: >-
            End of the period during which the product is eligible for
            recommendation, paired with {beginEligibleDate}.
          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
        smallimage:
          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 looked up by its external id in a partner's catalog: a
        curated, client-facing subset of the imported product held in the
        product cache, with the reason it is blocked from recommendation when it
        is. 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
    ProductBlockedType:
      enum:
        - Keyword
        - Image
        - ProductID
        - Category
      type: string
      description: Why a product is blocked from recommendation.
      example: Keyword
      x-enumNames:
        - Keyword
        - Image
        - ProductId
        - Category
      x-enum-varnames:
        - Keyword
        - Image
        - ProductId
        - Category
    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

````