Shopify Predictive Search API

openapi: 3.1.0
info:
  title: Shopify Admin REST About Predictive Search API
  description: The Shopify Admin REST API lets you build apps and integrations that extend and enhance the Shopify admin. Access products, customers, orders, inventory, fulfillment, and more. Endpoints are organized by resource type and versioned by release date.
  version: 2025-01
  contact:
    name: Shopify
    url: https://shopify.dev/docs/api/admin-rest
    email: api@shopify.com
  license:
    name: Shopify API Terms
    url: https://www.shopify.com/legal/api-terms
  x-date: '2026-03-04'
servers:
- url: https://{store}.myshopify.com/admin/api/2025-01
  description: Shopify Admin REST API
  variables:
    store:
      default: my-store
      description: The Shopify store subdomain
security:
- AccessToken: []
tags:
- name: Predictive Search
  description: Search suggestions for products, collections, pages, and articles
paths:
  /search/suggest.json:
    get:
      operationId: getPredictiveSearchResults
      summary: Shopify Get predictive search results
      description: Retrieves predictive search results for a query string. Returns matching products, collections, pages, articles, and query suggestions. Used for search-as-you-type experiences.
      tags:
      - Predictive Search
      parameters:
      - name: q
        in: query
        required: true
        description: The search query
        schema:
          type: string
      - name: resources[type]
        in: query
        description: Comma-separated resource types to search (product, page, article, collection, query)
        schema:
          type: string
          default: query,product,collection,page
      - name: resources[limit]
        in: query
        description: Number of results per type (1-10, default 10)
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 10
      - name: resources[limit_scope]
        in: query
        description: 'How the limit is distributed: all (shared across types) or each (per type)'
        schema:
          type: string
          enum:
          - all
          - each
          default: all
      - name: resources[options][unavailable_products]
        in: query
        description: How to handle unavailable products
        schema:
          type: string
          enum:
          - show
          - hide
          - last
          default: last
      - name: resources[options][fields]
        in: query
        description: Comma-separated fields to search within (title, product_type, vendor, tag, variants.title, variants.sku, body)
        schema:
          type: string
      responses:
        '200':
          description: Predictive search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: object
                    properties:
                      results:
                        type: object
                        properties:
                          queries:
                            type: array
                            items:
                              type: object
                              properties:
                                text:
                                  type: string
                                styled_text:
                                  type: string
                          products:
                            type: array
                            items:
                              $ref: '#/components/schemas/StorefrontProduct'
                          collections:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                title:
                                  type: string
                                handle:
                                  type: string
                                url:
                                  type: string
                                published_at:
                                  type: string
                                  format: date-time
                                body:
                                  type: string
                                image:
                                  type: object
                                  properties:
                                    url:
                                      type: string
                                      format: uri
                                    alt:
                                      type: string
                                    width:
                                      type: integer
                                    height:
                                      type: integer
                          pages:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                title:
                                  type: string
                                handle:
                                  type: string
                                url:
                                  type: string
                                body:
                                  type: string
                          articles:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                title:
                                  type: string
                                handle:
                                  type: string
                                url:
                                  type: string
                                body:
                                  type: string
                                published_at:
                                  type: string
                                  format: date-time
                                image:
                                  type: object
                                  properties:
                                    url:
                                      type: string
                                      format: uri
                                    alt:
                                      type: string
                                    width:
                                      type: integer
                                    height:
                                      type: integer
        '422':
          description: Invalid parameter
        '429':
          description: Rate limited
components:
  schemas:
    StorefrontProduct:
      type: object
      description: A product as returned by the storefront Ajax API
      properties:
        id:
          type: integer
        title:
          type: string
        handle:
          type: string
        description:
          type: string
        published_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        vendor:
          type: string
        type:
          type: string
        tags:
          type: array
          items:
            type: string
        price:
          type: integer
          description: Price in cents
        price_min:
          type: integer
        price_max:
          type: integer
        available:
          type: boolean
        price_varies:
          type: boolean
        compare_at_price:
          type:
          - integer
          - 'null'
        compare_at_price_min:
          type: integer
        compare_at_price_max:
          type: integer
        compare_at_price_varies:
          type: boolean
        variants:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              title:
                type: string
              option1:
                type:
                - string
                - 'null'
              option2:
                type:
                - string
                - 'null'
              option3:
                type:
                - string
                - 'null'
              sku:
                type:
                - string
                - 'null'
              requires_shipping:
                type: boolean
              taxable:
                type: boolean
              featured_image:
                type:
                - object
                - 'null'
              available:
                type: boolean
              name:
                type: string
              public_title:
                type:
                - string
                - 'null'
              price:
                type: integer
              weight:
                type: integer
              compare_at_price:
                type:
                - integer
                - 'null'
              barcode:
                type:
                - string
                - 'null'
        images:
          type: array
          items:
            type: string
            format: uri
        featured_image:
          type: string
          format: uri
        options:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              position:
                type: integer
              values:
                type: array
                items:
                  type: string
        url:
          type: string
        media:
          type: array
          items:
            type: object
            properties:
              alt:
                type:
                - string
                - 'null'
              id:
                type: integer
              position:
                type: integer
              media_type:
                type: string
              src:
                type: string
                format: uri
              width:
                type: integer
              height:
                type: integer
  securitySchemes:
    AccessToken:
      type: apiKey
      name: X-Shopify-Access-Token
      in: header
      description: Access token obtained via OAuth