Attribute orders

ShopAssist reports two levels of credit:

On Shopify and WooCommerce the plugin writes this onto the cart and it reaches the order by itself. On a custom storefront the widget cannot see your cart, so you carry it across.

What the widget records

The widget puts the session in two places:

• The page URL, as ?sa=<session id>&sa_attr=generated|influenced.
• sessionStorage, under shopassist_session.

Product links it renders carry the same parameters, so a shopper who arrives on a product page from the chat brings the session with them.

Carrying it into checkout

Read the session when the shopper buys and attach it to the order:

import { getAttribution } from "@shopassist/js";

async function checkout() {
  const { sessionId, attribution } = getAttribution();
  if (sessionId) {
    await cart.setAttributes({
      _session_id: sessionId,
      _attribution: attribution,
    });
  }
  return goToCheckout();
}

sessionId is null when the shopper never opened the chat, which is the normal case for most orders. Skip the attributes rather than sending empty ones.

On headless Shopify

Forward the session into the Shopify cart as a cart attribute. Cart attributes persist onto the order at checkout, which is what the ShopAssist dashboard reads.

await storefront.mutate(CART_ATTRIBUTES_UPDATE, {
  variables: {
    cartId,
    attributes: [
      { key: "_session_id", value: sessionId },
      { key: "_attribution", value: attribution },
    ],
  },
});

If you already use the cart bridge, the widget hands you the same pair as properties on every add, and you can attach it there instead.

Reading the parameters yourself

getAttribution() prefers the URL over stored state, and returns null for an sa_attr value it does not recognise, so you can pass its output through without validating it.

getAttribution();
// { sessionId: "s_01H…", attribution: "generated" }