Overview

Unbxd Search replaces Shopify’s native search with fast, AI-powered, fully configurable search. Unbxd connects to your Shopify store and indexes your products and categories, delivering accurate results across your site. Customers can search from any page, and you can enable full search-results pages for advanced filtering and merchandising.

Installing Unbxd with Shopify

1. Steps to Create Access Token for Shopify

Navigate to the admin panel of your Shopify store and click Apps
Under App, select the pop-up App and sales channel settings and click Develop apps for your store.
Click on Create an app and when prompted click on Unbxd Search App > Create app.
Within the Create App section, click Configure Admin API Scopes. Search for the below and enable the checkboxes:

Search Keyword	Permission Group	Permission Name
product	Product feeds	read_product_feed
product	Product listing	read_product_listing
product	Products	read_products
channels	Sales_channels	read_channels
themes	Themes	write_themes

then click Save.

To access store data, click API credentials and copy the API key and secret key.

Click Install and reveal the token and save it.

📘
Note
To protect your data, you will only be able to see the Admin API token once. Copy and save your Admin API access token in a secure place.

After generating the access token, share the following details with the Unbxd Support team or your Technical Project Manager (TPM) to complete the installation of the Unbxd Shopify Plugin:

Shopify access token
Shopify store name
Indexing interval

Once these details are shared, the Unbxd team will complete the installation.

📘
Note
After installation, Unbxd automatically triggers the feed indexing process.

2. Index Feed

Unbxd will connect to your specific Shopify store and index your products and collections data into an Unbxd site. Refer to the table below for the details of attributes.

