POST
/
search
/
products
curl --request POST \
  --url https://api.buybase.ai/search/products \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '{
  "query": {
    "text": "<string>",
    "image_url": "<string>"
  },
  "profile_id": "<string>",
  "store_id": "<string>",
  "store_domain": "<string>",
  "query_weight": 123,
  "style_weight": 123,
  "similarity_threshold": 123,
  "result_count": 123,
  "exclude_variant_ids": [
    {}
  ],
  "price_min": 123,
  "price_max": 123
}'
{
  "results": [
    {
      "id": "7924157309120",
      "title": "Classic Cotton T-Shirt",
      "handle": "classic-cotton-t-shirt",
      "description": "A comfortable everyday essential made from 100% organic cotton",
      "product_type": "t-shirt",
      "images": [ 
          "https://cdn.shopify.com/s/files/1/0680/5936/5568/files/tshirt_black_front.jpg",
          "https://cdn.shopify.com/s/files/1/0680/5936/5568/files/tshirt_black_back.jpg"
      ],
      "options": [
        {
          "name": "Size", 
          "values": [
            "S", "M", "L", "XL"
          ]
        },
        {
          "name": "Color", 
          "values": [
            "Black", "White", "Navy"
          ]
        }
      ],
      "variants": [
        {
          "id": 46002863112384,
          "title": "S / Black",
          "option1": "S",
          "option2": "Black",
          "option3": null,
          "price": "29.95",
          "available": true,
          "checkout_url": "https://fashion-store.com/cart/46002863112384:1",
          "checkout_url_with_shipping": "https://fashion-store.com/cart/46002863112384:1?checkout[email]=user@example.com&checkout[shipping_address][first_name]=John&checkout[shipping_address][last_name]=Doe&checkout[shipping_address][address1]=123 Main St&checkout[shipping_address][city]=New York&checkout[shipping_address][province]=NY&checkout[shipping_address][country]=US&checkout[shipping_address][zip]=10001"
        }
      ],
      "store_id": "store456",
      "store_name": "Fashion Store",
      "store_domain": "fashion-store.com"
    }
  ],
  "product_ids": ["7924157309120"],
  "code": "SEARCH_SUCCESS"
}

​
Headers

​
authorization
string
required

Your API key for authorization.

​
Body Parameters

​
query
object
required
​
profile_id
string

Optional ID of a profile to influence search results in a personalized way and provide checkout URLs with shipping forms pre-filled with the profile’s attached shipping address.

​
store_id
string

The ID of the store to search in.

​
store_domain
string

The domain of the store to search in.

​
query_weight
number
default:"1"

Weight to apply to the query which represents the text, image, or both (0-1).

When using a style profile, defaults to 0.7.

​
style_weight
number
default:"0.3"

Weight to apply to the style profile (0-1).

Only applies if profile_id is provided and the profile has a style attached.

​
similarity_threshold
number
default:"0.25"

Minimum similarity threshold for matching products (0-1).

​
result_count
integer
default:"2"

Number of results to return. Maximum depends on your plan.

​
exclude_variant_ids
array

Array of variant IDs to exclude from results.

​
price_min
number

Minimum price filter for the search results.

​
price_max
number

Maximum price filter for the search results.

​
Response

​
results
array

An array of product details, each containing:

​
product_ids
array

Array of product IDs returned in the results.

​
code
string

A code indicating the result of the search operation. Possible values:

  • SEARCH_SUCCESS: Search completed successfully with results
  • NO_RESULTS_FOUND: Search completed but no results found
  • INVALID_REQUEST: Invalid request parameters
  • STORE_NOT_FOUND: Store ID or brand not found
  • PROFILE_NOT_FOUND: Profile ID not found
  • INTERNAL_ERROR: Server error occurred
​
error
string

Error message if the request fails.

​
message
string

Additional details about the error if the request fails.

​
Plan Limitations

Feature availability varies by plan:

Free Plan:

  • No image search
  • Limited result count

Growth Plan:

  • No image search
  • Increased result count

Pro Plan:

  • Image search available
  • Higher result count limit
{
  "results": [
    {
      "id": "7924157309120",
      "title": "Classic Cotton T-Shirt",
      "handle": "classic-cotton-t-shirt",
      "description": "A comfortable everyday essential made from 100% organic cotton",
      "product_type": "t-shirt",
      "images": [ 
          "https://cdn.shopify.com/s/files/1/0680/5936/5568/files/tshirt_black_front.jpg",
          "https://cdn.shopify.com/s/files/1/0680/5936/5568/files/tshirt_black_back.jpg"
      ],
      "options": [
        {
          "name": "Size", 
          "values": [
            "S", "M", "L", "XL"
          ]
        },
        {
          "name": "Color", 
          "values": [
            "Black", "White", "Navy"
          ]
        }
      ],
      "variants": [
        {
          "id": 46002863112384,
          "title": "S / Black",
          "option1": "S",
          "option2": "Black",
          "option3": null,
          "price": "29.95",
          "available": true,
          "checkout_url": "https://fashion-store.com/cart/46002863112384:1",
          "checkout_url_with_shipping": "https://fashion-store.com/cart/46002863112384:1?checkout[email]=user@example.com&checkout[shipping_address][first_name]=John&checkout[shipping_address][last_name]=Doe&checkout[shipping_address][address1]=123 Main St&checkout[shipping_address][city]=New York&checkout[shipping_address][province]=NY&checkout[shipping_address][country]=US&checkout[shipping_address][zip]=10001"
        }
      ],
      "store_id": "store456",
      "store_name": "Fashion Store",
      "store_domain": "fashion-store.com"
    }
  ],
  "product_ids": ["7924157309120"],
  "code": "SEARCH_SUCCESS"
}