Keep Existing Links Working After Switching Search

When a store switches to Retail Cloud Connect, existing storefront links, saved collection URLs, and email campaigns may still use query-parameter names from a previous search provider. The search App Block can translate those old parameter names into the equivalent Retail Cloud Connect filter keys, so those links keep working.

When to Use This

• Migrating from another search provider whose URLs use different parameter names.
• Preserving saved collection links or campaign URLs that already circulate.

How It Works

Define key mappings before the search App Block bundle mounts:

window.Nimstrata = window.Nimstrata || {};
window.Nimstrata.search = window.Nimstrata.search || {};

window.Nimstrata.search.keyMappings = {
  resolution: 'attributes.resolution',
  stock: {
    key: 'availability',
    values: {
      0: 'OUT_OF_STOCK',
      1: 'IN_STOCK',
    },
  },
};

Common Shopify filter keys are mapped automatically. Storefront mappings override them.

Each object key is the old URL query parameter to accept. Each value is either a canonical filter field, such as attributes.resolution, or an object with a key, optional values, and optional keepOriginal. The values map converts old query-string values before applying the filter. With this example, ?stock=1 applies an availability filter of IN_STOCK.

The mapped key must resolve to a field the App Block already understands: a supported built-in facet such as brands, sizes, availability, price, or an attributes.* field. Unknown query parameters are ignored unless they appear in keyMappings or already match a supported field.

By default, generated search state uses canonical keys. Set keepOriginal: true when an integration also needs the old key. Shopper filter changes still write canonical keys to the browser URL.

Metaobject GIDs on mapped or attributes.* parameters are resolved to display text through the Storefront API before mapping. Explicit values mappings take priority, and unresolved GIDs remain unchanged.

Related Configuration

keyMappings is one of the manual window.Nimstrata storefront hooks; see Additional Properties for the full reference. For how normal filters are configured, see App Block Filters.