Search

POST

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,
  "max_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

Show Query object

text

string

required

The text search query. e.g. “beach gear for miami”

image_url

string

Intended to be a reference or inspiration for the text query.

Image search is only available on Pro plans and above.

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).

max_result_count

integer

default:"2"

Maximum number of results to return.

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:

Show Product details

string

The unique identifier of the product.

title

string

The product title.

description

string

The product description.

product_type

string

The type/category of the product.

options

array

Available product options, each containing:

Show Option details

name

string

The name of the option (e.g., “Size”).

values

array

Array of possible values for this option (e.g., [“S”, “M”, “L”, “XL”]).

images

array

Array of product images.

variants

array

Array of product variants, each containing:

Show Variant details

string

The variant ID.

title

string

The variant title.

price

number

The variant price.

available

boolean

Whether the variant is available.

checkout_url

string

Direct URL to go to the variant’s checkout form with quantity 1.

checkout_url_with_shipping

string

Direct URL to go to the variant’s checkout form with quantity 1 and shipping address pre-filled.

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

store_id

string

ID of the store.

store_name

string

Name of the store.

store_domain

string

Domain of the store.

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.

{
  "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"
}

RetrieveRetrieve a profile.

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,
  "max_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"
}

Profiles

Styles

Shipping Addresses

Search

Headers

Body Parameters

Response

Search

Profiles

Styles

Shipping Addresses

​Headers

​Body Parameters

​Response

Headers

Body Parameters

Response