Component	Feature	Description	Configuration
Product Information	Product related fields	The following fields are supported: `id` → uniqueId [last segment of GID] `descriptionHtml` → `descriptionHtml` [unchanged] `createdAt` → `createdAt` [normalized to UTC ISO] handle → `productUrl`, handle [URL built as /products/handle; handle kept] `featuredImage.originalSrc` → `imageUrl` [URL only] `featuredImage.altText` → `imageUrlAltText` [alt text] `images` → `images` [unchanged structure] `productType` → `productType` [unchanged] `publishedAt` → `publishedAt` [normalized to UTC ISO] `tags` → `tags` + `derived keys` [kept as tags; also expands key:value tags into additional fields] `templateSuffix` → `templateSuffix` [unchanged] `totalInventory` → `totalInventory` [unchanged; also used in availability calc] `tracksInventory` → `availability` [true if tracking and totalInventory>0; true if not tracking] `title` → `title` [unchanged] `vendor` → `vendor` [unchanged] `productCategory.productTaxonomyNode.fullName` → `productCategory_fullName [flattened]` `productCategory.productTaxonomyNode.name` → `productCategory_name [flattened]` `updatedAt` → `updatedAt` [normalized to UTC ISO] `isGiftCard` → `isGiftCard` [unchanged] `collections` → `collections` [unchanged]
	variants	Following fields are supported: id → variantId [last segment of GID] compareAtPrice → v_compareAtPrice [decimal] createdAt → v_createdAt [UTC ISO] image.originalSrc → v_imageUrl [URL only] inventoryQuantity → v_inventoryQuantity [unchanged] selectedOptions → v_selectedOptions plus per-option fields `[v_<OptionName> = value]` inventoryPolicy → v_inventoryPolicy [unchanged] price → v_price [decimal] requiresShipping → v_requiresShipping [unchanged] sku → v_sku [unchanged] taxable → v_taxable [unchanged] taxCode → v_taxCode [unchanged] title → v_title [unchanged] updatedAt → v_updatedAt [UTC ISO] weight → v_weight [unchanged] weightUnit → v_weightUnit [unchanged] availableForSale → v_availableForSale [unchanged field + contributes to availability summary]
	metafields	For metafield with the datatype of following, a new field in Unbxd will be created. Only these fields can be used for any Unbxd functionalities including merchandising, filter, sort etc. All fields derived with metafields have prefix called 'meta_'. By default following datatypes are extracted number_integer list.number_integer number_decimal list.number_decimal list.single_line_text_field list.url list.color string json color multi_line_text_field single_line_text_field url With the special configuration, following datatypes will be extracted file_reference metaobject_reference All fields derived from metafields will have datatype as "link"	There is option to change schema for the fields derived from the metafields in admin panel
	collections	Following fields are getting fetched: handle: At Unbxd, the field name is "category_handle" title: At Unbxd, the field name is "category"
	Price related	At Parent: price: minimum price across all variants compareAtPrice: compareAtPrice for the variant which has minimum price computed_discount: ceil((compareAtPrice - price/compareAtPrice) * 100) At Variant: computed_discount: ceil((compareAtPrice - price/compareAtPrice) * 100)
	tags	By default, Plugins splits the value of tags with ":" as delimiter and creates new field at Unbxd. All fields derived from tags will have prefix called "tags_" Following options are available: Delimiter: Supports any character	There is option to change schema for the fields derived from the tags in admin panel. Documented in self serve FAQ
		Custom Field availableForSaleOfVariants: If one of variants 'availablityForSale' is 'True', then this field is set to 'True' If "totalInventory > 0" and "availableForSaleOfVariants is True", then availablity is set to true
	Multi store(inventory) support	Fetch inventory details for Variants using graphQL `{ productVariants(first:{variants_size}, query:"{variants_query_of_ids}") { edges { node { id inventoryItem { id inventoryLevels(first:{stores_count}) { edges { node { id quantities(names: ["available"]) { name quantity } location { metafield(key: "{metafield_key}", namespace: "{metafield_namespace}") { value key } } } } } } } } } }`
	Translations(MultiLanguage)	According to the 'locale' parameter associated with the language, all fields will be fetched	By default, locale parameter is set to 'en'. For changing the locale parameter to corresponding language for the sitekey,
	Field translations	Shopify doesn’t translate every field through locale translation. This feature supports the translation of field values whose translated values are mapped and added in the Shopify locale JSON file.	Requirement to configure this are: `Language code Translated file name Shopify theme id Fields mapping with translation`
	Multi-regional currency	Varying product prices can be maintained for different regions based on the market. Also, they can be represented in different currencies. This feature supports fetching product prices for all regions.	We can add the transformer configuration without any params.
	Newness Property	Based on the createdAt field of the product, this feature marks the product with a field called newness: New Arrivals. Additionally, it adds an additional field called days_since_createdAt, which holds the number of days since this product was created.	Transformer configuration: Characters to filter (if not default) (optional). Field names (List of field names whose value needs cleaning). Field names (List of field names whose value needs cleaning).days_of_newness (optional): days to be consider as, new default value 60 days
	Variants Meta-fields .	By default variants meta-fields are not fetched, if required this feature can be added to fetch variants meta-fields	No configurations required, just add the transformer config
	Custom Fields(Custom Business Logics or use cases)		There are no default transformer supported, But Plugin allows to write the custom script for any customer based upon their business logic. For writing the custom script, Please raise the Jira in the PLUG board
	Blogs Articles	Blog Information Articles associated with blogs will be pulled, here are the fields which are fetched: title created_at blog_id author updated_at productUrl handle tags admin_graphql_api_id body_html
Pages Information	pages	Sync’ing data from Shopify pages `author created_at handle id published_at shop_id template_suffix title updated_at admin_graphql_api_id body_html`
Collections (Banners) Information	collections datas are synced as separate content-type.	Sync’ing data from Shopify collections. `id title handle updatedAt imageUrl imageAltText productsCount description seo_title seo_description`
Synchronisation	Full indexing All properties of Product Information and Blog Information will be supported.	Product Information: Plugin using admin API and graphql to fetch the products and don't use any of the storefront API for integration. There are documentation for storefront API and admin API in shopify with similar content. Please make sure, we are checking admin API documentation for referring anything. https://shopify.dev/docs/api/admin-graphql/2023-07/objects/ProductVariant vs https://shopify.dev/docs/api/storefront/2023-07/objects/ProductVariant#connection-productvariant-storeavailability Plugin uses graphql with the "bulkOperation" feature of Shopify. Using this, Shopify would pull all the matching results and push it to file. Once the file is ready from the shopify, Plugin pulls the file and uses to process the dataBlog Information: Plugin uses REST API to pull all the blog contents Limitation: Shopify has the limitation where they support only onejob(either it is full or delta) at a time. If a delta is running, then full would not execute and vice versa. Make sure delta indexing and full indexing interval is set such that, it never co-incides.	hat token can then be added to the AppUserProp in Viper DB with the property key as “delta_access_token”and value as token value. We will then be able to use 2 diff tokens in parallel for full and delta feeds respectively.
	Delta indexing	Supported only for Product Information. Based upon the last pulled time at the plugin, Delta indexing would pull all the updated product from shopify using Graphql query with the filter clauses matching "updated_at > last pulled time". Limitation: Shopify has the limitation where they support only one operation at a time. For pulling approximately 130s for 300 products and 3000 variants. Very frequent product synchronisation is not supported by Shopify Minimum duration for which delta indexing can be set is 15 minutes. Platform doesn't support more frequent feed upload	yes, API to set/unset the scheduled interval is available from the plugin. Steps documented at Shopify plugin

