Integrate with Shopify Using Liquid Templates
The Purple Dot Shopify Integration Script enables merchants on the Premium plan to start taking pre-orders on their Shopify store. It integrates into any Shopify theme and can be customised to meet the themes needs.
It handles features such as:
- Displaying an Add to Cart or Pre-order Button, depending on Waitlists and stock levels
- Hiding and Showing elements based on if a product is on pre-order
- Switching any Sold out labels in your theme to say Pre-order
- As well as others
To get started integrating follow the steps below.
- Go to your Shopify Admin page and go to the Products list page.
- Click Add Product
- Set the name of the product to
Z - Purple Dot Test Productand make sure it is not added to any collections or tags to make it difficult for real shoppers to find - Set the sales channels to Online Store only
- Give the product 3 Size options/variants
- Small should be out of stock
- Medium should have 1 unit of stock
- Large should be out of stock
- Set the price of these variants to free just in case anybody does find it
Later we will use this product to test that the integration is working as expected.
- Select the
Z - Purple Dot Test Productyou created earlier - Pick any future ship dates
- Set up incoming pre-order stock
- Small should be out of pre-order stock
- Medium should have 1 unit of pre-order stock
- Large should have 1 unit of pre-order stock
- Save the Waitlist
We need to have an open Waitlist set up to test the integration.
This will allow you to turn the Purple Dot integration on and off without any code changes.
- Clone your currently live theme to make a new preview theme
- In
config/settings_schema.jsonadd the following{"name": "Purple Dot","settings": [{"type": "checkbox","id": "use_purpledot","label": "Turn on Purple Dot integration"},{"type": "text","id": "purpledot_api_key","label": "Purple Dot API Key"}]}, - In
config/settings_data.jsonadd the following"use_purpledot": true,"purpledot_api_key": "<PURPLE_DOT_STORE_PUBLIC_API_KEY>",
The public API key of your Purple Dot store can be found at the bottom of the Integration settings page in the Merchant Portal.
- In the preview theme create a new snippet and name it
purple-dot.liquid - In
layout/theme.liquidfind the closing</head>tag and place the following code just before it{% if settings.use_purpledot and settings.purpledot_api_key != blank %}{% render 'purple-dot' %}{% endif %} - If you have custom checkouts enabled, in
layout/checkout.liquidfind the closing</head>tag and place the following code just before it{% if settings.use_purpledot and settings.purpledot_api_key != blank %}{% render 'purple-dot' %}{% endif %}
We will use
purple-dot.liquid as the place where all Purple Dot related code lives.Paste the following snippet into
purple-dot.liquid<script>
window.PurpleDotConfig = {
shopifyCart: {{ cart | json }},
};
</script>
<script src="https://www.purpledotprice.com/api/v1/init.js?apiKey={{settings.purpledot_api_key}}"></script>
Purple Dot offers 3 different methods for shoppers to buy pre-order products
- Combined Cart (the default)
- Separate Cart
- Express
If you want to use a non-default checkout method, please pass the additional
checkoutMethod parameter to window.PurpleDotConfig.- To use Separate Cartwindow.PurpleDotConfig = {checkoutMethod: 'SEPARATE_CART',...};
- To use Expresswindow.PurpleDotConfig = {checkoutMethod: 'EXPRESS',...};
If you do not know which checkout method you would like to integrate, contact us for more information.
Each checkout method may require some specifics to work with your store's theme.
No extra configuration is necessary
No extra configuration is necessary
- 1.Configure the cart placement
window.PurpleDotConfig = {
...
cart: {
// Icon styles
fill: '#000000',
strokeWidth: '1.5px',
matchFill: '.icon--cart',
width: '22px',
height: '22px',
// Function to place the cart element onto the page
placeElement: (cartElement, cartLink) => {
const cartLinkContainer = cartLink.parentElement;
const pdCartContainer = cartLinkContainer.cloneNode();
// Adjust these next two lines to your DOM, if necessary
pdCartContainer.appendChild(cartElement);
cartLinkContainer.insertAdjacentElement('beforebegin', pdCartContainer);
// Returns the container element
return pdCartContainer;
},
},
};
// Function to place the cart element onto the page
placeElement: (cartElement, cartLink) => {
const cartLinkContainer = cartLink.parentElement;
const pdCartContainer = cartLinkContainer.cloneNode();
const nav = document.querySelector('nav.Header__SecondaryNav');
// Define observer callback
const observer = new MutationObserver(() => {
const iframe = document.querySelector('iframe.purple-dot-frame');
if (iframe.style.display === "none") {
pdCartContainer.style.display = "none";
} else {
// May need to adjust this line to suit your theme
pdCartContainer.style.display = "inline-block";
}
});
// Adjust these next two lines to your DOM, if necessary
pdCartContainer.appendChild(cartElement);
cartLinkContainer.insertAdjacentElement('beforebegin', pdCartContainer);
// Set up observer:
// IMPORTANT: 'attributes' must be true, as iframe.style.display will change
observer.observe(nav, { attributes: true, childList: true, subtree: true });
// Returns the container element
return pdCartContainer;
},
- 2.Configure variant selectors on a PDP
window.PurpleDotConfig = {
...
pdp: {
variantSelector: {
// Selector that targets an individual element
selector: '',
// Class to remove order to enable the variant
disabledClass: '',
},
},
};
We support a number of customisations to Product Detail Pages (PDP) and Product Listing Pages (PLP) that may be required.
Out of the box, when the shopper selects a variant that is on pre-order through Purple Dot, we will hide the following on every PDP because we do not support them in our checkouts:
- Shopify payment buttons
- Klarna messaging
- Klaviyo notify me buttons
- as well as others
If you would like to hide some elements, simply add a
pdp.hide attribute with an array of selectors to instruct Purple Dot to hide these if the selected variant will be on pre-orderIf you would like to show some elements, create them in your theme with
display:none and then add a pdp.show attribute with an array of selectors to instruct Purple Dot to display these if the selected variant will be on pre-order.window.PurpleDotConfig = {
...
pdp: {
hide: ['<SELECTOR>'],
show: ['<SELECTOR>'],
},
};
To modify the quick view/add components on a PLP for any product that is on pre-order
window.PurpleDotConfig = {
...
plp: {
quickAdd: {
// Optional selector that targets the title element within a collection item
title: '',
// Optional string that will be used in place of the existing text
newTitle: '',
// Optional selector for a size selector element which Purple Dot will
// transform to link through to the PDP
sizeSelector: '',
// Class used to disable the size selector if the variant is sold out.
// Purple Dot will remove this if the variant is available for pre-order
disabledClass: '',
// Useful if you need to remove some attributes from some elements
removeAttributes: [{
selector: '',
attributes: [''],
}],
},
},
};
If your store supports multiple currencies you have to pass the currently selected one through. For example if you are a Shopify Markets user then you can do this as follows.
window.PurpleDotConfig = {
...,
currency: {{ cart.currency.iso_code | json }},
};
The provided discount will be applied to every checkout involving a line item on preorder.
window.PurpleDotConfig = {
...,
discountCode: <discount code>,
};
Currently support English, Spanish and German.
The correct locale will be automatically detected in most cases but if you wish to override it you can set it yourself.
window.PurpleDotConfig = {
...,
locale: 'es-ES',
};
Purple Dot does not show up for product variants that have some stock to be sold in the Online Store. We subscribe to your Shopify store's inventory updates to stay updated on current instock inventory levels, but you can override our view by explicitly providing latest product stock levels like so
const s = {};
Object.assign(s, {
{%- for variant in product.variants %}
{{ variant.id }}: {{ variant.inventory_quantity }},
{%- endfor %}
});
{% for product in collection.products -%}
Object.assign(s, {
{%- for variant in product.variants %}
{{ variant.id }}: {{ variant.inventory_quantity }},
{%- endfor %}
});
{% endfor -%}
{% for product in recommendations.products %}
Object.assign(s, {
{%- for variant in product.variants %}
{{ variant.id }}: {{ variant.inventory_quantity }},
{%- endfor %}
});
{% endfor -%}
{% for product in search.results -%}
Object.assign(s, {
{%- for variant in product.variants %}
{{ variant.id }}: {{ variant.inventory_quantity }},
{%- endfor %}
});
{% endfor -%}
window.PurpleDotConfig = {
...,
variantStockMap: s,
};
Purple Dot will email the subscribed shoppers when the product is back on pre-order. Please note: this feature is only supported by
EXPRESS and SEPARATE_CART checkout methods.window.PurpleDotConfig = {
...
enableNotifyMe: true,
};
Configuring this ensures your store is tracking conversions relating to pre-orders. See the snippet below for the currently available integrations. The Facebook Pixel and Google Analytics tracking is turned on by default. Please note: Klaviyo requires further setup in the Integration settings page in the Merchant Portal.
window.PurpleDotConfig = {
...,
tracking: {
facebookPixel: true,
googleAnalytics: true,
googleAdsTag: {
sendTo: '...',
},
klaviyo: true,
},
};
Some merchants handle multiple markets with one Shopify store, with checkout handled by another service like Global-E. Purple Dot does not currently support integrating with other checkout providers and so in these cases you can hide Purple Dot in markets you do not wish to offer pre-orders in.
window.PurpleDotConfig = {
...,
enableWaitlists: () => {
// Show Purple Dot to UK shoppers only
return new Promise((resolve, reject) => {
const interval = setInterval(() => {
try {
let waitlistsEnabled;
if (window.GLBE_PARAMS && window.GLBE_PARAMS.countryCode) {
waitlistsEnabled = window.GLBE_PARAMS.countryCode === 'GB';
} else if (window.GlobalE && window.GlobalE.Country) {
waitlistsEnabled = window.GlobalE.Country === 'GB';
}
if (waitlistsEnabled !== undefined) {
clearInterval(interval);
resolve(waitlistsEnabled);
}
} catch (err) {
clearInterval(interval);
reject(err);
}
}, 100);
setTimeout(reject, 10000);
});
},
};
If your store has sitewide discounts enabled then you need to turn the following flag on to apply the same discounts on Purple Dot.
window.PurpleDotConfig = {
...,
createFromCart: true,
};
Sometimes, you may need to override the text of buttons for different locales e.g. US/UK. To achieve this, you can use the
translations parameter inside the PurpleDotConfig object:window.PurpleDotConfig = {
...,
translations: {
'en-US': { addToCart: 'Add to Cart' }
'en-GB': { addToCart: 'Add to Bag' }
}
};
Alternatively, if you would like to just override it at all times, you can set your
locale to one specific thing, and then you only need one translation rule, like so:window.PurpleDotConfig = {
...,
locale: 'eu-US',
translations: {
'en-US': { addToCart: '🛍 Add To Bag' }
}
};
Note: This applies to the product detail page only
You may find that you need to style some components on a page differently when a waitlisted variant is selected. In this case, you can add the
styles param to your PurpleDotConfig.pdp.A good example of this would be when our 'Waitlist powered by' content is being added incorrectly to the PDP. Our code adds the waitlist content underneath the 'Pre-order' button (in the DOM), but if the button is in a flex container with
flex-direction: row, the waitlist info will be added to the side of the button.We can solve this using CSS, which will only be applied if the selected variant is on pre-order, and will be removed when the selected variant is not on preorder. We can also specify multiple style rules, if needed, and change values based on screen size, e.g. mobile screens.
window.PurpleDotConfig = {
...
// 'styles' must be inside 'pdp', not 'plp'
pdp: {
styles: {
preorder: [
{
selector: '.product__buy-buttons',
style: 'flex-wrap: wrap'
},
{
media: 'only screen and (max-width: 600px)',
selector: '.product__add',
style: 'width: 100% !important'
},
{
media: 'only screen and (min-width: 600px)',
selector: '.product__add',
style: 'width: 50% !important'
},
]
}
}
};
To check that everything is working correctly, look for the following
Referencing the test product setup outlined earlier
- When the Small variant is selected, the product appears as out of stock and no pre-order messaging is shown.
- When the Medium variant is selected, the product appears as in stock and no pre-order messaging is shown. When added to cart, the standard Shopify checkout is used.
- The Large variant is selected, the CTA changes to "Pre-order" and the Waitlist ship dates are displayed underneath. When added to cart, the Purple Dot checkout is used (Combined, Separate or Express) and the expected ship dates are shown.
If using Express Checkout:
- The express checkout opens when the Pre-order button is clicked.
If using Separate Cart:
- The product is added to a dedicated pre-order cart and the pre-order cart button is now showing throughout the store.
If using Combined Cart:
- The Purple Dot checkout is used whenever you try to check out, from the /cart page and from any quick checkout links.
If you have any quick view components or modals, any Add to Cart functionality in those should work the same as on a PDP.
To enable this checkout type Purple Dot ticks "Continue selling when out of stock" for every product variant that is on pre-order. Our system ensures that no oversell can occur beyond the defined pre-order stock level but only if our Pre-order button shows in every instance where the shopper can add products to their cart. Please check that:
- in your Shopify store every product with a Live Waitlist has only the Online Store sales channel turned on
- the Pre-order CTA shows for size Large everywhere it is possible to add products to the cart
- products on pre-order are excluded from any functionality that can automatically add products to the cart thereby bypassing Purple Dot (e.g. buy one get one free)
- Publish the preview theme
- Set up Waitlists - to take pre-orders, a product variant needs to have 0 stock in Shopify and an open Waitlist with incoming pre-order stock in Purple Dot
- When using Combined Cart, Purple Dot will enable "Continue selling when out of stock" for variants that have a Waitlist