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

# Find the best price for a product across retailers

> Find the lowest current price for a product across Amazon, Walmart, Costco, Home Depot, Nordstrom, and IKEA in US and Canada. Returns the cheapest option plus other retailer prices for comparison.



## OpenAPI

````yaml https://api.syntalic.com/openapi.json get /v1/shopper/best-price
openapi: 3.1.0
info:
  title: Syntalic — Pricing Intelligence API
  version: 1.0.0
  description: >-
    Real-time competitive pricing data across US and Canadian e-commerce
    retailers (Amazon, Walmart, Best Buy, Target, etc.). Serves price
    comparisons, deal alerts, brand tracking, promotional intelligence, and
    market analytics to AI agents via x402 and MPP micropayments.
  x-guidance: >-
    This API has three endpoint groups organized by use case:


    **Shopper endpoints** ($0.01/query): Use these for price comparisons and
    deal hunting. Start with /v1/shopper/best-price?q=<product> to find the
    cheapest option across retailers. Use
    /v1/shopper/deal-finder?category=<category> to find discounted products. Use
    /v1/shopper/price-drop-alert?q=<product> to check for recent price drops.


    **Marketing endpoints** ($0.01/query): Use these for competitive analysis.
    /v1/marketing/competitive-landscape?category=<category> shows all products
    in a category with pricing. /v1/marketing/brand-tracker?brand=<brand> tracks
    a brand's pricing over time.
    /v1/marketing/share-of-shelf?category=<category> shows brand market share.


    **Analyst endpoints** ($0.02/query): Use these for market-level insights.
    /v1/analyst/inflation?category=<category> shows price trends over time.
    /v1/analyst/price-dispersion?category=<category> shows price spread across
    retailers.


    All endpoints accept an optional 'country' parameter (us or ca, defaults to
    us). Query parameters use 'q' for free-text search and 'category' for
    category-level queries.
servers:
  - url: https://api.syntalic.com
security: []
paths:
  /v1/shopper/best-price:
    get:
      tags:
        - Shopper
      summary: Find the best price for a product across retailers
      description: >-
        Find the lowest current price for a product across Amazon, Walmart,
        Costco, Home Depot, Nordstrom, and IKEA in US and Canada. Returns the
        cheapest option plus other retailer prices for comparison.
      operationId: getBestPrice
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
          description: Search query (product name, keyword, or category term)
          example: airpods
        - name: country
          in: query
          required: false
          schema:
            type: string
            enum:
              - us
              - ca
            default: us
          description: Country (us or ca)
          example: us
        - name: retailer
          in: query
          required: false
          schema:
            type: string
            enum:
              - amazon
              - walmart
              - costco
              - homedepot
              - nordstrom
              - ikea
          description: Filter to a specific retailer
          example: amazon
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
          description: Max results to return (default 10, max 50)
          example: 10
      requestBody:
        required: false
        description: >-
          Query parameters as JSON (alternative to URL query string for agents
          that prefer body-based invocation).
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - q
              properties:
                q:
                  type: string
                  minLength: 1
                  description: Search query (product name, keyword, or category term)
                  example: airpods
                country:
                  type: string
                  enum:
                    - us
                    - ca
                  default: us
                  description: Country (us or ca)
                  example: us
                retailer:
                  type: string
                  enum:
                    - amazon
                    - walmart
                    - costco
                    - homedepot
                    - nordstrom
                    - ikea
                  description: Filter to a specific retailer
                  example: amazon
                limit:
                  type: integer
                  default: 10
                  maximum: 50
                  description: Max results to return (default 10, max 50)
                  example: 10
      responses:
        '200':
          description: Best price result
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  country:
                    type: string
                  currency:
                    type: string
                  best_price:
                    type: object
                    properties:
                      product_name:
                        type: string
                      retailer:
                        type: string
                      price:
                        type: number
                      list_price:
                        type: number
                        nullable: true
                      savings_pct:
                        type: number
                        nullable: true
                      in_stock:
                        type: boolean
                      condition:
                        type: string
                        enum:
                          - new
                          - refurbished
                          - used
                          - unknown
                        description: >-
                          Derived from product name + retailer URL signals (e.g.
                          Walmart 'Restored', Amazon Renewed). Defaults to 'new'
                          when no condition signal is present.
                      scraped_at:
                        type: string
                        format: date-time
                  other_prices:
                    type: array
                    items:
                      type: object
                      properties:
                        retailer:
                          type: string
                        price:
                          type: number
                        in_stock:
                          type: boolean
                        condition:
                          type: string
                          enum:
                            - new
                            - refurbished
                            - used
                            - unknown
        '402':
          description: Payment Required

````