Save a customer design link with storefront JavaScript

Your storefront can create a link to the customer’s current design without opening the Share modal. Save the link with a cart, CRM record, or another process that needs the design.

A developer must add this integration to your storefront theme.

When to request a design link

Request the link immediately before you add the item to the cart or send the design to another system. The customer customiser captures the design when it receives the request.

Use this feature when your integration must keep the exact design for a later step. Use the visible Share feature when customers must copy the link themselves.

Before you start

• Confirm that your Store can go live and that its plan includes sharing.

• Ask a developer to add JavaScript to your storefront theme.

• Choose where your integration will save the complete design URL.

• Treat each design URL as sensitive. Anyone with the URL can open the saved design while the link remains valid.

The customer Share button does not have to be visible. An eligible Store can make a design-link request when the button is hidden.

How the request works

1. Your theme adds listeners for the success and failure events.

2. Your theme sends signCustomiserDesignLinkRequested with a unique requestId.

3. The customer customiser captures the current design and creates the link.

4. While its runtime remains mounted, the customer customiser sends one success or failure event with the same requestId.

5. Your theme saves the complete URL after success. It continues without a link after failure.

The request does not open the Share modal, move keyboard focus, or change the current customiser screen.

Add the storefront code

This example requests a design link and adds it to a Design Link cart attribute. It continues the cart flow if the request fails or takes more than 10 seconds.

function requestSignCustomiserDesignLink(callback) {
  var requestId =
    "cart-" + Date.now() + "-" + Math.random().toString(36).slice(2);
  var finished = false;
  var timeout = window.setTimeout(function () {
    finish(null);
  }, 10000);  function cleanup() {
    document.removeEventListener(
      "signCustomiserDesignLinkCreated",
      handleCreated,
    );
    document.removeEventListener(
      "signCustomiserDesignLinkFailed",
      handleFailed,
    );
    window.clearTimeout(timeout);
  }  function finish(url) {
    if (finished) {
      return;
    }    finished = true;
    cleanup();
    callback(url);
  }  function handleCreated(event) {
    if (!event.detail || event.detail.requestId !== requestId) {
      return;
    }    finish(event.detail.url);
  }  function handleFailed(event) {
    if (!event.detail || event.detail.requestId !== requestId) {
      return;
    }    finish(null);
  }  document.addEventListener(
    "signCustomiserDesignLinkCreated",
    handleCreated,
  );
  document.addEventListener(
    "signCustomiserDesignLinkFailed",
    handleFailed,
  );
  document.dispatchEvent(
    new CustomEvent("signCustomiserDesignLinkRequested", {
      detail: {
        requestId: requestId,
      },
    }),
  );
}function continueCartFlowWithDesignLink(cartAttributes, continueCartFlow) {
  requestSignCustomiserDesignLink(function (designUrl) {
    if (designUrl) {
      cartAttributes["Design Link"] = designUrl;
    }    continueCartFlow(cartAttributes);
  });
}

Connect continueCartFlow to your theme’s existing cart code. Change the cart attribute name only if your order process expects a different name.

Use the link safely

• Add both terminal event listeners before you send the request.

• Create a new requestId for each pending request.

• Match the returned requestId before you use the result.

• Save the complete url from the success event.

• Do not build a URL from token parts.

• Remove both listeners after success, failure, or timeout.

• Continue the cart flow without a link after failure or timeout.

• Do not log the design URL or send it to analytics.

• Do not click the customer Share button from JavaScript.

• Do not read, close, or remove the Share modal from JavaScript.

Handle a failed request

The signCustomiserDesignLinkFailed event includes one of these codes:

Do not save an empty or partial URL after a failure.

Read the event reference

See Storefront JavaScript events for the exact request, success, and failure payloads.

Use these events. Do not call the private shopper share endpoint from your theme.