Integrate with Shopify Using Liquid Templates

Looking to learn more about our Platform integration? See the Purple Dot Overview.

Introduction

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 lables in your theme to say Pre-order
  • As well as others

To get started integrating follow the steps below.

Integrating

1. Create a test product

  • 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 Product and 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.

2. Set up a Waitlist

  • Go to your Purple Dot Merchant Portal, navigate to Waitlists and click New Waitlist
  • Select the Z - Purple Dot Test Product you created earlier
  • Pick any future ship dates
  • Set up incoming pre-order stoc
    • 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.

3. Add Purple Dot to your theme settings

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.json add 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.json add the following
    "use_purpledot": true,
    "purpledot_api_key": "<API_KEY>",

4. Create a purple-dot.liquid snippet in your theme

  • In the preview theme create a new snippet and name it purple-dot.liquid
  • In layout/theme.liquid find 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.

5. Setup your preferred checkout method

Purple Dot offers 3 different methods for shoppers to buy pre-order products:

  • Combined Cart
  • Separate Cart
  • Express

Based on which checkout method you would like to integrate, paste the relevant snippet into purple-dot.liquid.

If you do not know which checkout method you would like to integrate, contact us for more information.

Combined Cart

<script>
window.PurpleDotConfig = {
shopifyCart: {{ cart | json }},
};
</script>
<script src="https://www.purpledotprice.com/api/v1/init.js?apiKey={{settings.purpledot_api_key}}"></script>

Express

Use the Combined Cart snippet above but adjust the PurpleDotConfig section like:

window.PurpleDotConfig = {
...
checkoutMethod: 'EXPRESS',
};

Separate Cart

Use the Combined Cart snippet above but adjust the PurpleDotConfig section like:

window.PurpleDotConfig = {
...
checkoutMethod: 'SEPARATE_CART',
};

6. Configure the checkout method for your theme

Each checkout method may require some specifics to work with your store's theme.

Combined Cart

You need to ensure that there is no way to bypass Purple Dot when the shopper's cart includes a Waitlisted product line item. An example of this would be an abandoned cart email that deep links shoppers past the /cart page and straight into your native checkout.

If you have a Shopify+ store, Purple Dot can take care of this for you:

  • In the preview theme find (or create) layout/checkout.liquid
  • Find 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 a Shopify store then you must ensure this by removing all ways to bypass the /cart page when the shopper's cart includes a Waitlisted product line item.

Express

  • No extra configuration is necessary

Separate Cart

  1. Configure the cart placement
window.PurpleDotConfig = {
...
cart: {
placeElement: (cartEl, cartLink) => {
// Function to place the cart element onto the page.
// Returns the container element
},
},
};

7. (Optional) Various configuration options

Modify existing PDP/PLP page behaviour

We support a number of customisations to Product Detail Pages (PDP) and Product Listing Pages (PLP) that may be required to

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
  • Kaviyo 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-order

If 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 variant selectors on a PDP for any variant that is on pre-order

window.PurpleDotConfig = {
...
pdp: {
variantSelector: {
// Selector that targets an individual element
selector: '',
// Class to remove order to enable the variant
disabledClass: '',
},
},
};

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: [''],
}],
},
},
};

Customise currency

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 }},
};

Automatically apply discount

The provided discount will be applied to every checkout involving a line item on preorder.

window.PurpleDotConfig = {
...,
discountCode: <discount code>,
};

Localise the Pre-order button

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',
};

Set current instock inventory levels explicitly

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,
};

Enable pre-order stock notification

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,
};

Enable conversion tracking

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 Purple Dot Merchant Portal.

window.PurpleDotConfig = {
...,
tracking: {
facebookPixel: true,
googleAnalytics: true,
googleAdsTag: {
sendTo: '...',
},
klaviyo: true,
},
};

Restrict Purple Dot to some markets

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(() => {
if (window.GlobalE.Country) {
clearInterval(interval);
resolve(window.GlobalE.Country === 'GB');
}
}, 100);
setTimeout(reject, 10000);
});
},
};

Sitewide discounts

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,
};

8. Test the integration

To check that everything is working correctly, look for the following

On the PDP

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 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.

On the PLP

If you have any quick view components or modals, any Add to Cart functionality in those should work the same as on a PDP.

Extra testing if using Combined Cart

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)

9. Start taking pre-orders

  • 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