Algolia search engine

​

Introduction

​

Setup

ALGOLIA_APP_ID=your_app_id
ALGOLIA_API_KEY=your_admin_api_key

NEXT_PUBLIC_ALGOLIA_ID=your_app_id
NEXT_PUBLIC_ALGOLIA_SEARCH_KEY=your_search_only_api_key

​

Configuration

Important: The settings below are configured for the default Mercur storefront. If you’re using a custom storefront with different filtering requirements, you’ll need to adjust attributesForFaceting based on your specific filters. See the Custom Storefront Configuration section below.

​

Understanding attributesForFaceting

• Every attribute you filter by in your storefront → Must be declared in attributesForFaceting
• Without this declaration, Algolia will ignore the filter or return 0 results

// If your storefront uses this filter:
filters: "seller.handle:vendor-name AND supported_countries:pl"

// Algolia MUST have:
attributesForFaceting: [
  "filterOnly(seller.handle)",
  "filterOnly(supported_countries)"
]

​

Default Storefront Configuration

// Default storefront filters:
NOT seller:null AND 
NOT seller.store_status:SUSPENDED AND 
supported_countries:${locale} AND 
variants.prices.currency_code:${currency_code} AND 
variants.prices.amount > 0

• variants.condition - Product condition (e.g., new, used, refurbished)
• variants.color - Product color options
• variants.size - Product size options

Recommended Algolia Settings for Default Storefront

• attributesForFaceting - Required for filtering by category, seller, country, currency, etc.
• searchableAttributes - Product fields that are searchable
• Ranking and relevance settings
• Facet ordering (color, size, condition)

1. Via Algolia Dashboard (recommended):
   • Download the algolia-config.json file
   • In Algolia Dashboard, go to your product index
   • Select “Import configuration” from the “Manage index” dropdown
   • Upload the downloaded file
2. Via API:
   • Use the Algolia API to update index settings programmatically
   • See Algolia setSettings documentation

• attributesForFaceting - Enables filtering by:
  • categories.id - Filter products by category
  • seller.handle - Filter products by vendor/seller
  • seller.store_status - Filter out suspended sellers
  • seller.id - Filter by specific seller ID
  • supported_countries - Geographic filtering
  • variants.prices.currency_code - Currency-specific filtering
  • variants.color, variants.size, variants.condition - Product attributes
  • attribute_values.name and attribute_values.value - Custom attributes
• searchableAttributes - Defines which fields are searchable in text queries
• facetOrdering - Controls the order and display of facets in the storefront

• filterOnly(attr) - Attribute can only be used for filtering (more memory efficient)
• searchable(attr) - Attribute can be used for both filtering and text search

​

Custom Storefront Configuration

1. Identify Your Filters

• Product listing components
• Search components
• Category/collection pages

// Example: Finding filters in your code
const filters = `brand:${brand} AND color:${color} AND price_range:${range}`

2. Map Filters to attributesForFaceting

{
  "attributesForFaceting": [
    "filterOnly(brand)",      // For: brand:Nike
    "filterOnly(color)",       // For: color:red
    "filterOnly(price_range)"  // For: price_range:100-500
  ]
}

3. Choose the Right Prefix

• Use filterOnly() for attributes that only need filtering (most common, more efficient)
• Use searchable() for attributes that should also be searchable via text query

4. Update and Test

1. Update your Algolia index settings via dashboard or API
2. Re-sync your products if needed
3. Test filtering in your storefront to ensure it works

// Your custom storefront code:
const filters = `
  brand:${selectedBrand} AND 
  color:${selectedColor} AND 
  collection.id:${collectionId}
`

{
  "attributesForFaceting": [
    "filterOnly(brand)",
    "filterOnly(color)",
    "filterOnly(collection.id)"
  ]
}

​

Product Visibility Requirements

1. Product Status: Must be published
2. Seller Assignment: Product must have an assigned seller with status ACTIVE (not SUSPENDED)
3. Geographic Availability: Product’s supported_countries must include the target country code
4. Pricing: All variants must have prices in the appropriate currency with amount > 0
5. Inventory: Variants must have properly configured inventory locations with fulfillment sets for the target country

Note: If you’re using a custom storefront, your visibility requirements may differ based on your filtering logic.

​

Events

• algolia.products.changed
• algolia.products.deleted

• algolia.intermediate.fulfillment_set.changed
• algolia.intermediate.service_zone.changed
• algolia.intermediate.shipping_option.changed
• algolia.intermediate.stock_location.changed
• algolia.intermediate.inventory_item.changed

​

Troubleshooting

​

Products not showing on storefront

1. Check attributesForFaceting - Ensure all attributes used in your storefront filters are declared in attributesForFaceting
2. Verify filter values - Check that products have the values you’re filtering by (e.g., supported_countries contains the target country)
3. Review pricing - Ensure all variants have prices in the correct currency (if you filter by currency)
4. Confirm seller status - If filtering by seller status, verify it’s ACTIVE and not SUSPENDED
5. Check product status - Ensure product status is published
6. Inspect Algolia Dashboard - View your index in Algolia Dashboard to see actual data and test filters

​

Common Issues

1. Check your storefront code to see what filters are applied
2. Compare with your Algolia attributesForFaceting settings
3. Add any missing attributes to the Algolia configuration
4. Re-sync products if needed

• Verify the attribute exists in your product data in Algolia
• Check that the attribute is declared in attributesForFaceting
• Use filterOnly() prefix for filtering-only attributes
• Use searchable() prefix if you also need to search by this attribute

• New filters require corresponding attributesForFaceting entries
• Update Algolia index settings first
• Then add the filter to your storefront code
• Products without the filtered attribute value will be excluded (this is expected)