Integrate Shopify Using Liquid Templates

Introduction

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

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>
(() => {
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 = {
apiKey: '{{ settings.purpledot_api_key }}',
variantStockMap: s,
checkoutMethod: 'COMBINED_CART',
shopifyCart: {{ cart | json }},
currency: {{ cart.currency.iso_code | json }},
};
const preLoadStyle = document.createElement('style');
preLoadStyle.id = 'pd-preload-style';
preLoadStyle.innerHTML = `
form[action^='/cart'] *[type='submit'], form iframe, a[href='/checkout'] {
pointer-events: none !important;
}
`;
document.head.appendChild(preLoadStyle);
const pdScript = document.createElement('script');
pdScript.src = 'https://www.purpledotprice.com/api/v1/shopify-script.js';
pdScript.onerror = () => preLoadStyle.remove();
document.head.appendChild(pdScript);
})();
</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

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

8. (Optional) Restrict Purple Dot's integration 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: () => {
const elem = document.querySelector('.gep-switcher-flag');
return elem && elem.firstChild.textContent === 'United Kingdom';
},
};

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

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