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. Install App and link to Unbxd account.
2. Set up Catalog Indexing
3. Integrate Search

1. Steps to Create Access Token for Shopify

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

then click Save.

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

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

7. 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 product and collection data on an Unbxd site. Refer to the table below for details on the attributes.

2.1 Product Information

The following product-level fields are fetched and mapped to Unbxd by default. No additional configuration is required.

2.2 Variant Information

Variant data is fetched alongside product data. All variant fields are prefixed with v_ in Unbxd. No additional configuration is required.

2.3 Metafields Support

Default Supported Metafield Types are below

All metafields are automatically indexed as new Unbxd fields, prefixed with meta_. The following datatypes are supported by default:

• 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

Additional Datatypes (Requires Configuration)

The following datatypes require special configuration to be extracted:

• file_reference
• metaobject_reference

Fields derived from these datatypes are stored in Unbxd with a datatype of link.

📘

Note

Fetching referenced data such as swatch images or hex codes from metaobject references requires additional configuration. Please contact the Netcore Unbxd support team to enable this.

2.4 Variant Metafields

Variant-level metafields are not fetched by default. This feature can be enabled through a simple transformer configuration with no additional parameters required. Configuration Required: Yes

2.5 Collections (Categories)

Shopify collections are synced and mapped to Unbxd category fields by default.

2.6 Collections as a Separate Content Type (Banners)

In addition to category mapping, Shopify collections are also synced as a separate content type in Unbxd. This enables use cases like banner display and collection-level merchandising.

Synced Fields

• id
• title
• handle
• updatedAt
• imageUrl
• imageAltText
• productsCount
• description
• seo_title
• seo_description

2.7 Price Processing

1. At the Product (Parent) Level The following computed price fields are available by default on each product:

• compareAtPrice = compare-at-price of variant with minimum price
• computed_discount = ceil((compareAtPrice - price) / compareAtPrice * 100)

2. Variant Level (Default fetch)

• computed_discount applied per variant using the same formula

2.8 Tag Processing

By default, the plugin splits Shopify tags using : as a delimiter and creates derived fields in Unbxd. All derived tag fields are prefixed with tags_. For example, a tag like color: red creates a field tags_color with value red.

• Delimiter is configurable: any character can be used
• Schema for derived fields can be modified from the Unbxd Admin Panel

Configuration is not required for this.

2.9 Availability Logic

Unbxd computes product availability based on variant-level data. Two custom fields are added automatically:

Custom Fields Added (Default behaviour).

• availableForSaleOfVariants True if any variant has availableForSale = True
• availability (final product availability) True only if: totalInventory > 0, and availableForSaleOfVariants = True

2.10 Multi-Store (Inventory) Support

This feature fetches inventory data for variants across multiple Shopify locations using the GraphQL API. It pulls inventory levels, quantities, and location-specific metafields per variant. Inventory is fetched using Shopify GraphQL: (Configurations is needed)

• Fetches inventory per variant across multiple locations
• Pulls inventory levels, quantities, and location metafields

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

2.11 Translations (Multi-Language Support)

Unbxd supports multi-language product data using Shopify's locale parameter. By default, the locale is set to en. To index product data in another language, the locale parameter for the relevant site key must be updated.

Requirements

• Language code (e.g., fr, de, es)
• Translated file name
• Shopify theme ID
• Field mapping configuration

📘

Note

Shopify does not translate all fields automatically via locale. The Field Translations feature supports manual mapping of translated values from Shopify locale JSON files.

Configuration is required for this.

2.12 Multi-Regional Pricing / Currencies

This feature supports fetching product prices for multiple regions and representing them in different currencies, based on Shopify Markets. Varying prices are maintained per region and indexed into Unbxd automatically. Enable this by adding a transformer configuration; no parameters are required. Configuration is required for this.

2.13 Newness Property

Based on a product's createdAt date, this feature automatically marks recent products and adds two fields to each product:

