JavaScript API

The JavaScript API is exposed as window.Convermax on pages where the Convermax widget (search.min.js) is installed, that is, on client storefronts. It is not available outside the widget: for standalone apps, use the Convermax npm package or call the Search API directly.

Every method below is called on window.Convermax.

Vehicle

A vehicle is an object of fitment fields, for example { Year: '2015', Make: 'Ford', Model: 'F-150' }. The garage is the list of vehicles available on the current page; one of them can be selected.

The selected vehicle and garage are essential browser data: on Shopify they are saved and restored regardless of the Preferences consent category, and logged-in customers load and update their profile garage independently of consent.

All field values must be strings. Fields whose names start with __, such as __productIds, store custom data with the vehicle. They do not affect vehicle matching, search, or labels. When customer-garage sync is configured and the shopper is identified, these fields are also included in customer-garage updates.

On stores with fitment search enabled, signed-in shoppers download the account garage on each page load. Browser vehicles are merged at login, with matching account records taking precedence. The import remains pending until an account read contains the browser vehicles. Later page loads use the account list and retain the currently selected vehicle if it is missing from that list. If no stored account garage is returned, browser vehicles are retained; a stored empty list clears the garage except for the current selection after synchronization.

When you update an existing vehicle through the API, include every custom field you want to keep. Omitted __* fields are removed from the replaced record. Use getVehicle(true) or getVehicleList(true) to read the complete record before updating it.

getVehicle(includeInternalFields?)

Returns the selected vehicle’s fitment fields. Pass true to return all stored fields, including custom __* fields and fitment values marked __ignored or __inexact. These markers mean that a fitment field was skipped or still needs a value.

window.Convermax.getVehicle();

Result

{
  "Year": "2015",
  "Make": "Ford",
  "Model": "F-150"
}

window.Convermax.getVehicle(true);

Result with stored custom data

{
  "Year": "2015",
  "Make": "Ford",
  "Model": "F-150",
  "__productIds": "123,456"
}

setVehicle(vehicle, sendIsolatedRequest?)

Adds a vehicle to the garage and selects it. A matching vehicle is updated with the supplied record. Omitted __* fields are removed.

setVehicle can keep more detailed fitment fields from a saved vehicle. For example, if a saved Ford F-150 has Engine: 'V6', setting the same Year, Make, and Model keeps that Engine value. Custom fields still come from the supplied record.

Selecting a saved vehicle through a widget keeps its complete record.

• sendIsolatedRequest (default true) - when false, skips background fitment-widget requests. Vehicle selection and normal search behavior stay active.

window.Convermax.setVehicle({ Year: '2015', Make: 'Ford', Model: 'F-150' });
window.Convermax.setVehicle({ Year: '2015', Make: 'Ford', Model: 'F-150', __productIds: '123,456' }, false);

discardVehicle()

Clears the selected vehicle. If the vehicle is in the garage, it stays in the list but is no longer selected.

window.Convermax.discardVehicle();

isVehicleSelected()

Checks whether a vehicle is selected.

window.Convermax.isVehicleSelected();

Result

true

getVehicleString()

Returns the selected vehicle as a string, or an empty string if no vehicle is selected.

window.Convermax.getVehicleString();

Result

2024 Ford F-150

getVehicleSearchParams()

Returns the current vehicle selection as slash-delimited field/value pairs, or an empty string if there is no selection. Partial selections are supported. Values are not URL-encoded; use getVehicleUrl(url) to prepare navigation links.

window.Convermax.getVehicleSearchParams();

Result

Year/2020/Make/Ford/Model/F-150

getVehicleUrl(url)

Adds the current page vehicle to a same-origin URL and applies the platform route. Preserves existing parameters, fragments, and any vehicle already specified in the destination. External URLs remain unchanged.

window.Convermax.getVehicleUrl('/products/winch?variant=123#details');

getVehicleRequestParams()

