Initializing the Paazl Checkout widget

Initializing the Paazl checkout widget

This article gives detailed explanations of the parameters used to initialize the Paazl checkout widget. If you have integrated the Paazl checkout widget in your webshop, the widget will be initialized using the parameters in the table below. This will happen each time one of your webshop customers lands on your checkout page. Integrating the Paazl checkout widget step by step explains how to initialize the widget's styling. Use the parameters below to configure the widget's layout, display and behavior.

Initialization parameters

Parameter Required/Optional Type Explanation
mountElementId Optional String The id attribute of the block element in which you want to display the Paazl checkout widget.

The default value is "paazl-checkout".

Example: mountElementId: "checkout-widget"

apiKey Required String

A string containing a public API key generated in the Paazl web app. See Configuring the REST API for an explanation of how to generate this key.

Example: apiKey: "12345"

token Required String

The access token returned by the token endpoint.

If you assign token a value, Paazl temporarily registers session details in its database—including the session reference you gave when creating the token—in order to keep track of the choices made by webshop customers.

Example: token: "23o4587y-wsakfgh-3249-srljhtgl"

loadPaazlBasedData Optional Boolean

If true, Paazl returns shipping options derived from your delivery matrix.

Note

This parameter only affects shipping options for home delivery.

If both loadPaazlBasedData and loadCarrierBasedData are true, the widget will first retrieve Paazl data because this is quicker. It then requests carrier data. If this differs from the Paazl data, the widget will override the Paazl data with the carrier data.

If both loadPaazlBasedData and loadCarrierBasedData are false, no data will be retrieved.

The default value is true.

Example: loadPaazlBasedData: false

loadCarrierBasedData Optional Boolean

If true, and the carrier concerned supplies such data, Paazl returns shipping options obtained from the carrier itself.

Note

This parameter only affects shipping options for home delivery.

If both loadPaazlBasedData and loadCarrierBasedData are true, the widget will first retrieve Paazl data because this is quicker. It then requests carrier data. If this differs from the Paazl data, the widget will override the Paazl data with the carrier data.

If both loadPaazlBasedData and loadCarrierBasedData are false, no data will be retrieved.

The default value is false.

Example: loadCarrierBasedData: true

availableTabs Optional Array

The widget displays shipping options in a number of tabs depending on the delivery type. The following values are available:

  • "DELIVERY" (shipping options for home delivery)
  • "STORE" (shipping options for click & collect stores)
  • "PICKUP" (shipping options for pick-up locations)

The default is ["DELIVERY", "STORE", "PICKUP"]

Note

The tabs will be displayed from left to right in order you specify them.

Note

Tabs will only be displayed if they contain shipping options.

Example: availableTabs: ["PICKUP", "DELIVERY"]

defaultTab Optional String

The name of the tab that is selected by default. The value you enter here must be one of the availableTabs values.

The default value is "DELIVERY".

Example: defaultTab: "PICKUP"

headerTabType Optional String

Determines whether the tabs are displayed as tabs:

headerTabType: "TAB"

headerType-tab.png

or as buttons:

headerTabType: "BUTTON"

headerType-button.png

The default value is "TAB".

style Optional String

Paazl has a number of predefined widget styles that you can use to match your webshop branding. The following values are available:

  • "DEFAULT"
  • "GREEN"
  • "LIGHT-GREEN"
  • "BROWN"
  • "BLUE"
  • "RED"

The default value is "DEFAULT", which uses Paazl's default styling.

Example: style: "BLUE"

nominatedDateEnabled Optional Boolean

If true, shipping options will be displayed grouped by date. If false, the list will be displayed in ascending order of price, i.e. the least expensive option will be at the top.

The default value is false.

Example: nominatedDateEnabled: true

consigneeCountryCode Required String

The ISO 3166-2 code for the country the shipment is being sent to.

Example: consigneeCountryCode: "NL”

consignorCountryCode Optional String

The ISO 3166-2 code for the country the shipment is being sent from.

