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

# Offer Search



## OpenAPI

````yaml api-reference/openapi.json post /search/offers
openapi: 3.0.0
info:
  title: ValueChecker API
  description: The ValueChecker Application Programming Interface.
  version: 0.150.1
  x-logo:
    url: >-
      https://files.valuechecker.net/images/default-category-images/Value-Checker_top_bar_logo.png
    backgroundColor: '#FFFFFF'
    altText: ValueChecker logo
  contact:
    name: Contact
    url: https://www.valuechecker.net/contact/
    email: support@valuechecker.net
servers:
  - url: https://api.valuechecker.net/
    description: ValueChecker API URL.
security:
  - apiKey: []
tags:
  - name: default
externalDocs:
  description: PDF Documentation (official)
  url: https://www.valuechecker.net/docs/api/pdf
paths:
  /search/offers:
    post:
      tags:
        - default
      summary: Offer Search
      parameters:
        - $ref: '#/components/parameters/client_id'
        - $ref: '#/components/parameters/session-id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: >-
                    The product name, model number, or other identifier the
                    customer is claiming.
                image_urls:
                  type: array
                  items:
                    type: string
                  description: >-
                    One or more publicly reachable URLs that point to images
                    supporting the claim.
                images:
                  type: array
                  items:
                    type: string
                  description: >-
                    One or more base‑64‑encoded image strings (use when direct
                    URLs aren't available).
                claimed_amount:
                  type: number
                  multipleOf: 0.01
                  description: >-
                    The monetary amount (in the currency of record) that the
                    customer is requesting to be reimbursed.
                price_min:
                  type: number
                  multipleOf: 0.01
                  description: >-
                    Lower price threshold: offers priced below this value are
                    filtered out and not returned.
                price_max:
                  type: number
                  multipleOf: 0.01
                  description: >-
                    Upper price threshold: offers priced above this value are
                    filtered out and not returned.
      responses:
        '200':
          description: >-
            OK - Returns offer search results with claimed product, recommended
            offer, and replacement options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CuratedResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  description:
                    type: string
              example:
                error: Invalid JSON
                description: Could not parse an empty JSON body
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  event_code:
                    type: string
                  event_dict:
                    type: object
                    properties:
                      event_severity:
                        type: string
                      title:
                        type: string
                      description:
                        type: string
              example:
                error: User <user> does not have access to client_id <client_id>.
                event_code: ERIP00
                event_dict:
                  event_severity: ERROR
                  title: Invalid parameter
                  description: The "client_id" parameter is invalid.
components:
  parameters:
    client_id:
      name: client_id
      in: query
      schema:
        type: integer
      example: '10'
      description: >-
        The client ID for the request. It's required if you have access to
        multiple clients with your API key. Otherwise, it's optional.
    session-id:
      name: session-id
      in: query
      schema:
        type: string
      example: a1b2c3d4e5f6g7h8i9j0
      description: Optional session identifier of the user.
  schemas:
    CuratedResponse:
      type: object
      properties:
        claimed_product:
          anyOf:
            - $ref: '#/components/schemas/CuratedClaimedProduct'
            - type: object
              properties: {}
              example: {}
          description: >-
            The claimed product built from the search query/image. An empty
            object when no claimed product could be determined.
        recommended_offer:
          anyOf:
            - $ref: '#/components/schemas/CuratedRecommendedOffer'
            - type: object
              properties: {}
              example: {}
          description: >-
            The single ValueChecker-recommended offer/price for the search. An
            empty object when no recommendation could be made.
        indexed_products:
          anyOf:
            - $ref: '#/components/schemas/CuratedIndexedProducts'
            - type: object
              properties: {}
              example:
                products: []
        clustered_products:
          anyOf:
            - $ref: '#/components/schemas/CuratedClusteredProducts'
            - type: object
              properties: {}
              example:
                products: []
        replacement_offers:
          anyOf:
            - $ref: '#/components/schemas/CuratedReplacementOffers'
            - type: object
              properties: {}
              example:
                offer_groups: []
        metadata:
          $ref: '#/components/schemas/CuratedMetadata'
    CuratedClaimedProduct:
      type: object
      properties:
        pid:
          type: integer
        product_name:
          type: string
        brand:
          type: string
        pic_url:
          type: string
        specs:
          type: array
          items:
            $ref: '#/components/schemas/CuratedSpec'
        client_category_id:
          type: integer
        client_category:
          type: string
        in_stock:
          type: boolean
    CuratedRecommendedOffer:
      type: object
      properties:
        offer_type:
          $ref: '#/components/schemas/RecommendedOfferType'
        pid:
          type: integer
        product_name:
          type: string
        brand:
          type: string
        pic_url:
          type: string
        specs:
          type: array
          items:
            $ref: '#/components/schemas/CuratedSpec'
        client_category_id:
          type: integer
        client_category:
          type: string
        offer_id:
          type: integer
          nullable: true
        offer_url:
          type: string
        master_name:
          type: string
        unmatched_specs:
          type: array
          items:
            $ref: '#/components/schemas/CuratedSpec'
        price:
          $ref: '#/components/schemas/CuratedPrice'
    CuratedIndexedProducts:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/CuratedIndexedProduct'
    CuratedClusteredProducts:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/CuratedClusteredProduct'
    CuratedReplacementOffers:
      type: object
      properties:
        offer_groups:
          type: array
          items:
            $ref: '#/components/schemas/CuratedOfferGroup'
    CuratedMetadata:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/CuratedCategory'
        query:
          $ref: '#/components/schemas/CuratedQuery'
        price_filters:
          $ref: '#/components/schemas/CuratedPriceFilters'
    CuratedSpec:
      type: object
      properties:
        spec_id:
          type: integer
        spec_name:
          type: string
        spec_value_display:
          type: string
        spec_value_numeric:
          type: number
    RecommendedOfferType:
      type: string
      enum:
        - indexed_product
        - clustered_product
        - product_offer
    CuratedPrice:
      type: object
      properties:
        currency:
          type: string
        price:
          type: number
          multipleOf: 0.01
        price_date:
          type: string
        is_refurbished:
          type: boolean
        in_stock:
          type: boolean
        blocked:
          type: boolean
        shop:
          $ref: '#/components/schemas/CuratedShop'
        item_quantity:
          type: number
        country_code:
          type: string
        filtered_price:
          type: boolean
    CuratedIndexedProduct:
      type: object
      properties:
        product_name:
          type: string
        pid:
          type: integer
        pic_url:
          type: string
        price_clusters:
          $ref: '#/components/schemas/CuratedIndexedPriceCluster'
    CuratedClusteredProduct:
      type: object
      properties:
        pid:
          type: integer
        product_name:
          type: string
        brand:
          type: string
        pic_url:
          type: string
        specs:
          type: array
          items:
            $ref: '#/components/schemas/CuratedSpec'
        client_category_id:
          type: integer
        client_category:
          type: string
        price_clusters:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CuratedPriceClusters'
    CuratedOfferGroup:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/CuratedGroupMetadata'
        offers:
          type: array
          items:
            $ref: '#/components/schemas/CuratedOffer'
    CuratedCategory:
      type: object
      properties:
        predicted_client_category_id:
          type: integer
        predicted_client_category:
          type: string
        prediction_certainty:
          type: number
    CuratedQuery:
      type: object
      properties:
        used_query:
          type: string
        original_query:
          type: string
          nullable: true
        predicted_query:
          type: string
          nullable: true
    CuratedPriceFilters:
      type: object
      properties:
        price_min:
          type: number
          multipleOf: 0.01
          nullable: true
        price_max:
          type: number
          multipleOf: 0.01
          nullable: true
    CuratedShop:
      type: object
      properties:
        shop_name:
          type: string
        shop_status:
          type: integer
        shop_score:
          type: integer
    CuratedIndexedPriceCluster:
      type: object
      properties:
        low:
          $ref: '#/components/schemas/IndexedPriceCluster'
        medium:
          $ref: '#/components/schemas/IndexedPriceCluster'
        high:
          $ref: '#/components/schemas/IndexedPriceCluster'
    CuratedPriceClusters:
      type: object
      properties:
        low:
          $ref: '#/components/schemas/CuratedPriceCluster'
        medium:
          $ref: '#/components/schemas/CuratedPriceCluster'
        high:
          $ref: '#/components/schemas/CuratedPriceCluster'
    CuratedGroupMetadata:
      type: object
      properties:
        offer_count:
          type: integer
    CuratedOffer:
      type: object
      properties:
        pid:
          type: integer
        product_name:
          type: string
        brand:
          type: string
        pic_url:
          type: string
        specs:
          type: array
          items:
            $ref: '#/components/schemas/CuratedSpec'
        client_category_id:
          type: integer
        client_category:
          type: string
        offer_id:
          type: integer
          nullable: true
        offer_url:
          type: string
        master_name:
          type: string
        unmatched_specs:
          type: array
          items:
            $ref: '#/components/schemas/CuratedSpec'
        price:
          $ref: '#/components/schemas/CuratedPrice'
    IndexedPriceCluster:
      type: object
      properties:
        group:
          $ref: '#/components/schemas/GroupEnum'
        price:
          type: number
          multipleOf: 0.01
    CuratedPriceCluster:
      type: object
      properties:
        group:
          $ref: '#/components/schemas/GroupEnum'
        price:
          type: number
          multipleOf: 0.01
        count:
          type: integer
        percentage:
          type: number
        price_min:
          type: number
          multipleOf: 0.01
        price_max:
          type: number
          multipleOf: 0.01
    GroupEnum:
      type: string
      enum:
        - low
        - medium
        - high
  responses:
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              event_code:
                type: string
              event_dict:
                type: object
                properties:
                  event_severity:
                    type: string
                  title:
                    type: string
                  description:
                    type: string
          example:
            error: Invalid Authorization header
            event_code: ERIT00
            event_dict:
              event_severity: ERROR
              title: Invalid Authorization header
              description: Please provide the right authorization token
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Note! Prefix your <api-key> with `apiKey `. Note the space after "apiKey
        ".

````