Save a customer ShareLink with storefront JavaScript

Your storefront can create a ShareLink without opening the Share modal. Save the complete URL with the process that needs the design.

A developer must add this integration to your storefront theme.

When to request a ShareLink

Request the ShareLink immediately before the cart action or design transfer. The customer customiser captures the design when it receives the request.

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

Before you start

• Confirm that your Store can go live.

• Confirm that its plan includes sharing.

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

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

• Treat each ShareLink URL as sensitive. Anyone with the complete URL can open the design until it expires or you revoke it.

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

How the request works

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

2. Your theme sends signCustomiserShareLinkRequested with a unique requestId.

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

4. The runtime sends one terminal event with the same requestId while it remains mounted.

5. Your theme saves the complete URL after success.

6. Your theme continues without a ShareLink 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 ShareLink before an existing cart flow. It continues if the request fails or takes more than 10 seconds.

function requestSignCustomiserShareLink(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(
      "signCustomiserShareLinkCreated",
      handleCreated,
    );
    document.removeEventListener(
      "signCustomiserShareLinkFailed",
      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(
    "signCustomiserShareLinkCreated",
    handleCreated,
  );
  document.addEventListener(
    "signCustomiserShareLinkFailed",
    handleFailed,
  );
  document.dispatchEvent(
    new CustomEvent("signCustomiserShareLinkRequested", {
      detail: {
        requestId: requestId,
      },
    }),
  );
}function continueCartFlow() {
  requestSignCustomiserShareLink(async function (shareLinkUrl) {
    try {
      if (shareLinkUrl) {
        await saveShareLinkForCart(shareLinkUrl);
      }
    } finally {
      await continueToCart();
    }
  });
}

Connect saveShareLinkForCart and continueToCart to your existing cart code.

Use the ShareLink 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.

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

• Continue without a ShareLink after failure or timeout.

• Do not log the ShareLink URL.

• Do not send the ShareLink URL to analytics.

• Do not extract, build, or log token parts.

• Do not click the customer Share button from JavaScript.

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

The ShareLink access value is in the URL fragment. Store the complete returned URL without changes.

Each ShareLink expires 365 days after creation.

Revoke a ShareLink

Revoke a ShareLink when you must stop access before its expiry.

1. In merchant admin, select Shares.

2. Open the saved share.

3. Select Revoke ShareLink.

4. In the confirmation, select Revoke.

Anyone who has the ShareLink can no longer open the saved design. You cannot undo this action.

Handle a failed request

The signCustomiserShareLinkFailed 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 details.

Use these events for the integration. Do not call private ShareLink routes from your theme.