If left empty, Paazl will use the default setting in your Paazl web app account under Settings > My address book > Sender address > Country.

Example: consignorCountryCode: "NL”

consigneePostalCode Required String

The postal code of the address the shipment is being sent to. The code is used to get a more precise list of available shipping options.

Example: consigneePostalCode: "1020HD”

consignorPostalCode Optional String

The postal code of the address the shipment is being sent from. The code is used to get delivery dates from carriers if they offer this service.

If left empty, Paazl will use the default setting in your Paazl web app account under Settings > My address book > Sender address > Postal code.

Example: consignorPostalCode: "1019HD”

customerNumber Optional String

An individual code that DHL issues to customers so that they can identify themselves at a DHL PackStation.

Example: customerNumber:XYZ1234

numberOfProcessingDays Optional Number

The number of days a warehouse needs to get an order ready for pick-up by a carrier.

The default value is 0. However, if you have specified a value for processing days in your webshop's delivery matrix, that value will override numberOfProcessingDays.

Minimum value: 0

Maximum value: 99

Example: numberOfProcessingDays: 5

tags Optional Array

Codes that are used to filter returned shipping options for display. Possible values that the array can contain are:

  • "PACK_STATION"
  • "SAME_DAY"
  • "FLEX_DELIVERY"
  • "CASH_ON_DELIVERY"
  • "INSURANCE"
  • "SIGNATURE_REQUIRED"
  • "AT_NEIGHBORS"
  • "NOT_AT_NEIGHBORS"
  • "RETURN_ON_FAILURE"
  • "DATE_PREFERENCE"
  • "TWENTYFOUR_SEVEN"
  • "NOTIFY_RECEIVER"
  • "SUNDAY_SORTING"
  • "AGE_CHECK"
  • "ID_CHECK"
  • "CLIMATE_COMPENSATION"
  • "DANGEROUS_GOODS"
  • "RETURN_TO_SENDER"
  • "NO_PROOF_OF_DELIVERY"
  • "PERISHABLE"

Example: tags: ["CASH_ON_DELIVERY", "INSURANCE"]

deliveryDateOptions Optional Object

Contains options affecting the delivery date.

Example: deliveryDateOptions: {"startDate": "2018-08-27", "numberOfDays": 5}

startDate Optional String

The starting point of a range of possible delivery dates.

Note

When calculating the start date for a delivery date range, Paazl adds the number of delivery days and processing days you have configured in your webshop's delivery matrix.

Format: "YYYY-MM-DD”

The default value is today's date.

Example: startDate: "2018-08-27"

numberOfDays Optional Number

The number of days a shipment is in transit.

The default value is 7. However, if you have specified a value for delivery days in your webshop's delivery matrix, that value will override numberOfDays.

Example: numberOfDays: 3

language Optional String

The ISO 639-1 or ISO 639-2 code for the widget's display language.

Note

If a language code is used that Paazl does not yet support, the widget display language will be English.

The languages currently supported are:

  • English ("eng")
  • German ("ger" or "deu")
  • Dutch ("nld")
  • Polish ("pol")

The default value is "eng".

Example: language: "deu"

currency Optional String

The ISO 4217 code for the currency concerned.

The parameter determines the currency icon that is displayed next to shipping rates.

The default code is "EUR".

Example: currency:"USD"

isPricingEnabled Optional Boolean

If false, the shipping rates of the various shipping options will not be displayed in the widget.

The default value is true

isShowAsExtraCost Optional Boolean

If true, the shipping cost will be displayed as a separate amount using a "plus" symbol

If false, no "plus" symbol will be displayed

The default value is false

deliveryRangeFormat Optional String

Indicates whether you want date ranges displayed on shipping option rows displayed as a number of days, or as a date range.

This parameter takes one of two values:

  • DATE
  • NUMBER

If deliveryRangeFormat = "DATE", the range will be shown as two dates

If deliveryRangeFormat = "NUMBER", the range will be shown as a number of days

