Delivery methods component

1. Add the Javascript library

Insert the script tag that loads the component in the <head>

<script src="https://cdn.sparqle.com/delivery-methods/latest/component.bundle.js"></script>

NB: the latest version is targeted here, as you can see in the url. It is also possible, and preferred to target specific versions eg: https://cdn-stage.sparqle.com/delivery-methods/v1.0/component.bundle.js. See next paragraph for more info.

Versioning and releases

Sparqle applies semantic versioning for the component. Every release, major, minor and patch is published in 4 ways:

As the Patch version: delivery-methods/v0.1.12/component.bundle.js
As the latest Minor: delivery-methods/v0.1/component.bundle.js
As the latest Major: delivery-methods/v0/component.bundle.js
As the latest: delivery-methods/latest/component.bundle.js

This allows you to subscribe to a type of release, eg:

if you implement v0.1 you automatically get all the patches published under that minor version.
if you implement latest you automatically get all version updates, including breaking ones. It is not recommended to apply this in production.

Release notes are published at the end of this page to help you decide when to upgrade the component version.

2. Add component to your delivery method form HTML

Insert the HTML component where you want it to be displayed:

<sparqle-delivery-methods 
	location-id="ABC123XYZ" 
  mock="true" 
  free-shipping="true"
></sparqle-delivery-methods>

The location-id is the Sparqle id connected to your location, that you can find in your Sparqle account.

The mock="true" will give you mock data, convenient for quick testing. It can be left out entirely or set to false to get data based on input address, configured location and delivery areas in the Sparqle dashboard.

The free-shipping="true" parameter displays all delivery options for free.

You can add your own styling by overriding the rules in our CSS file.

3. Add configuration, order info and address

3.1 Create a configuration object with the following parameters:

const configuration = {
	reference: "OrderId-12345",
	locale: "nl_NL"  
}

Target the Sparqle-delivery-methods component and set the configuration object:

const sparqleCheckout = document.querySelector('sparqle-delivery-methods');

sparqleCheckout.setConfiguration(configuration);

3.2 Optionally create order object

const cart = {
	totalPrice: 4749, // in cents
}

Target the Sparqle-delivery-methods component and set the configuration object:

const sparqleCheckout = document.querySelector('sparqle-delivery-methods');

sparqleCheckout.setCart(cart);

3.2 Add the address object

It is possible to set the address programmatically or to use this component in combination with the Sparqle address component.

3.2.1 Set Address programmatically

const address = {
  street: "IJsbaanpad",
  houseNumber: "2",
  suffix: "",
  postalCode: "1076CV",
  city: "Amsterdam",
  countryCode: "NL"
}

Target the Sparqle-delivery-methods component and set the configuration object:

const sparqleCheckout = document.querySelector('sparqle-delivery-methods');

sparqleCheckout.setAddress(address);

3.2.2 Use in combination with Sparqle address component

If you use the combination of components the delivery methods component listens to the address component

Insert the sparqle-address-component

<script src="https://cdn-stage.sparqle.com/address/latest/component.bundle.js"></script>
<sparqle-address
   show-country="false"
   country-code="NL"
   locale="nl_NL"
></sparqle-address>

Set the use-sparqle-address prop to true

<sparqle-delivery-methods
  location-id="U5WPDIRUXW"
  mock="true"
  use-sparqle-address="true"
></sparqle-delivery-methods>

4. Get available delivery options

Call fetch delivery methods on the component with the address object:

sparqleCheckout.fetchDeliveryMethods(address);

5. Get selected option from event

The component emits an event with info about the selected option:

   document.addEventListener("sparqleCheckoutClicked", function (event) {
      console.log("Custom event received:", event.detail);
   });

6. Release notes

v1.0.15 - 16-09-2024

dont trigger delivery methods call if address incomplete
dont use double ids in html

v1.0.10 - 16-09-2024

align radio button with logo

v1.0.9 - 16-09-2024

allow spaces in postalCode
display pickup point details in emitted event
bugfix not displaying delivery methods
setCart function to set totalPrice of cart
emitted event contains cart info

v1.0.5 - 16-07-2024

reference can be empty
order info can be provided to apply shipping rules for delivery options

bigger carrier logo icons
free shipping possible
better error handling
errors in selected language

Breaking changes:

component attribute location-id is hyphenated
component name is changed to \<sparqle-delivery-methods>

Other features:

can be used on combination with sparqle address component

v0.2.0 - 24-06-2024

Initial public version.