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 the shopper has saved; one of them can be selected.

getVehicle()

Returns the selected vehicle.

window.Convermax.getVehicle();

Result

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

setVehicle(vehicle)

Adds a vehicle to the garage and selects it. If the vehicle is already in the garage, it is not added twice.

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

discardVehicle()

Clears the selected vehicle. If the vehicle is in the garage, it stays saved 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 selected vehicle as slash-delimited key/value pairs that can be appended to a search URL path.

window.Convermax.getVehicleSearchParams();

Result

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

Example URL

https://example-store.com/?Year/2020/Make/Ford/Model/F-150

getVehicleRequestParams()

Returns the selected vehicle as Search API facet parameters. If no vehicle is selected, returns an empty string.

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()

Returns the vehicles in the garage.

window.Convermax.getVehicleList();

Result

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

addVehicle(vehicle)

Adds a vehicle to the garage without selecting it.

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

removeVehicle(vehicle)

Removes a vehicle from the garage.

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

addVehicleList(vehicles)

Adds a list of vehicles to the garage. Vehicles already in the garage are skipped.

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 or not found.

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)