Note

If you choose "DATE", the date format parameters will apply.

The default value is "DATE".

Example: deliveryRangeFormat:"NUMBER"

deliveryOptionDateFormat Optional String

The format for dates displayed in the shipping option rows of the widget's "Delivery" tab. The string format used is that of the Javascript fetcha library.

The default value is "ddd DD MMM".

Note

See Formatting widget dates for more information of how to format widget dates.

Example: deliveryOptionDateFormat: "DD-MM-YY"

deliveryEstimateDateFormat Optional String

The format for dates displayed in the footer of the widget's "Delivery" tab. The string format used is that of the Javascript fetcha library.

Note

See Formatting widget dates for more information of how to format widget dates.

The default value is "dddd DD MMMM".

Example: deliveryEstimateDateFormat:"dddd, MMMM DD, YYYY"

pickupOptionDateFormat Optional String

The format for dates displayed in the shipping option rows of the widget's "Pickup" tab. The string format used is that of the Javascript fetcha library.

Note

See Formatting widget dates for more information of how to format widget dates.

The default value is "ddd DD MMM".

Example: pickupOptionDateFormat: "DD-MM-YY"

pickupEstimateDateFormat Optional String

The format for dates displayed in the footer of the widget's "Pickup" tab. The string format used is that of the Javascript fetcha library.

Note

See Formatting widget dates for more information of how to format widget dates.

The default value is "dddd DD MMMM".

Example: pickupEstimateDateFormat:"dddd, MMMM DD, YYYY"

separatorsFormat Optional String

Specifies whether the widget should display numbers with a period for the decimal place and a comma to separate groups of thousands (as used in the USA and UK) or vice versa.

The parameter takes one of two values:

  • DECIMAL_COMMA
  • DECIMAL_POINT

The default value is "DECIMAL_COMMA"

Example: separatorsFormat:"DECIMAL_COMMA"

sortingModel Optional Object

Contains elements that tell Paazl how to sort the shipping options it sends back.

Examples:

sortingModel: {orderBy: "DATE", sortOrder: "DESC"}

sortingModel: {orderBy: "CARRIER", distributor: "DHL Deutschland"}

orderBy Optional String

Indicates how the displayed shipping options should be sorted. Possible values are:

  • "PRICE"
  • "DATE"
  • "CARRIER"

The default value is "PRICE".

distributor Conditional String

Indicates which carrier's shipping options should appear at the top of the shipping options list.

You will find carrier codes available to you in your web app account under Settings > Account > Overview of shipping options.

The shipping options displayed following those of distributor will be displayed in order of ascending price

Note

If orderBy has the value "CARRIER", you have to include distributor in the sortngModel object, otherwise you can leave it out.

Example: distributor: "SELEKTVRACHT"

sortOrder Optional String

Indicates the order in which shipping options should be sorted. Possible values are:

  • "ASC"
  • "DESC"

Note

If orderBy has the value "CARRIER", this element will be ignored.

The default value is "ASC".

Example: sortOrder:"DESC"

shipmentParameters Optional Object

Contains details of a customer’s order.

Example: shipmentParameters: {totalWeight: 3.14, startMatrix: "AA", goods: [{quantity: 2, weight: 3}, {width: 1, height: 5}]}

totalWeight Optional Number

The total weight in kilograms (kg) of a shipment, including packaging.

Note!

If you give totalWeight a value, the volumes of the individual products in the shipment will be ignored.

Example: totalWeight: 10

totalVolume Optional Number

The total volume in cubic meters (m3) of the shipment concerned, including packaging.

Note

If you give totalVolume a value, the volumes of the individual goods in the shipment will be ignored.

Example: totalVolume: 1

totalPrice Optional Number

The total price of a shipment. This is a scalar value. The currency unit is assigned by your webshop's checkout page.

Note!

If you give totalPrice a value, the prices of the individual products in the shipment will be ignored.

Example: totalPrice: 100

numberOfGoods Optional Number