• newness = "New Arrivals"
• days_since_createdAt = number of days since product creation

Configuration: days_of_newness (default: 60 days)

Configuration is required for this

2.14 Special Character Filter

This feature automatically removes special characters from field values before indexing. It helps ensure clean, consistent data in Unbxd without manual preprocessing.

Configuration Options

• Characters to filter: provide a custom list, or use the default set
• Field names: specify which fields the filter should be applied to

Configuration is required for this

2.15 Blog and Article Information

Unbxd can index blog and article content from your Shopify store, enabling content-aware search experiences alongside product results.

• Blogs: All blog records are synced. Blog data is pulled using the Shopify REST API.
• Articles: The following fields are fetched for each article:
  • Article Fields
  • title
  • created_at
  • blog_id
  • author
  • updated_at
  • productUrl
  • handle
  • tags
  • admin_graphql_api_id
  • body_html Configuration is required for this

2.16 Pages Information

Unbxd can also index Shopify Pages, making static content discoverable through search.

• Synced Fields
• author
• created_at
• handle
• id
• published_at
• shop_id
• template_suffix
• title
• updated_at
• admin_graphql_api_id
• body_html

Configuration is required for this

2.17 Custom Fields and Business Logic

The plugin supports custom scripts for specialised use cases that fall outside the default feature set. This allows any customer-specific data transformation or business logic to be applied during indexing.

📘

Note

To request a custom script, raise a Jira ticket in the PLUG board. The Unbxd engineering team will review and implement the logic based on your requirements.

3. Synchronization & Indexing

Full Indexing

Full indexing fetches all products and collections from your Shopify store.

Product Data

• Uses Shopify Admin API + GraphQL (not Storefront API)
• Uses Shopify's bulkOperation feature — Shopify exports all matching results to a file, and the plugin downloads and processes it

Blog and Article Data

• Pulled using the Shopify REST API

📘

Note

Shopify allows only one bulk operation (full or delta) to run at a time. If a delta job is running, a full job will not execute, and vice versa. Schedule full and delta indexing intervals carefully to avoid overlap.

Delta Indexing

Delta indexing keeps your Unbxd catalog up-to-date by syncing only products that have changed since the last successful pull.

• Supported for Product data only
• Fetches products where updated_at > last_pulled_time
• Minimum supported interval: 15 minutes

❗️

Known Limitations

• Shopify allows only one bulk operation at a time — full and delta jobs must not overlap
• Approximate timing: ~130 seconds for 300 products / 3,000 variants
• Very frequent synchronization is not supported due to Shopify's constraints

📘

An API is available to set or update the delta indexing schedule. See the Shopify Plugin documentation for details.

Handling Full and Delta Job Conflicts

If full and delta indexing jobs are at risk of overlapping, you can configure separate Shopify access tokens for each job type

• Generate a second Shopify access token from your store's developer settings.
• Store the token in Viper DB with the following configuration: Key: delta_access_token , Value: <token>
• The plugin will then use separate tokens for full and delta indexing, allowing both to run without conflict.

4. 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:

1. Make a duplicate of an existing Shopify theme.
2. On the Shopify webpage, navigate to the Online Store > Themes section of the admin panel of your store and click Actions > Edit code.
3. 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>

Autosuggest Integration

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>

Browse Integration

To replace Shopify's native collection/browse pages with Unbxd-powered browse, refer to the Self-Serve FAQ documentation for step-by-step instructions on integrating browse Liquid files.

👍

Required Unbxd Liquid files must be added manually to your theme. Steps are documented in the Self-Serve FAQ.

Hydrogen and Headless Storefront Integration

For Hydrogen (Remix) or Hydrogen React (Next.js) storefronts, integration is API-based using custom code and the unbxd.helper.js utility. For fully custom storefront frameworks, solutioning is done based on your specific setup contact Unbxd Support to get started.