> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Algolia Collections

> Show Algolia Collections on your Salesforce B2C Commerce storefront and index the data they need.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

Collections are curated product listings you build in Algolia instead of in Business Manager.
Algolia adds a `_collections` facet attribute to matching product records as they pass through the ingestion pipeline.
The storefront filters results by values of that attribute.

This page covers what the Salesforce B2C Commerce cartridge needs to index that attribute, and what it renders from it.
To create, curate, and delete collections,
see [Collections](/doc/guides/solutions/ecommerce/browse/tutorials/collections).

<Callout icon="credit-card" color="#c084fc">
  This feature isn't available on every plan.
  Refer to your [pricing plan](https://www.algolia.com/pricing) to see if it's included.
</Callout>

## Before you begin

To use Collections with the Salesforce B2C Commerce cartridge, you need the following:

* Cartridge version **26.6.0** or later.
* [Ingestion API indexing](/doc/integration/salesforce-commerce-cloud-b2c/guides/ingestion-api) enabled in Business Manager.
* Ensure that each product index has a push task. Creating a collection provisions the task for its index, so you don't need a separate Push to Algolia connector for that index. The cartridge already sends product records through the Ingestion API push endpoint, so you don't need to modify its indexing code.
* The built-in storefront components require Storefront Reference Architecture (SFRA). SiteGenesis storefronts require a custom implementation.

<Note>
  Collections apply to product indices.
  `AlgoliaCategoryIndex_v2` and `AlgoliaContentIndex_v2` always send their writes through the Search API, so a collection on a categories or contents index loses its data the next time those jobs run.
</Note>

## Name collections for the storefront

A collection's name is what users see, what appears in your storefront URLs, and what the storefront filters on, so choose it with the same care as a category ID.

Don't use `>` in the name.
The storefront can read it as a level separator, which leaves the collection out of the refinement list and stops its URL from filtering.

Each locale has its own collections, because the cartridge maintains one product index per locale.
Create the collection once per locale index, and name each one in that locale's language.
Storefront URLs are per locale too, so your UK link carries the English name and your French link carries the French one.
Use the dashboard's **Copy to another index** action to replicate a collection across locale indices.

## Show collections on your storefront

The SFRA cartridge adds a **Collections** refinement to the search and category pages, and a collection listing page you can link to.
The refinement lists the collections on the index, and selecting one narrows the product grid.

The refinement appears on its own once an index has collections, and it renders nothing on an index that has none.
No site preference controls it.

Users can select one collection at a time.
Selecting another replaces the current selection because the storefront uses a [`menu`](/doc/api-reference/widgets/menu/js) widget which allows only one facet value.

Selecting a collection puts it in the URL:

```
https://www.example.com/s/SITE_ID/search?collection=Summer%20Sale
```

Users can sort the collection's products and apply additional refinements.

## Link to a collection page

Open a collection URL without a search term or category to show that collection's listing page.
It displays the collection name and products,
without a list of other collections or the products and articles tabs.
Link to the page from your site navigation, a content asset, or a campaign.

The page's canonical URL points at the collection.
A collection selected next to a search term or a category keeps the canonical URL of the page it refines.
With [**Enable SSR**](/doc/integration/salesforce-commerce-cloud-b2c/guides/ssr-caching) turned on, search engine crawlers receive the collection's products in the initial HTML, just as they do on category pages.

If the collection doesn't return any products, the storefront displays the usual no-results message.
The banner remains visible but it doesn't show the collection name.

The page is a variant of the search route, so it inherits your storefront's caching and page layout. The feature doesn't add a new controller and no metadata import is needed to use it.
Treat it as a starting point: override `searchResultsNoDecorator.isml` to change the presentation, and keep the `collection` parameter and the widget wiring so the filtering and the URL keep working.

<Warning>
  The heading displays the `collection` parameter from the URL,
  which is user input rather than merchant content.
  The cartridge template escapes it, so it renders as text.
  If you replace the presentation, escape it in your version too, and don't pass the value into markup that expects trusted content.
</Warning>

To serve the page from a path such as `/collections/summer-sale`, map that path to `Search-Show` with the `collection` parameter in Business Manager.
The cartridge doesn't ship a mapping, so the URL form stays yours to choose.

### Set the page title and description

The collection page uses the site's default title and meta description,
because the cartridge doesn't set page metadata on its search, category, or collection pages.
To set collection-specific values, extend `Search-Show` in your own cartridge.

## Migrate from Search API indexing

If you index with the Search API, your <Records /> don't carry `_collections` yet.
To switch:

1. Follow [Index with the Ingestion API](/doc/integration/salesforce-commerce-cloud-b2c/guides/ingestion-api).
2. Run `AlgoliaProductIndex_v2` in `fullCatalogReindex` mode so every product record passes through the pipeline.

Delta runs alone don't achieve this, because they cover only changed products.

## Retire a collection

The storefront URL carries the collection's display name, not a stable ID.
Renaming or deleting a collection breaks links that use its display name.
An old link still loads the page, but the banner doesn't show a collection name and the page shows a no-results message.

Before you delete or rename a collection, remove links pointing at it, as [Delete a collection](/doc/guides/solutions/ecommerce/browse/tutorials/collections#delete-a-collection) also advises.

If you permanently retire a collection,
configure a permanent server-side redirect from its old URL to a relevant replacement collection or category.
This also handles links in campaigns that you can't update.
Use an HTTP 301 or 308 redirect to direct users to the replacement and signal the preferred URL to search engines.

## Collection limitations

Keep these limitations in mind when planning collections for your storefront.

### Collections don't have a draft state

A collection can appear in the storefront refinement once its membership data is available in the product index.
Create campaign collections only when you're ready for users to see them.

### Review handpicked collections after changing the record model

Algolia identifies manually selected products by their object IDs.
Changing the [record model](/doc/integration/salesforce-commerce-cloud-b2c/indexing/product-indexing/indexing-attributes) can change those IDs.
If a selected ID no longer exists in the index, it no longer identifies an indexed product.
After changing the model and reindexing, review your handpicked collections and select the affected products again.

## Troubleshoot collections

For collection status, conditional collections that don't pick up products, and the "`_collections` isn't a facet" error, see [Troubleshoot problems](/doc/guides/solutions/ecommerce/browse/tutorials/collections#troubleshoot-problems).

### The refinement doesn't appear

Confirm the collection exists on the index the storefront queries.
Index names follow `<HOSTNAME>__<SITE_ID>__products__<LOCALE>` unless you set **Index Prefix**.

### A collection is missing from the refinement or its page shows unrelated products

Check whether its name contains `>`.
See [Name collections for the storefront](#name-collections-for-the-storefront).
Collections beyond the hundredth are also out of reach from the refinement list.

### The collection page shows the search page instead of the collection heading

The page renders when the URL carries `collection` and neither `q` nor `cgid`.
With a search term or a category in the URL, the collection applies as a refinement instead.
That's intentional.

### The collection page banner is empty

The storefront leaves the collection name out when the collection doesn't return any products.
This happens when you renamed or deleted the collection, or when the URL carries other refinements that don't match anything.

### The collection is empty on the storefront but not in the dashboard

Check the latest product indexing [job report](/doc/integration/salesforce-commerce-cloud-b2c/troubleshooting/monitoring) under **Merchant Tools > Algolia > Algolia**.
If expected records are missing or outdated in the index queried by the storefront,
also inspect the corresponding run under **Data sources > Connector Debugger** in the Algolia dashboard.
A successful cartridge job doesn't rule out errors during asynchronous ingestion.

## See also

* [Frontend (UI/UX)](/doc/integration/salesforce-commerce-cloud-b2c/building-the-search-ui/front-end)