Shopware

Shopware can be connected to Stella with a lightweight custom integration. In most projects this consists of five steps: provide a product feed, load our shop components, trigger purchase events, create one or more entry points for the analysis, and optionally wire up add-to-cart behavior on the result page.

Provide a product feed

Our ShopwareProvider expects a CSV product feed that is compatible with our system. Use ; as delimiter, make sure the header row is present, encode the file as UTF-8, and use standard CSV quoting for values that may contain semicolons, quotes, or line breaks.

Each CSV row represents one product variant. Variants are grouped into one product by parentId. For single-variant products, just leave the parentId field empty.

Required header columns

Optional mapped columns

Any additional CSV columns are preserved as metafields and can assist our DataAI in understanding your products better. Keep the file reasonably small though, since we need to download and process it on every sync.

To get the best product and variant naming split, format name values like Product Name - Variant Name, Product Name: Variant Name, or another predictable shared-prefix pattern.

For price and compareAtPrice, use a dot as decimal separator, for example 12.99. Invalid color values are ignored.

Integrate the shop components

The shortest integration is to load our script in the header of your storefront (use defer for best performance).

<script defer src="https://cdn.askstella.ai/scripts/shop-components-latest.js"></script>

Alternatively, you can set window.STELLA_AI.COMPANY_ID before loading the script. This is optional, but it can slightly improve loading speed and helps when the integration is running on another domain, for example on test systems.

Loading the script with createElement can also be useful when the integration is managed through a tag manager.

Example:

<script>
  window.STELLA_AI = { COMPANY_ID: "your-company-id" };

  (function () {
    if (window.__STELLA_AI_SHOP_COMPONENTS_LOADED__) return;
    window.__STELLA_AI_SHOP_COMPONENTS_LOADED__ = true;

    var script = document.createElement("script");
    script.src = "https://cdn.askstella.ai/scripts/shop-components-latest.js";
    script.defer = true;
    document.head.appendChild(script);
  })();
</script>

Important for single page applications (SPA)

If your Shopware frontend changes the URL without a full page reload, you must dispatch stellaOnRouteChange after every route change so our components can refresh for the new page.

window.dispatchEvent(new CustomEvent("stellaOnRouteChange"));

More details about global settings and frontend events can be found in the developer documentation.

Trigger purchase events

To let Stella track purchases of recommended products, dispatch the stellaPurchaseCompleted event after a successful checkout in the frontend.

window.dispatchEvent(new CustomEvent("stellaPurchaseCompleted", {
  detail: {
    currency: "EUR",
    total_discounts: 0,
    total_line_items_price: 24,
    total_price: 28.99,
    total_tax: 0,
    total_shipping_price: 3.99,
    line_items: [
      {
        name: "Dramatic Length Mascara - Brown",
        product_id: "41250",
        variant_id: "41250",
        price: 24.0,
        quantity: 1,
        total_discount: 0
      }
    ]
  }
}));

Shopware usually does not have separate variant IDs, so you can set product_id and variant_id to the same value. Those IDs must match the IDs we receive through your product feed.

Create entry points

1. Create a dedicated landing page in Shopware and link it in your main navigation as something like Beauty Consultation. On that page you can embed the analysis directly with <stella-analysis />. For more information, see the relevant documentation.

   <stella-analysis />

2. Add a CTA on product pages where users typically need help, for example Find your shade or Find my perfect color match. The CTA can open the analysis in a popup with the funnel subdomain you want to use.

   window.stellaAnalysisPopup.open("my-funnel");

   If you need more context on embedded analysis components or popup behavior, see the technical documentation.

3. A third and usually very prominent entry point is our widget or FAB button. There is nothing to implement on the Shopware side for this. Both can be configured directly in our platform and then appear automatically in the storefront.

Add to cart (optional)

If you want the add-to-cart buttons on Stella's result page to work inside your Shopware storefront, we need a JavaScript command that adds an item to your cart. That command can then be configured in the respective field of your funnel settings.

The exact implementation depends on how your Shopware storefront or custom theme handles cart updates, so this step is optional and often handled together with your agency or development team. If needed, we can help you wire this up.

If this is not available yet, you can keep the add-to-cart buttons disabled until the cart command has been implemented.