Integrate into Shopify Headless Storefronts

This guide will walk you through Purple Dot's Platform integration into any Shopify Headless Storefront. If you are using our Shopify App, please see Installing our Shopify App instead. See Purple Dot Overview for the comparison of our Shopify App vs. Platform integrations.

Headless integration overview

Purple Dot integrates with your existing storefront and enables you to create pre-order experiences. When integrating with a headless storefront Purple Dot, provides a set of components that can be used to build the integration.

There are 5 key requirements an integration needs to implement:

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.
Adding pre-order items to cart. When adding an item to cart, the integration needs to determine if it is a pre-order, and attach the waitlist ID and ship dates if it is.
Showing pre-order items in cart. When a pre-order item is in the cart, the estimated ship dates need to be displayed.
Using the pre-order checkout. The Purple Dot pre-order checkout lets shoppers checkout with pre-order items. When a pre-order item is in the cart, the integration needs to direct the shopper to the Purple Dot pre-order checkout instead of the Shopify checkout.
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.

Purple Dot currently supports two types of carts:

Shopify AJAX API cart
Shopify Storefront API cart

Some aspects of the integration differ depending on what cart is being used.

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.

When a variant has an open waitlist, it will be set to “continue selling” in Shopify, and how it should be displayed is determined by the Pre-order availability API.

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 Shopify, and should be treated like a regular in-stock product.
ON_PREORDER state means the variant has an open waitlist and no stock in Shopify 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 Shopify. 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 endpoint. 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.

Adding pre-order items to cart

Whenever a pre-order item is added to cart, two line item properties must be added to it:

__releaseId, a hidden property whose value indicates which waitlist it's on. This is the id as returned by the 2 Pre-order availability API endpoints.
Purple Dot Pre-order, a property whose value has the estimated ship dates and that indicates that something is a pre-order. This is the display_dispatch_date as returned by the 2 Pre-order availability API endpoints.

Whenever an item is added to cart from anywhere on the site, it's pre-order status needs to be checked, and properties added if it is in ON_PREORDER or SOLD_OUT state (nothing needs to be done if it is NO_WAITLISTS or AVAILABLE_IN_STOCKstate).

If using the AJAX API cart, Purple Dot provides a pre-built component (see below) that can intercept all calls to the cart API and insert the required properties automatically.

If using the Storefront API, the integration must take care to always attach these properties when a pre-order item is added to cart.

Showing pre-order items in cart

When displaying items in the side cart or on a cart page, the Purple Dot Pre-order line item property should always be displayed. It indicates that the item is a pre-order and its estimated ship dates.

Most storefronts already display the cart item properties, so this should happen automatically. If not, you need to make sure the property is shown in the side cart and on the cart page.

Using the pre-order checkout

In order to hold pre-orders outside your downstream systems and for FTC compliance, the mirrored Purple Dot pre-order checkout is used when the shopper is checking out with pre-order items in their card. When a pre-order item is in the cart, the integration needs to direct the shopper to the Purple Dot checkout instead of the Shopify checkout. Purple Dot provides a pre-built component for checking the cart state (see below), which can be used to conditionally change any links to the checkout.

The pre-order checkout can be opened on any page as an overlay iframe, or it can be hosted on the cart page and opened conditionally on load.

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.

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.

When initialised, it will inject a <script> tag that loads additional code required to make Purple Dot work.

The package contains several modules structured like this:

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

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:

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:

Create a new page that can host the portal, e.g. /pages/manage-pre-orders
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.

Working with the cart

Purple Dot is compatible with several cart implementations:

Standard AJAX cart used by Liquid storefronts
Storefront API used by Hydrogen and headless storefronts
Custom cart implementations (coming soon)

In order for Purple Dot to be able to interact with your cart, an adapter must be provided. The library includes pre-built adapters for the AJAX and Storefront API carts. They should be passed in as configuration when initialising the library.

import { init } from '@purple-dot/browser';
import { ShopifyAJAXCart } from '@purple-dot/browser/shopify-ajax-cart';

PurpleDot.init({
  apiKey: '<Purple Dot API key>',
  cartAdapter: new ShopifyAJAXCart(),
});

import { init } from '@purple-dot/browser';
import { ShopifyStorefrontCart } from '@purple-dot/browser/shopify-storefront-cart';

PurpleDot.init({
  apiKey: '<Purple Dot API key>',
  cartAdapter: new ShopifyStorefrontCart(
    'your-store.myshopify.com',
    '<Storefront API public access token>'
  ),
});

Cart interceptors for AJAX API (`@purple-dot/browser/shopify-ajax-interceptors`)

Whenever a pre-order item is added to cart, from anywhere on the storefront, pre-order metadata must be added to it as line item properties. This can be achieved by making sure that anywhere that adds to cart accounts for pre-orders, or by intercepting and modifying all requests to the cart API. The interceptors package will use the provided cart adapter. It is used like:

import * as interceptors from '@purple-dot/browser/shopify-ajax-interceptors';

interceptors.start();

The library will intercept any requests to the cart API, use the pre-order state API to determine if an item is a pre-order, and add the required metadata. It adds two line item properties, __releaseId (hidden), which indicates the Purple Dot waitlist, and Purple Dot Pre-order which contains the ship dates, and should be shown in the side cart.

Cart state (`@purple-dot/browser/cart`)

In order to redirect the shopper to the Purple Dot pre-order checkout, we need to know if the cart contains a pre-order. That can be done like:

import { cartHasPreorderItem } from '@purple-dot/browser/cart';

// When using the AJAX cart API, cart is fetched automatically
if (await cartHasPreorderItem()) {
  // ...
}

// When using the Storefront cart API, a cart object has to be provided
if (await cartHasPreorderItem(cart)) {
  // ...
}

The library fetches the latest cart state from the cart using the configured adapter and check if it contains a pre-order item by inspect the line item properties and checking for the presence of __releaseId.

Pre-order checkout (`@purple-dot/browser/checkout`)

If the cart contains a pre-order item, the shopper has to checkout using the Purple Dot pre-order checkout instead of the standard Shopify checkout. The checkout loads as a full-page iframe and can be opened from any page on the site. If the storefront has a /cart page, the checkout should be opened on page load. The checkout will use the configured cart adapter and is opened like this:

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

// When using the AJAX cart API, cart id is determined automatically
await checkout.open();

// When using the Storefront cart API, cart id must be passed in
await checkout.open({ cartId: 'gid://Cart/...' });

PreviousMinimum Theme Requirements NextIntegrate into Shopify Hydrogen Storefronts

Last updated 1 year ago