Quick Start - Build a Badge and Install on Your Website

1. Select Style


2. Select Minimum Rating to display


px Enter a range from 40px to 200px

4. Install the generated code to the right →

Advanced Options

900 x 60


Copy and paste this HTML code for every used vehicle in the place where you'd like to display the badge. Substitute the correct VIN and Price accordingly.

<span data-cg-vin="1GNDT13W81K248136" data-cg-price="12300"></span>

Javascript code

Copy and paste this code ONLY Once before the closing body tag.

  var CarGurus = window.CarGurus || {}; window.CarGurus = CarGurus;
  CarGurus.DealRatingBadge = window.CarGurus.DealRatingBadge || {};

(function() {
    var script = document.createElement('script');
    script.src = "https://static.cargurus.com/js/api/en_CA/1.0/dealratingbadge.js";
    script.async = true;
    var entry = document.getElementsByTagName('script')[0];
    entry.parentNode.insertBefore(script, entry);

Need Help?

Refer to the Troubleshooting section, or contact us at dealerhost_support@cargurus.com


1. How do I debug?

You can turn the debug flag on, and look in the browser developer tools to see if there any messages or errors being thrown. To turn the debug flag on, update this property in the javascript CarGurus.DealRatingBadge.options.debug = true;

Any console messages from our script will start with the following text: CarGurus.DealRatingBadge.

2. Badges aren't showing up

By default, badges will show for used vehicles that fetch a Good Deal or better. You can change the default by updating the CarGurus.DealRatingBadge.options.minRating setting. The script will then fetch badges for deals that are equal or better than the minRating value.

Possible values for the minRating setting are GREAT_PRICE, GOOD_PRICE, and FAIR_PRICE. Vehicles that do not meet the minimum Deal Rating will not have a badge shown.

Other things to check:

  • Make sure there are no Javascript errors in the browser developer tools.
  • Make sure the span tags are valid HTML, contain a valid VIN and Price in the corresponding data-cg attributes, and are not hidden in the DOM. Here's an example:
        <span data-cg-vin="1GNDT13W81K248136" data-cg-price="12300"></span>
  • Make sure the script tag appears once on the page, at the bottom of the page before the end </body> tag.
  • Make sure our API is being requested by checking the network tab in the browser developer tools, and look for a request to dealRatingRequest.action

3. Can't get the badge to be the right size

For STYLE1 or STYLE2, you have the ability to size the badge via the CarGurus.DealRatingBadge.options.defaultHeight property. The badge will resize proportionally to whichever height you set it at.

BANNER1, BANNER2, BANNER3, BANNER4, BANNER5 are fixed size and should only be used where appropriate.

4. How do I change the look of the badge?

Our badge container has a CSS class of cg-dealrating-badge.

STYLE1 and STYLE2 are transparent images, and you can add a background color, padding, and other CSS properties to the container.

Still have questions, contact dealerhost_support@cargurus.com

Detailed Instructions

1. Install the Javascript SDK

Copy and paste the following code at the end of your HTML page, right before the </body> tag

  CarGurus = window.CarGurus || { DealRatingBadge: { } };
(function() {
    var script = document.createElement('script');
    script.src = "https://static.cargurus.com/js/api/en_CA/1.0/dealratingbadge.js";
    script.async = true;
    var entry = document.getElementsByTagName('script')[0];
    entry.parentNode.insertBefore(script, entry);

2. Define placeholders on your page where the badge should appear

The CarGurus Deal Ratings Badge will traverse your document and replace any <span> tag with the data-cg-vin and data-cg-price attributes with the corresponding Badge if one exists.

<span data-cg-vin="1GNDT13W81K248136"

The attributes in bold are required.

The data-cg-badge-style attribute is optional, and when it exists, specifies the Badge style for the vehicle. If not specified, will use the CarGurus.DealRatingBadge.options.style mentioned below.

The data-cg-height, when it exists, specifies the height of the badge in pixels.

We recommend setting a smaller height for the listing results page, and a larger height for vehicle detail pages.

3. Verify the Badge is working correctly

After installing the code on your website, you should be able to see CarGurus Deal Ratings Badge show up on your pages. It looks something like this:

CarGurus Badge Example

4. Advanced usage

The CarGurus Deal Ratings Badge automatically loads and fetches the deal ratings after the page has loaded, and continues to fetch any new ratings if the vehicles on the page change at any point. If for any reason, you would like control over the fetch process, you can disable the live updating via the options hash or by calling the following API function:


Then to manually fetch rating badges, you can use the following API function:


To enable the live updates again, you can call

5. Customizing the widget

You can set options globally or pass an options object to the run function. To set options globally, declare the following variable with at least one option key set:

CarGurus.DealRatingBadge.options = { minRating: "FAIR_PRICE", style: "STYLE2" };

To pass a custom options object to the run function, and have it apply just for that run instance, pass it as a parameter to the function.

CarGurus.DealRatingBadge.run({ minRating: "FAIR_PRICE", style: "STYLE2" });

If no parameter is passed, the global options object will take precedence if specified.

All possible options are listed below

Option key Type Default value Description
style string STYLE1 Default badge style to use if data-cg-badge-style is not specified for a span.

The following styles are supported:

  • STYLE1 - default height of 40px
  • STYLE2 - default height of 60px
  • BANNER1 - 900 x 60 pixels fixed size
  • BANNER2 - 900 x 42 pixels fixed size
  • BANNER3 - 748 x 42 pixels fixed size
  • BANNER4 - 550 x 42 pixels fixed size
  • BANNER5 - 374 x 42 pixels fixed size
Refer to the Badge Styles panel in the top right of this page
showContactForm boolean true When set to true will show a contact form in the Vehicle Detail Page so the consumer can submit their information to the dealer
minRating string GOOD_PRICE Determines the minimum deal rating to display. Can be one of

defaultHeight integer 40 | 60 depends on the style Height in pixels that the Badge should have, if the span tag does not contain a data-cg-height property. This property is ignored for the BANNER1, BANNER2, BANNER3, BANNER4 or BANNER5 styles.
live boolean true When set to true, enables live updates of pages anytime new vehicles are added to the page without a page refresh
liveIntervalMS integer 500 Refresh interval time in milliseconds if the option live is set to true
debug boolean false When set to true, allows for client side console debug logging. This should not be set to true in production.
Badge Styles


Need Help?