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 that single item right away.

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

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 checkout integration

Express checkout overview

Prerequisites: The Express checkout relies on Purple Dot's backend having up-to-date information about your product catalog, pricing, and inventory information, as well as means to export pre-orders into your Order Management System (OMS) and transfer payments when the time comes to fulfill pre-orders. For e-commerce platforms outside of Purple Dot and Salesforce, this will likely require either a custom integration or a third-party Integration-Platform-as-a-Service (iPaaS) to synchronize data between systems.

Please reach out to Purple Dot's Activation team to inquire about setting this up.

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.

Product pages

Anywhere a product can be added to cart - on product pages, or collection pages and elsewhere with add to cart controls - the integration should use the variant's pre-order state provided by the Pre-order availability API to determine how a variant should be treated. There are 4 possible states:

  • NO_WAITLISTS state means the variant has no open waitlists and no changes need to be made.

  • AVAILABLE_IN_STOCK state means the variant has an open waitlist but also has stock available in your inventory management system, and should be treated like a regular in-stock product.

  • ON_PREORDER state means the variant has an open waitlist and no stock in inventory, and should be treated as a pre-order. The following should be shown:

    • Change the add to cart button label to “Pre-order”, if the button has a label.

    • Show the estimated ship dates. This is the display_dispatch_date as returned by the 2 Pre-order availability API endpoints.

    • Show the Learn more component near the button.

  • SOLD_OUT state means the variant has an open waitlist but no stock in Purple Dot or your inventory. The add to cart button must be disabled and the label should be changed to “Sold out”.

Whenever a new variant is selected, for example using a size or colour picker, the Pre-order availability API state should be used to determine how to display the newly selected variant. For products with multiple variants, it is possible for some variants to be on pre-order while others are in-stock or sold out.

Collection pages

On collection pages and in any panels that list products, the integration may show a “Pre-order” label for products that are fully on pre-order, using the state provided by the product pre-order state API. The possible states are the same as for a single variant, but take into account all of the product's variants, and are therefore suitable for cases where no variant is selected.

Using the Express pre-order checkout

When a shopper clicks the Pre-order button, instead of adding the pre-order item to the cart, launch the Purple Dot Express checkout for just that specific item.

Purple Dot provides a pre-built component that will launch the checkout on the page as an overlay iframe.

Embedding the Shopper portal

The shopper portal is an iframe that embeds a portal that lets shoppers manage their pre-orders. The integration must embed the shopper portal component on a dedicated page, so that shoppers can be linked to it from their confirmation emails.

Components

Purple Dot provides a package that includes the components needed for the integration. It can be installed from npm, and 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: 'xxx',
});

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

Pre-order availability API

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 api from '@purple-dot/browser/api';

const variantResponse = await api.fetchVariantsPreorderState(variant.id);

const productResponse = await api.fetchProductsPreorderState(product.handle);

  • variantPreorderState provides data on the pre-order state of any variant. It should be used when interacting with a specific variant, such as on a product page. It returns:

    • state, one of:

      • NO_WAITLISTS - the variant has no open waitlists and no pre-order related functionality should trigger

      • AVAILABLE_IN_STOCK - the variant is available in stock and should not be sold as a pre-order (even though there is an open waitlist)

      • ON_PREORDER - the variant is available as a pre-order only

      • SOLD_OUT - the variant is completely sold out, in stock and on pre-order

    • waitlist

      • id - the waitlist ID

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

  • productPreorderState provides data on the pre-order state of a whole product. It can be used in contexts where no variant is selected, such as on a collection page. It returns:

    • state, one of:

      • NO_WAITLISTS - the product has no open waitlists and no pre-order related functionality should trigger

      • AVAILABLE_IN_STOCK - the product has some variants available in stock, and should be displayed as a regular in-stock product

      • ON_PREORDER - the product has all variants available on pre-order, and should be displayed as a pre-order product

      • SOLD_OUT - the product is completely sold out

    • waitlist

      • id - the waitlist ID

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

Express checkout component

Instead of adding a pre-order item to a cart, the Express checkout allows the shopper to pre-order a single item right away. The Express checkout modal should be launched within a click handler for the Add To Cart/Pre-order button:

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

// Get the pre-order button element
const preorderButton = document.getElementById("preorderButton");

// Add an event listener for the button's "click" event
preorderButton.addEventListener("click", function() {
  await checkout.openExpressCheckout({
    variantId: '41234567890...',   // Product variant ID as a string
    releaseId: 'f47ac10b-58cc...', // Purple Dot release ID from variantPreorderState.waitlist
    currency: 'USD',               
    quantity: 1,                   // 1, or the value from a quantity selector if there is one
  });
});

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 like this:

  1. Place a <purple-dot-learn-more /> HTML element anywhere in the DOM. This component is framework-agnostic and is compatible with all popular frameworks like React and Vue.

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. /pages/manage-pre-orders

  2. Place a <purple-dot-self-service /> HTML element 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.

PreviousUpgrading to 2024-08-29NextPublic API

Last updated