Skip to content
⚓️ A shipping calculator library for Shopify
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
browser
src
test
.gitignore
.npmignore
README.md
package.json

README.md

Shopify Shipping Calculator

Fetch shipping rates for a Shopify store based on country, province, and zip.

Limitations

  • For use in Shopify-hosted themes only. This module does not support CORS requests.
  • Request /services/countries.js before your javascript bundle. This defines a Countries object on the window that this library depends on.
    {{ '/services/javascripts/countries.js' | script_tag }}
  • See markup requirements below.

Install

npm i shopify-shipping-calculator --save

Usage

import shipper from 'shopify-shipping-calculator'

const form = document.querySelector('.js-form')

const calculator = shipper(form)

calculator.on('success', rates => handleSuccess(rates))
calculator.on('error', res => handleError(res))

calculator.on('change', { country, province, zip, meta } => {
  // hide/show needed fields, clear previous results, etc
})

calculator.getState()
/** returns
{
  country: 'United States',
  province: 'New York',
  zip: '10013',
  meta: {
    province_label: 'State',
    zip_label: 'Zip code',
    provinces: [...states]
  }
}
*/

Configuration

calculator(form[, options])

This library takes two parameters: form and options. form should be the shipping calculator form element, and options is an object.

// country will default to the first country in the `window['Countries']` object
const calculator = shipper(form)

// or, optionally specify a default country
const calculator = shipper(form, {
  defaultCountry: 'United States'
})

Options

defaultCountry string

The preselected country shown on form load. Default: null.

const calculator = shipper(form, {
  defaultCountry: "Canada"
})

Events

This library emits a few helpful events and exposes data that you can use to manage the state of the calculator UI.

success

Called after a successful fetch, returns an array of shipping rates:

calculator.on('success', rates => {
  rates.forEach(r => resultsContainer.innerHTML += `${r.type}: ${r.price}`)
})

error

Called after an unsuccessful fetch, returns an error message from the Shopify servers:

calculator.on('error', res => console.warn(res))

change

Called when the country selector changes, is passed the full state object returned from .getState().

calculator.on('change', { country, province, zip, meta } => {
  !!province ? (
    provinceSelector.style.display = 'block'
  ) : (
    provinceSelector.style.display = 'none'
  )
})

API: Properties

.getState()

Returns an object representing the data fetched by the form.

calculator.getState()

/** returns
{
  country: 'United States',
  province: 'New York',
  zip: '10013',
  meta: {
    province_label: 'State',
    zip_label: 'Zip code',
    provinces: [...states]
  }
}
*/

.on(event, callback)

Attach handlers for event emissions from the instance.

calculator.on('success', rates => // do stuff)

Markup

The only markup requirements for this library are a standard HTML form element that contains inputs with name attributes matching country, province and zip.

<form class="js-form">
  <select name="country"></select>
  <select name="province"></select>
  <input type="text" name="zip">
  <input type="submit" value="submit">
</form>

License

MIT

You can’t perform that action at this time.