Product Page Widget - JsRates Documentation

The JsRates product page widget allows customers to view shipping rates before adding a product to their cart. Available as a Shopify theme app block, it uses your JsRates shipping rules to calculate rates for the selected product variant, quantity, and delivery address.

Customers can compare shipping prices, view delivery dates and rate descriptions, and update their destination directly on the product page. You can configure the widget's appearance and display options through the Shopify theme editor.

Requirements

Before adding the widget, make sure you have:

JsRates installed: See JsRates API for details about API access and configuration.
Working shipping rules: Configure and test your shipping rate code in JsRates. The widget displays rates returned by your code.
A compatible Shopify theme: Requires a theme 2.0 (Online Store 2.0) compatible theme.
Your JsRates API key: Find it on the JsRates Settings page, under JsRates API.
Trusted domains configured: Add your storefront's custom domain under JsRates API on the Settings page. Any other domains used to access the widget must also be allowed.
A product that requires shipping: The widget is hidden when the selected variant is unavailable or does not require shipping.

The widget requests rates through the JsRates API. Enabling JsRates at checkout is a separate step. To display JsRates shipping rates at checkout, follow the checkout activation instructions.

In your Shopify admin, open Online Store → Themes and open the theme editor for the theme you want to update.
Select the Products template where you want the widget to appear.
In a product section that supports app blocks, click Add block and select Product Page Widget from JsRates under Apps.
Position the block where customers should see shipping information, such as near the product price or purchase buttons.
Open the block settings and paste your API key into JsRates API key.
Configure the address fields, rate display, and appearance to suit your store.
Click Save and test the widget on a product page.

The widget appears on products assigned to that template. If your store uses multiple product templates, add the block to each template where you want shipping rates displayed.

Calculating Shipping Rates

When a customer opens a product page, the widget requests rates using the selected variant and delivery destination. The request includes product details such as price, weight, SKU, vendor, product and variant IDs, and whether the item requires shipping. The store address is supplied as the shipping origin.

The widget updates rates when it detects changes to the selected variant or quantity. Customers can click the delivery address summary, edit their destination, and select Update address to calculate rates again.

For logged-in customers, the request also includes their customer ID and tags, allowing your shipping rules to use this information.

Choosing the Delivery Address

The widget uses the following order to determine the destination:

Previously saved destination: An address saved by the widget in the customer's browser takes priority.
Customer's default address: If no destination is saved, the widget uses the logged-in customer's default Shopify address when it contains a postcode or ZIP code.
Automatic location detection: Otherwise, the widget asks JsRates to detect the customer's location.

Your configured default address provides a fallback when location detection is unavailable or the detected country is not supported. Customers can change the destination manually using the address fields you make visible.

The country selector normally uses the countries available in the current Shopify market. If Shopify returns no market country list, the widget falls back to Shopify's country list.

Automatically detected locations may be incomplete or inaccurate. Customers should check the displayed destination and update it when necessary. The widget remembers the destination in the same browser for future visits.

Including Cart Items

Include cart items is enabled by default. With this option enabled, rates are calculated for the items already in the cart plus the product and quantity currently selected on the product page.

If the selected variant is already in the cart, the widget adds the product page quantity to its existing cart quantity for the estimate. For example, two units in the cart plus one selected on the product page are calculated as three units. Calculating rates does not add the product to the cart.

Disable Include cart items to calculate shipping for the product page selection alone. If the widget cannot retrieve the cart, it falls back to the product page selection.

Configuring Address Fields

Under Address fields, you can configure:

Address prefix text: The text before the destination summary. The default is Delivering to.
Show country: Allows customers to select a destination country. Enabled by default.
Show state / province: Displays the state or province selector for countries with subdivisions. Enabled by default.
Show city: Allows customers to enter a city. Disabled by default.
Show postcode / ZIP: Allows customers to enter a postcode or ZIP code. Enabled by default. Postcodes are required when Shopify's country information indicates they are needed.
State / province required: Requires a selection for countries with states or provinces. Disabled by default.
City required: Requires a city before the address can be submitted. Disabled by default.

Keep required fields visible so customers can complete them. Also show any fields that your shipping rules or courier integrations need, even if you do not mark them as required.

