How to Access Shoply AI Search Through the API

Yes. You can query Shoply AI Search programmatically from your own backend without loading the on-site widget or sending the request through your Shopify storefront.

The standard search API is available with every Shopify plan that includes AI Search, including Forever Free. API requests use the same monthly search allowance as searches made through the storefront widget. See the current limits on our pricing page.

If you need higher limits, a service-level agreement, a custom data source, or an integration that does not use a Shoply-indexed Shopify catalog, contact us about an Enterprise plan.

Before You Start

Install Shoply AI on the Shopify store whose catalog you want to search and allow the initial product index to finish. You will need the store’s permanent myshopify.com domain, such as:

your-store.myshopify.com

The API can be called from any backend environment. A separate API key is not required for the standard product-search endpoint because it returns the same public catalog information that Shoply can display in the storefront search experience.

Endpoint

POST https://api.shoplyai.ai/product_query_v2
Content-Type: application/json

Request Body

query is a JSON string inside the request body, not a nested JSON object. For example, the search phrase waterproof hiking boots is sent as:

"{\"keywords\":\"waterproof hiking boots\"}"

cURL Example

Replace your-store.myshopify.com with your store’s permanent Shopify domain:

curl --request POST "https://api.shoplyai.ai/product_query_v2" \
  --header "Content-Type: application/json" \
  --data '{
    "store_key": "your-store.myshopify.com",
    "query": "{\"keywords\":\"waterproof hiking boots\"}",
    "start": 0,
    "limit": 8
  }'

JavaScript Example

// Build the inner query separately because the API expects it as a JSON-encoded string.
const searchQuery = JSON.stringify({
  keywords: "waterproof hiking boots"
});
 
const response = await fetch("https://api.shoplyai.ai/product_query_v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    store_key: "your-store.myshopify.com",
    query: searchQuery,
    start: 0,
    limit: 8
  })
});
 
if (!response.ok) {
  throw new Error(`Shoply search failed with status ${response.status}`);
}
 
const results = await response.json();
console.log(results.docs);

Python Example

import json
import requests
 
# The query value is encoded separately to match Shoply's structured search contract.
payload = {
    "store_key": "your-store.myshopify.com",
    "query": json.dumps({"keywords": "waterproof hiking boots"}),
    "start": 0,
    "limit": 8,
}
 
response = requests.post(
    "https://api.shoplyai.ai/product_query_v2",
    json=payload,
    timeout=30,
)
response.raise_for_status()
 
results = response.json()
print(results["docs"])

Response

A successful request returns:

{
  "num_results": 2,
  "docs": [
    {
      "product_id": "gid://shopify/Product/1234567890",
      "url": "https://your-store.example/products/example-product",
      "product_name": "Example Product",
      "brand": "Example Brand",
      "current_price": "129.00",
      "currency": "USD",
      "main_image": "https://cdn.shopify.com/example-product.jpg",
      "selected_variant_id": "gid://shopify/ProductVariant/1234567891"
    }
  ],
  "display_filters": []
}

• num_results is the total number of matching products.
• docs contains the ranked products for the requested page.
• display_filters contains available filters such as price, brand, color, or other catalog-specific attributes.

Product objects can contain additional fields depending on the store’s catalog, variants, pricing, and Shoply configuration. Clients should use the fields they need and safely ignore unfamiliar fields.

Pagination

Use start and limit to request additional results. For example, after requesting eight products with start: 0 and limit: 8, request the next page with:

{
  "start": 8,
  "limit": 8
}

Stop when start + docs.length is greater than or equal to num_results, or when docs is empty.

Plan and Integration Notes

• Standard API search is self-service and does not require the on-site widget.
• Your Shopify store must remain connected to Shoply AI so its product index can stay current.
• API searches and storefront searches share the monthly search allowance for your Shopify plan.
• Keep the call on your backend if you want to centralize caching, logging, retries, or access control.
• Contact us for Enterprise support if you need custom authentication, guaranteed throughput, an SLA, a non-Shopify catalog, or limits beyond the published plans.

For help confirming your store key or planning a production integration, contact Shoply AI.