...

Dev Shipping Rate Calculator API

Shipping Rate Calculator

Latest Version 2.0
Component Snippet 
{% if content_for_header contains 'cdn.parcelifyapp.com\/parcelify-components' %}
  {% render 'parcelify-rate-calculator' %}
{% endif %}
Asset Files

We provide component theme assets for when your theme does not support Theme Extension App Blocks, or you wish to customize the component. Upload the assets that correspond to your theme to the specified path and follow these instructions to integrate it into your theme. Use the Default assets if your specific theme is not listed.

Shopify Default (All Themes) Shopify Dawn Shopify Debut Shopify Prestige
Changelog v2.0
  • Release Date: 2024-01-08
  • New Theme Extension App Block integration for 2.0 themes
  • Removed direct Shopify Theme integration due to Shopify Asset API deprecation
v1.2
  • Release Date: 2023-01-30
  • Shipping prices are now formatted according to the customer's locale using the ECMAScript Internationalization API
  • Shipping prices are converted from the Shop's currency to the customer's if they differ
v1.1
  • Release Date: 2022-11-22
  • New Country and Region localization with support for 20+ languages
  • The provinceLabel and provinceCodeLabel are no longer lower case
  • Deprecated the rate_calculator:select_<region> translations, use the generic rate_calculator:select_one
v1.0
  • Use Shopify's new async shipping rate generation
  • Style automatically matches theme: Debut, Dawn, Prestige, Dawn-based themes
Known Issues
  • "There was a problem retrieving shipping rates from Shopify." - occurs when a third party carrier fails to return shipping rates to Shopify. We suggest removing all shipping rate providers from the Shipping Profile and add them back one at at a time, testing each time until the problematic provider is found.
  • Designed to work on the Cart page - This component looks for items in the cart to request shipping rates.

Status variables

These variables provide information about the state of a component and availability of data

Name type Description
hasPostalCodes boolean contains true if select country requires a postal code
Code Example 
<div x-show="hasPostalCodes">
  <span>This country has postal codes</span>
</div>
Show the contents of the div when hasPostalCodes is true
hasProvinces boolean returns true if selected country requires a province
Code Example 
<div x-show="hasProvinces">
  <span>This country has states, provinces, or prefectures</span>
</div>
Show the contents of the div when the selected country has provinces.
loading boolean returns true if the component is loading (not mounted)
Code Example 
<div x-show="!loading">
  <span>Shipping Calculator is loaded and ready to use!</span>
</div>
Shows the contents of the div after all the resources for the component have loaded.
quoting boolean returns true if shipping quotes are currently being fetched
Code Example 
<div x-show="quoting">
  <span>⌚ Please wait while we fetch your shipping rates</span>
</div>
Shows the contents of the div when we are waiting for shipping rates.
quoted boolean returns true if shipping quotes have been fetched
Code Example 
<div x-show="quoted">
  <span>Your shipping quote is available</span>
</div>
Shows the contents of the div when we have successfully retrieved shipping rates.
show boolean toggles shipping calculator visibility
Code Example 
<button type="submit" x-on:click.prevent="show = !show">Rate Calculator</button>
Shows a button that will enable and disable the visibility of this component

Destination variables

These fields must be filled in order for us to provide a shipping quote

Name type Description
destination object destination address to be used for shipping rate quote
destination.countryCode string country code (2 character ISO format)
destination.provinceCode string province/state/region code (2 character ISO format)
destination.postalCode string postal/zip code
Code Example 
<div>
  <input type="text" x-model="destination.countryCode">
  <input type="text" x-model="destination.provinceCode">
  <input type="text" x-model="destination.postalCode">
  <button type="submit" x-on:click.prevent="fetchQuotes">Fetch Rates</button>
</div>
Provides three fields to manually enter a shipping country, province, and postal code - along with a button to fetch shipping rates based on these values

Country variables

Use these variables to reveal where you ship to your customers

Name type Description
countries Country[] (object[]) list of countries where shipping is offered
selectedCountry Country (object) currently selected country
country object Represents an individual country
country.code string The ISO 3166-2 2-letter code for this country
country.name string The human-readable name for this country
country.provinces object[] list of available provinces/regions/states in this country
country.province.code string The ISO 3166-2 code for a province
country.province.name string The human-readable name of a province
country.provinceLabel string province input label for selected country
country.postalCodeLabel string postal code input label for selected country
Code Example 
<div>
  <button type="submit" x-on:click.prevent="selectedCountry = countries[0]">Country Info</button>
  <div>Country code: <span x-text="selectedCountry.code"></span></div>
  <div>Country name: <span x-text="selectedCountry.name"></span></div>
  <div>First Province code: <span x-text="selectedCountry.provinces[0].code"></span></div>
  <div>First Province name: <span x-text="selectedCountry.provinces[0].name"></span></div>
</div>
Selects the first country in the list of countries you ship to and displays its country code, name, one of its province codes, and that province name

Shipping Rates and Shipping Quotes

These variables allow you to display shipping rates once fetchRates() has been called

Name type Description
shippingQuote ShippingQuote (object) contains retrieved shipping quote
shippingQuote.rates ShippingRate[] (object[]) shipping rates for the quote
rate object represents an individual rate
rate.serviceName string the name of this shipping rate
rate.priceFormatted string the formatted amount for this shipping rate in your shop's local currency
rate.description string the description text for this rate
rate.currency string the currency code for your default currency
Example - JPY, USD, GBP
rate.price number the real price Shopify returned to us; the shipping total represented in your local currency's smallest denomination
Example - $100 USD = 10000
rate.minDeliveryDate Date if available, the estimated arrival date for this level of service
Code Example 
<div x-show="quoted">
    <template x-for="rate in shippingQuote.rates">
      <div>
        <span x-text="rate.currency"></span>
        <span x-text="rate.serviceName"></span>
        <span x-text="rate.priceFormatted"></span>
      </div>
    </template>
</div>
If a shipping quote is available via fetchQuotes(), this code will list them all with their names and formatted currencies

Interface Methods

Methods perform operations or take parameters (either directly or by variables you set up previously) to provide information

Method Name Parameters Returns Description
fetchQuotes
void retrieves shipping quotes using provided destination variables
hasError
  • readProperty (string)
string returns true if the provided readProperty has an error

Acceptable values of readProperty are the destination variables: countryCode, provinceCode, postalCode
getError
  • readProperty (string)
string returns the first error of the provided readProperty has an error

Localization Strings

Key English Value
rate_calculator:calculate_shipping Calculate shipping
rate_calculator:get_rates Calculate shipping rates
rate_calculator:shipping_rates Shipping Rates
rate_calculator:select_one Select one...
rate_calculator:generic_error There was a problem retrieving shipping rates from Shopify.
Anatomy of a Storefront Component Parcelify Storefront Components