3. Set up Unbxd Search in Shopify

Next, you have to integrate Search on the Storefront. Customers can utilise custom storefront frameworks for complete control over UI and performance. Supported approaches include:

Storefront Type	Integration Method	Tools / Libraries	Notes
Default Liquid storefront	Unbxd JS Search Template	https://unbxd.github.io/search-JS-library/	Easiest and fastest method
Hydrogen	API-based	Custom code + unbxd.helper.js	React SSR using Remix
Hydrogen React (Next.js)	API-based	Custom code + unbxd.helper.js	React SSR using Next.js
Custom Storefront API	API-based	Any framework	Requires solutioning based on customer setup

Make a duplicate of an existing Shopify theme.
On the Shopify webpage, navigate to the Online Store > Themes section of the admin panel of your store and click Actions > Edit code.
Update the theme.liquid template. Add the below snippet immediately after the start of the body tag.

<script src="https://libraries.unbxdapi.com/sdk-clients/{sitekey}/ua/ua.js"></script> 

<script
(function() {
    const sdkScript = document.createElement("script");
  
// Pick the value for LATEST_VERSION from https://unbxd.github.io/search-JS-library/
  
sdkScript.src = `https://libraries.unbxdapi.com/search-sdk/LATEST_VERSION/vanilla
  
Search.min.js`;
  
sdkScript.type = "text/javascript";

document.body.appendChild(sdkScript);


    sdkScript.addEventListener("load", () => {
        window.unbxdSearch = new window.UnbxdSearch({
            siteKey: "YOUR_SITE_KEY", // Available in Unbxd Console
            apiKey: "YOUR_API_KEY", // Available in Unbxd Console
            searchTrigger: "click",
            debugMode: false,
            // Add correct JS configuration by referring to https://unbxd.github.io/search-JS-library/
        });

    });
})();
</script>

Update the below script to integrate Autosuggest.

<script>
(function() {
    // Configuration - UPDATE THESE VALUES
    const SITE_KEY = "YOUR_SITE_KEY";
    const API_KEY = "YOUR_API_KEY";
    const INPUT_SELECTOR = ".site-header-form-search-desktop input";
    
    // Load Unbxd Autosuggest library
    const script = document.createElement('script');
    script.src = 'https://libraries.unbxdapi.com/autosuggest/VERSION/unbxdAutosuggest.js';
    script.onload = function() {
        // Initialize autosuggest
        unbxdAutoSuggestFunction(jQuery, Handlebars);
        
        jQuery(INPUT_SELECTOR).unbxdautocomplete({
            siteName: SITE_KEY,
            APIKey: API_KEY,
            minChars: 0,
            platform: "io",
            searchEndPoint: "https://search.unbxd.io",
            template: window.innerWidth < 1024 ? '1column' : '2column',
            mainTpl: ["keywordSuggestions", "popularProducts"],
            keywordSuggestions: { count: 6 },
            popularProducts: { count: 5, price: true, currency: "$" },
            onItemSelect: function(data) {
                if (data.type === 'POPULAR_PRODUCTS' && data.productUrl) {
                    window.location.href = data.productUrl;
                    return false;
                }
                window.location = window.location.origin + "/search?search=" + encodeURIComponent(data.value);
            }
        });
        
        console.log('Unbxd Autosuggest initialized successfully');
    };
    
    script.onerror = function() {
        console.error('Failed to load Unbxd Autosuggest library');
    };
    
    document.head.appendChild(script);
})();
</script>