Returns the selected vehicle as Search API facet parameters. If no vehicle is selected, returns an empty string without a warning. Use getVehicleUrl(url) to add the vehicle to navigation links.

window.Convermax.getVehicleRequestParams();

Result

facet.0.field=Year&facet.0.selection=2020&facet.1.field=Make&facet.1.selection=Ford&facet.2.field=Model&facet.2.selection=F-150

Example URL

https://example-store.myconvermax.com/search.json?pagesize=30&facet.0.field=Year&facet.0.selection=2020&facet.1.field=Make&facet.1.selection=Ford&facet.2.field=Model&facet.2.selection=F-150

Garage

getVehicleList(includeInternalFields?)

Returns the vehicles in the garage. Pass true to include all stored fields for each vehicle, as with getVehicle(true).

window.Convermax.getVehicleList();

Result

[
  { "Year": "2015", "Make": "Ford", "Model": "F-150" },
  { "Year": "2016", "Make": "Ford", "Model": "F-150" }
]

window.Convermax.getVehicleList(true);

Result with stored custom data

[
  { "Year": "2015", "Make": "Ford", "Model": "F-150", "__productIds": "123,456" },
  { "Year": "2016", "Make": "Ford", "Model": "F-150", "__productIds": "789" }
]

addVehicle(vehicle)

Adds a vehicle to the garage without selecting it. A matching vehicle is replaced with the supplied record, including removal of omitted __* fields. A match has the same fitment fields and values, including optional fields such as Engine; __* fields are ignored.

window.Convermax.addVehicle({ Year: '2015', Make: 'Ford', Model: 'F-150' });

To update custom data for the selected vehicle, read its complete record and submit it again. This keeps the other custom fields and the current selection:

if (window.Convermax.isVehicleSelected()) {
  const vehicle = window.Convermax.getVehicle(true);
  window.Convermax.addVehicle({ ...vehicle, __productIds: '123,456' });
}

removeVehicle(vehicle)

Removes a vehicle from the garage.

window.Convermax.removeVehicle({ Year: '2015', Make: 'Ford', Model: 'F-150' });

addVehicleList(vehicles)

Adds new vehicles and replaces matches without changing the selection. Matching follows the same rules as addVehicle. Omitted __* fields are removed from replaced records. Other garage vehicles remain unchanged.

window.Convermax.addVehicleList([
  { Year: '2015', Make: 'Ford', Model: 'F-150' },
  { Year: '2016', Make: 'Ford', Model: 'F-150' },
]);

setVehicleList(vehicles)

Replaces the garage with the given list. The last vehicle in the list is selected.

window.Convermax.setVehicleList([
  { Year: '2015', Make: 'Ford', Model: 'F-150' },
  { Year: '2016', Make: 'Ford', Model: 'F-150' },
]);

Events

Assign a function to subscribe.

onVehicleSelected

Called when a vehicle is selected, with that vehicle.

window.Convermax.onVehicleSelected = (vehicle) => console.log(vehicle);

Argument

{
  "Year": "2015",
  "Make": "Ford",
  "Model": "F-150"
}

onVehicleRemoved

Called when a vehicle is removed from the garage, with the remaining vehicle list.

window.Convermax.onVehicleRemoved = (vehicleList) => console.log(vehicleList);

Argument

[{ "Year": "2016", "Make": "Ford", "Model": "F-150" }]

Fitment

verifyFitmentAsync(productId?, vehicle?)

Checks whether a product fits a vehicle. Both arguments are optional: by default it checks the product of the current product page against the selected vehicle. You can pass just a vehicle, just a product ID, or both.

await window.Convermax.verifyFitmentAsync();
await window.Convermax.verifyFitmentAsync({ Year: '2015', Make: 'Ford', Model: 'F-150' });
await window.Convermax.verifyFitmentAsync('3051');
await window.Convermax.verifyFitmentAsync('3051', { Year: '2015', Make: 'Ford', Model: 'F-150' });

