Integrate into another platform

While Purple Dot natively integrates with Shopify and Salesforce, it can be easily adapted to integrate with other e-commerce platforms by using our APIs and SDKs directly.

Platform integration overview

Purple Dot integrates with your existing storefront and enables you to create pre-order experiences.

Choose a Checkout Flow

Purple Dot supports a number of different checkout flows:

• Express: This checkout method presents a quick checkout modal to the shopper that opens directly when the Add to Cart button is clicked, so that the shopper can pre-order one or more of that item right away without any other products.

• Separate Bag: This checkout method is much like Express but adds a pre-order specific cart for the shopper to use to purchase multiple different pre-order items in one go. This comes with an additional pre-order cart component you can integrate into your store. This is a great option for situations in which a Shopper might want to pre-order multiple variants of the same product or products that go well together.

• Combined: This checkout method allows the shopper to add a pre-order item to their cart, but also continue shopping for other in-stock and pre-order items. When they are ready to checkout, they can be presented with a checkout that allows them to combine both pre-order and in-stock items at once, and choose to either ship them together or separately. This method is not publicly available on non-Shopify stores please contact Purple Dot support if you need this option.

If you are unsure which checkout flow your store is configured for, please reach out to Purple Dot Support to confirm, or to switch from one checkout method to another.

The integration requirements will differ slightly depending on which checkout method is chosen.

Express & separate bag

Overview

There are 3 key requirements an integration needs to implement for an Express checkout:

• Displaying pre-order items. Purple Dot is the source of data for which items are on pre-order and their estimated ship dates. The integration needs to show that those items are on pre-order, with the estimated ship dates, the "Learn more” informational content and a “Pre-order” call to action.

• Using the Express pre-order checkout. When pre-ordering an item, instead of adding the item to the cart, the integration needs to launch our Express checkout modal and provide the variant ID, release ID, currency, and quantity.

• Embedding the Shopper portal. The shopper self-service portal lets shoppers manage their pre-orders. The integration needs to be embedded on a page in the storefront that the shoppers will be directed to in their confirmation email.

Displaying pre-order items

Purple Dot is the source of data for which items are on pre-order and their estimated ship dates. The Pre-order availability API can be queried for the pre-order status of any product or variant on the store.

Anywhere a product can be added to cart (on product pages, or collection pages and elsewhere with add to cart controls) we need to decide whether the product is in stock, sold out or on pre-order. To help with this we provide an extensible product availability API which you can use to check the state of the item.

Pre-order pages

On pre-order pages you should check the active variant against the availability API. If it is on pre-order you must show the Pre-order CTA, required estimated shipping dates, and Purple Dot branding to the shopper.

Collection pages

On collection pages and in any situation in which you display a "product" rather than individual variants you may wish to display a specific "Pre-order" label on the item. The availability API can be used for this by calling it with a product handle or identifier rather than a variant.

Purchasing pre-order items

Once you've used the availability API to determine the correct state for the item, you need to trigger Purple Dot whenever the Shopper interacts with the Pre-order button via our Checkout API.

For Express this will display an overlay with the first page of the pre-order checkout for the Shopper to buy the item. For separate bag this will display the shoppers pre-order cart where they can add and remove any items before continuing to checkout.

Shopper self-service

We also provide Shoppers with self-service tools for managing their pre-order such as cancelling items, or updating their payment method. This can be integrated on any page you like within your store using our SDK.

@purple-dot/browser

Purple Dot provides an npm package that includes the components needed for the integration. It must be included and initialised whenever the storefront is loaded, likely in the root layout of your storefront application.

npm install -S @purple-dot/browser

import * as PurpleDot from '@purple-dot/browser';

PurpleDot.init({
  apiKey: '$YOUR_API_KEY',
});

💡 Your API key can be found in the Merchant Portal under Settings > Integration.

You can find examples of using the SDK here github.com/purple-dot/browser-examples.

@purple-dot/browser/availability

The pre-order availability API should be used for determining if a product or a variant should be displayed as a pre-order and the estimated ship dates if so.

Purple Dot provides a client library that can be used like:

import * as PurpleDot from '@purple-dot/browser';
import { availability } from '@purple-dot/browser/availability';

async function inStockInMyStore({ variantId }) {
    const response = await fetch(`/your/api/product.json?variant=${variantId}`);
    const data = response.json();
    
    // Return a truthy value when the item is In Stock.
    
    return data.quantity;
}

const preorderState = await availability({
  variantId: variant.id
}, inStockInMyStore);

The availability call takes 2 arguments

• request: An object with either a variantId or productHandle property indicating the item to look up the preorder state for.

• inStockCallback (optional): A callback used to check if the item is instock against your own inventory system before checking the preorder status.

The result is and object with this shape

• state

  • AVAILABLE_IN_STOCK

    • The variant is available in stock and should not be sold as a pre-order.

  • ON_PREORDER

    • The variant is available as a pre-order only.

  • SOLD_OUT

    • The variant is neither available in stock or on a pre-order.

• waitlist (if state is ON_PREORDER)

  • id - the waitlist ID

  • display_dispatch_date - the estimated ship date to display for the variant if on pre-order

@purple-dot/browser/checkout

This module provides access to the Purple Dot checkout APIs so that you can open the checkout and items to the separate bag.

To start an Express checkout use

openExpressCheckout(variantId, releaseId, currency, quantity);

To add an item to the Separate Cart use

addItem(variantId, releaseId, currency, quantity);

Learn more component

When a variant is on pre-order, the estimated ship dates and the “Pre-order protected by” branding must be displayed near the “Pre-order” call to action. Purple Dot provides a Web Component that can be used with any JS framework.

Simply place a <purple-dot-learn-more /> HTML element near the Pre-order button.

Separate pre-order bag

When using the Separate Bag checkout you will probably want to show the shopper a separate pre-order cart next to your normal in stock item cart in your navigation. To support this we provide a <purple-dot-separate-bag /> component which can be customised to fit the look and feel of your store.

This component comes with some default styling but you are free to add your own elements inside it which will override our defaults. The element will automatically have some attributes to help you style it as desired.

• The data-item-count attribute will always be set to the current number of items in the pre-order cart.

• When the shopper has pre-order items in the cart class="purple-dot-separate-bag--has-items" will be added to the element.

You should use these to do things like hide the separate cart element when the cart is empty, or to indicate the number of items in the bag to the shopper.

Shopper self-service portal component

Purple Dot provides a portal where shoppers can manage their pre-orders. The portal can be embedded onto any page in your storefront:

1. Create a new page that can host the portal, e.g. /account/manage-pre-orders

2. Place a <purple-dot-self-service /> component where you would like the self service iframe to appear. This component is framework-agnostic and is compatible with all popular frameworks like React and Vue.