The total number of packages or individual goods in a shipment.

Note!

If you give numberOfGoods a value, the quantity attribute of each goods array will be ignored.

Example: numberOfGoods: 8

startMatrix Optional String

A one- or two-letter code identifying the delivery matrix column to start with when determining the appropriate shipping option and rate. See Configuring delivery matrices for an explanation of how delivery matrices work.

goods Optional Array

An array of variables used to determine the applicable delivery matrix. See Configuring delivery matrices for an explanation of how delivery matrices work.

Example: goods:[{quantity: 2, weight: 3}, {width: 1, height: 5}]

quantity Optional Number

The number of items of a particular product type in a shipment.

Example: quantity: 7

weight Optional Number

The weight in kilograms (kg) of a product.

Example: weight: 10.5

length Optional Integer

The length in whole centimeters (cm) of a product.

Note

The value you assign this attribute must be an integer. If you assign a floating-point value, Paazl will truncate it.

Example: length: 170

width Optional Integer

The width in whole centimeters (cm) of a product.

Note

The value you assign this attribute must be an integer. If you assign a floating-point value, Paazl will truncate it.

Example: width: 30

height Optional Integer

The height in whole centimeters (cm) of a product.

Note

The value you assign this attribute must be an integer. If you assign a floating-point value, Paazl will truncate it.

Example: height: 10

volume Optional Number

The volume of a product in cubic meters (m3), including packaging.

Example: volume: 0.10

price Optional Number

The price of a single item in a shipment. This is a scalar value. The currency unit is assigned by your webshop's checkout page.

Example: width: 30

startMatrix Optional String

A one- or two-letter code identifying the delivery matrix column to start with when determining the appropriate shipping option and rate. See Configuring delivery matrices for an explanation of how delivery matrices work.

shippingOptionsLimit Optional Number

Limits the number of shipping options displayed on the widget's "Delivery" tab.

The default value is 10.

Example: shippingOptionsLimit: 3

initialPickupLocations Optional Number

Limits the number of pickup locations displayed on the widget's "Pickup" tab, and the number of store locations displayed on the "Store" tab.

The default value is 3.

Example: initialPickupLocations: 10

pickupLocationsPageLimit Optional Number

Specifies the initial number of pickup locations displayed on the widget's pickup location map, and the initial number of store locations displayed on the widget's store location map

It also determines the number of pickup or store locations that are added every time you click "More" on, respectively, the "Pickup" or "Store" tabs.

You see the map if you click "Select a different pickup point" on the "Pickup" or "Store" tabs. The locations closest to the delivery address are displayed.

The default value is 10.

Example: pickupLocationsPageLimit: 5

pickupLocationsLimit Optional Number

Limits the total number of pickup locations displayed on the widget's "Pickup" map, and the total number of store locations displayed on the widget's "Store" map.

You see the map if you click "Select a different pickup point" on the "Pickup" or "Store" tabs. The locations closest to the delivery address are displayed.

The default value is 20.

Example: pickupLocationsLimit: 10

Formatting widget dates

The date format strings that you use when initializing the widget adhere to the ISO-8601 standard. Here are a few examples:

Date example Format string
Wednesday, September 09, 2018 "dddd, MMMM DD, YYYY"
Wed, 9 Sep 2018 "ddd, D MMM YYYY"
9. September 2018 "D. MMMM YYYY"
09-09-18 "DD-MM-YY"

For languages other than English, we recommend you format dates as indicated below in order (where applicable) to avoid problems regarding case-endings or capitalization with respect to the widget labels.

Language Recommended format
Chinese "YYYY/MM/DD"
Dutch "DD.MM.YYYY"
French "D MMMM YYYY"
German "DD.MM.YYYY"
Italian "DD/MM/YYYY"
Korean "YYYY/MM/DD"
Polish "DD.MM.YYYY"
Russian "DD.MM.YYYY"
Spanish "DD-MM-YYYY"
Swedish "YYYY/MM/DD"

Was this article helpful?