Configure Algolia for BigCommerce

Configure indexes for the Algolia BigCommerce integration.

Each index in the Algolia for BigCommerce app is a combination of:

• An Algolia index name (must be unique)
• A BigCommerce storefront channel (each store can have multiple channels)
• A set of BigCommerce product data with currencies

You already set up an index during installation. You can edit it on its detail page, or add and delete others from the Overview page. The number of indexes you can create is limited by the number of indices available on your Algolia plan.

To open an index, go to Overview and select it in the Your indexes list.

Saving changes to an index’s settings doesn’t update existing records. After changing custom fields, metafields, or attributes to exclude, trigger a full reindex to apply the changes to your index.

Trigger a full reindex

After installing, you need to trigger a full reindex at least once to retrieve your products from BigCommerce. The setup wizard does this when you select Start indexing. You should also reindex after changing an index’s data mapping.

A full reindex builds records in a temporary index and replaces the existing index in a single operation:

• Search isn’t interrupted. Users keep searching the existing index until the new one is ready.
• If the reindex fails, the existing index stays unchanged.
• Real-time updates received during the reindex are queued and applied after the reindex finishes.
• Index settings, rules, and synonyms are copied from the existing index.

Only one reindex can run at a time for each index.

To trigger a full reindex:

1. Go to Overview and select the index.

2. Select Reindex.

   

3. To check the reindexing progress, open the Activity tab. For more information, see Monitor BigCommerce indexing.

Indexing success threshold

The indexing success threshold is the minimum percentage of products that must import without errors for a reindex to succeed. You set it when creating an index and can change it later under Index settings on the index’s Settings tab.

• The threshold is measured in products, not records. With variant-level indexing, a product with many variants counts as one product.
• The default is 100%. At this threshold, one product import failure causes the reindex to fail.
• If a reindex fails, your existing index stays unchanged.
• If a reindex meets the threshold, it’s reported as successful, even if some products failed to import. To find products that failed, check the run’s events.

Data mapping

The Data mapping section on the index’s Settings tab controls which catalog fields get indexed: attributes to exclude, metafields, and custom fields.

Custom fields

To index custom fields:

1. Go to Overview and select the index.

2. In the Data mapping section, expand Custom fields.

3. Enter a comma-separated list of custom field names to index and select Save.

4. Trigger a full reindex to apply the change.

   

To use custom facets in your BigCommerce integration:

1. Add them as custom fields
2. Reindex your data.
3. Configure the filters to display them on your InstantSearch results page.

Custom fields are indexed as JSON-encoded strings, as defined by the BigCommerce API.

Troubleshooting

• If a custom field doesn’t appear, check that it’s included in your Algolia index under attributes for faceting.
• If you require a different data type, you can transform the data before indexing.

Metafields

Metafields let you index custom data attached to your BigCommerce products or variants so you can make it searchable, filterable, or display it in Algolia. Use metafields to store additional product information beyond the standard BigCommerce fields, such as technical specifications, custom labels, or other attributes.

Configure metafields

1. Go to Overview and select the index.

2. In the Data mapping section, expand Metafields.

3. Enter the key and namespace for each metafield you want to index, then select Add. You can add:

   • Product metafields (applies to the product as a whole)
   • Variant metafields (applies to specific product variants, such as size or color)

4. Trigger a full reindex to update your Algolia index with the new metafield data.

   

For example, if you have a product metafield with namespace specs and key material, enter those values to make the material information searchable and filterable in Algolia.

After reindexing, the selected metafields will be available in your Algolia index. You can use them for search, display, or as custom filters in InstantSearch.

Limitations

• Only the metafields you specify are indexed. Others are ignored.
• If you add or remove metafields, you must reindex for changes to take effect.
• Metafields must exist in BigCommerce and be populated for products or variants to appear in Algolia with those fields.
• Metafields are indexed as JSON-encoded strings, as defined by the BigCommerce API. If you need a different data type, use transformations to convert them before indexing.

Attributes to exclude

Attributes to exclude lets you prevent specific product attributes from being indexed in Algolia. This is useful if you want to reduce index size, avoid exposing sensitive data, or remove irrelevant fields from search and filtering.

Exclude attributes

1. Go to Overview and select the index.

2. In the Data mapping section, expand Attributes to exclude.

3. Enter a comma-separated list of attribute names you want to exclude from indexing (for example: cost_price,upc,weight) and select Save.

   

4. Trigger a full reindex to apply the change.

After saving and reindexing, the specified attributes will no longer be present in your Algolia index. They also won’t be searchable, filterable, or visible in search results.

Limitations

• Excluded attributes are removed from all products in the index.
• You must reindex for changes to take effect.
• You can’t exclude the objectID and _tags attributes. The integration uses them to manage records.
• The list must be comma-separated without spaces.
• Excluding required attributes may affect search relevance or display if those fields are used in your InstantSearch configuration.