Setting a Default Address

Under Default address, optionally enter:

Country code: A two-letter ISO country code, such as AU or US. Leave blank to use the current market country.
State / province code: A code such as NSW, VIC, or CA.
City: Your fallback destination city.
Postcode / ZIP: Your fallback destination postcode.

Use a consistent set of address values for the same destination. Defaults do not override a customer's saved destination or default Shopify address.

Configuring the Rate Display

Under Rate display, you can configure:

Show delivery dates: Displays a delivery date or date range when your shipping rules return delivery dates. Enabled by default.
Show rate description: Displays descriptions returned with your rates. Enabled by default.
Maximum rates shown: Sets the number of rates initially displayed, from 1 to 10. The default is 2. Customers can reveal additional rates using the show-more button.
Sort order: Choose Default (API order), Price: low to high, Price: high to low, or Delivery: soonest first. The default is Delivery: soonest first; rates without delivery dates appear after dated rates.
Badge: best price: Highlights the lowest-priced returned rate. Enabled by default.
Badge: fastest delivery: Highlights the earliest delivery date among rates that include dates. Enabled by default.

Rates with a zero price are displayed as Free. Delivery dates and descriptions must be supplied by your shipping rate code; turning on their display does not generate them. See Defining Delivery Dates for examples.

In the current widget, setting Maximum rates shown to 1 displays one rate initially, with additional rates available through the show-more button. The theme editor hint saying that 1 shows all rates does not reflect the current behavior.

Currency and Language

The widget requests rates in the store's base currency and displays prices in the customer's active storefront currency using Shopify's supplied exchange rate.

Apply currency rounding is enabled by default. When converting currencies, it applies the widget's bundled rounding rules. These rules do not read your store's individual Shopify Markets rounding configuration, so displayed estimates may differ from checkout.

Built-in interface translations are available for English, French, German, Spanish, Italian, Portuguese, Dutch, Japanese, Chinese, Korean, and Swedish. Other languages fall back to English. Custom address prefix text and rate names or descriptions returned by your code are not automatically translated by the widget.

Customizing the Appearance

Use the Container and Spacing settings to match the widget to your theme:

Colors: Set the text, background, border, button background, and button text colors.
Border: Adjust the border width and corner radius.
Font size: Scale widget text from 80% to 120%.
Margins: Adjust the space above and below the widget.
Padding: Adjust the space inside the widget on all four sides.

Testing Before Going Live

Test the widget on your storefront with:

Different product variants and quantities.
An empty cart and a cart containing other products.
A variant that is already in the cart, to confirm the combined quantity estimate.
Different destination countries, states, cities, and postcodes supported by your rules.
Logged-in and guest customers.
Different storefront currencies and languages, where applicable.

Compare the estimates with checkout using the same items and destination.

Product page rates are estimates. Checkout may calculate shipping separately for different shipping profiles or fulfillment locations. The widget supplies a single store-address origin and a combined item list. It also calculates item totals without checkout discounts and does not collect a full street address. Rules that depend on these details, or currency conversion and rounding, may produce different results at checkout.

Troubleshooting

Confirm that the block has been added to the product's assigned template and that the theme has been saved.
Check that the selected variant is available and requires shipping.
If the block is unavailable in the theme editor, check that the product section supports app blocks.

Shipping Rates Cannot Be Retrieved

Check the JsRates API key in the block settings. If you rotated the key in JsRates, update the block with the new key.
Confirm that your storefront domain is allowed under JsRates API on the JsRates Settings page.
Confirm that your shipping rate code runs successfully in JsRates.
Retry with a complete destination address.

No Shipping Rates Are Available

Check that your rules return rates for the selected product, quantity, and destination.
Enter any missing address details. The widget prompts for an address when it does not have enough destination information.
Enable city or state / province fields if your rules require them.

Rates Do Not Update After Product Changes

Test variant and quantity changes on your theme. The widget listens for product form changes and variant changes in the page URL. Themes with custom product selectors may require compatibility adjustments if those changes are not detected.

The Destination Is Incorrect

Open the address summary and select Update address after entering the correct destination. A destination previously saved in the browser takes priority over the customer's default address and automatic location detection.

Product Page Shipping Rate Widget in JsRates