Possible results

yes
no
aggressive
unknown
universal
nonVehicleProducts

updateVerifyFitmentWidget(productId, variantId?)

Re-checks the Verify Fitment widget for another product or variant against the selected vehicle, for example after the shopper switches variants. Throws if productId is empty.

window.Convermax.updateVerifyFitmentWidget(123412341234);
window.Convermax.updateVerifyFitmentWidget(123412341234, 456745674567);

updateFitmentTableWidget(productId, variantId?)

Reloads the Fitment Table widget with the fitments of another product or variant. Returns a Promise; throws if productId is empty.

await window.Convermax.updateFitmentTableWidget('123412341234');
await window.Convermax.updateFitmentTableWidget('123412341234', '456745674567');

Search

getSearchRequest()

Returns the current search request.

window.Convermax.getSearchRequest();

Result

{
  "selection": [],
  "action": "set",
  "catalog": "",
  "filterQuery": "",
  "maxCountByField": {},
  "pageNumber": 0,
  "pageSize": 36,
  "query": "exhaust",
  "sort": "relevance"
}

getSearchResponse()

Returns the current search response. Besides the fields below, it includes the facets and items collections.

window.Convermax.getSearchResponse();

Result

{
  "error": null,
  "messages": [],
  "originalQuery": "exhaust",
  "query": "exhaust",
  "state": "normal",
  "totalHits": 39
}

getSearchSort()

Returns the current sort value.

window.Convermax.getSearchSort();

Result

relevance

setSearchSort(sort)

Sets the sort. Use a field name for ascending order, or field:desc for descending order.

window.Convermax.setSearchSort('price');
window.Convermax.setSearchSort('price:desc');

Default sort options

// Shopify
[
  'relevance',
  'title',
  'title:desc',
  'collection_sort',
  'price',
  'price:desc',
  'published_at',
  'published_at:desc',
];

// BigCommerce
['relevance', 'name', 'name:desc', 'price', 'price:desc', 'date_created', 'date_created:desc'];

discardSearchFields(fields)

Clears only the given search fields. Other selections stay unchanged.

window.Convermax.discardSearchFields(['category', 'price', 'collections']);

clearCurrentRequest(doNotDiscardVehicle?)

Clears the current filters and query. Pass true to keep the selected vehicle.

window.Convermax.clearCurrentRequest();
window.Convermax.clearCurrentRequest(true);

clearCurrentQuery()

Clears the autocomplete query, search query, and filter query, where set.

window.Convermax.clearCurrentQuery();

Related items

getRelatedItemsAsync(id, count, sort?)

Returns a Promise with related items for a product. When a vehicle is selected, only items that fit it are returned. sort uses the same format as setSearchSort().

const items = await window.Convermax.getRelatedItemsAsync('112233445566', 2, 'price');

Result

[
  {
    "id": "123456789",
    "title": "ARB Example Item",
    "price": 0.95,
    "url": "/products/arb-example-item",
    "vendor": "ARB"
  },
  {
    "id": "1011121314",
    "title": "Hella Example Item",
    "price": 5.58,
    "url": "/products/hella-example-item",
    "vendor": "Hella"
  }
]

Dialogs

openDialog(dialogName, metadata?)

Opens a dialog. metadata passes dialog-specific options.

Generic bundles include VehicleWidgetDialog, SearchBoxDialog, FacetDialog, SimpleColorPaletteDialog, and ColorExtractorDialog; stores can register their own.

window.Convermax.openDialog('VehicleWidgetDialog');
window.Convermax.openDialog('FacetDialog');
window.Convermax.openDialog('VehicleWidgetDialog', { withCurrentVehicle: true });

Script version

version

Returns the script build timestamp and Git commit hash.

window.Convermax.version;

Result

Thu, 12 Mar 2026 12:19:40 GMT (abc1234:Thu, 12 Mar 2026 11:56:52 GMT)