> ## Documentation Index
> Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect another store platform

> Send products and orders from Shopware, Salla, PrestaShop, Wix or your own backend, directly or through n8n or Make, so your store gets bestsellers, customer signals and product picks.

SegmentFlow\.ai learns from a store's own orders: which products sell, when each customer usually orders again, and which products to show each customer in an email. Shopify and WooCommerce stores send their orders through their integration. A store on any other platform gets the same features once it sends two things through the API:

* its **products**, by its own product IDs, through the [catalog products](https://segmentflow.ai/docs/catalog-products.md) endpoints;
* its **paid orders and refunds**, with the products in them, through the [order transactions](https://segmentflow.ai/docs/order-transactions.md) endpoints.

Platforms can't call these endpoints straight from their webhook settings: their webhook bodies have their own shape, and they don't send your API key. Put a small mapping step in between. It can be your own backend or a serverless function, an [n8n](#connect-through-n8n) workflow, or a [Make](#connect-through-make) scenario. This guide shows the requests, then the mapping for a Shopware 6 and a Salla order.

## What to send when

| When this happens in your store | Send |
| - | - |
| You connect the store | All products with `POST /api/v1/catalog-products/batch`, then past orders marked `historical`. |
| A product is created or changed | `PUT /api/v1/catalog-products/by-external-id/{externalId}` with the whole product. |
| A product is deleted | `POST /api/v1/catalog-products/by-external-id/{externalId}/archive`. |
| An order is paid | `POST /api/v1/events/order-transactions` with `"type": "order"` and its line items. |
| An order is refunded | `POST /api/v1/events/order-transactions` with `"type": "refund"` and the refunded items or amount. |

## Before you start

* **An API key.** An owner or admin creates one in **Settings → API Keys** with the scopes **Track events** (`events:write`), **Write catalog products** (`catalog-products:write`) and **Read catalog products** (`catalog-products:read`). Keep it on your server or in your automation tool's credentials, never in a storefront.
* **A source name.** Every order carries a `source`: your store's name, such as `ember-hill` or `salla:482100731`. Use the same name every time. With `orderId` it identifies the order, so sending an order again updates it.
* **One product ID on both sides.** An order item matches a product when its `productId` is the `externalId` you sent the product with. When an order item has no product ID, it matches the product with the same `sku`. Use the ID your platform puts on order lines. If those lines carry a variant ID, send the parent product's ID as `productId` and the variant as `variantId`, or send each variant as its own product.

## 1. Send your products

Send every product once, in batches of up to 100. A batch is saved as a whole: if one product is invalid, the request fails with `400` and nothing is saved.

```json POST /api/v1/catalog-products/batch theme={null}
{
  "products": [
    {
      "externalId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a01",
      "title": "Ethiopia Yirgacheffe, 250 g",
      "description": "<p>Washed coffee with notes of jasmine and lemon.</p>",
      "price": "14.90",
      "currency": "EUR",
      "productUrl": "https://shop.example.com/products/ethiopia-yirgacheffe",
      "imageUrl": "https://cdn.shop.example.com/ethiopia-yirgacheffe.jpg",
      "category": "Coffee",
      "tags": ["single origin", "light roast"],
      "sku": "EH-ETH-250"
    },
    {
      "externalId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a02",
      "title": "Colombia Huila, 250 g",
      "price": "13.50",
      "currency": "EUR",
      "productUrl": "https://shop.example.com/products/colombia-huila",
      "imageUrl": "https://cdn.shop.example.com/colombia-huila.jpg",
      "category": "Coffee",
      "sku": "EH-COL-250"
    },
    {
      "externalId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a03",
      "title": "Paper filters, 100 pack",
      "price": "5.90",
      "currency": "EUR",
      "productUrl": "https://shop.example.com/products/paper-filters",
      "imageUrl": "https://cdn.shop.example.com/paper-filters.jpg",
      "category": "Brewing",
      "sku": "EH-FIL-100"
    },
    {
      "externalId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a04",
      "title": "Ceramic dripper",
      "price": "29.00",
      "compareAtPrice": "34.00",
      "currency": "EUR",
      "productUrl": "https://shop.example.com/products/ceramic-dripper",
      "imageUrl": "https://cdn.shop.example.com/ceramic-dripper.jpg",
      "category": "Brewing",
      "sku": "EH-DRP-01"
    },
    {
      "externalId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a05",
      "title": "Enamel mug",
      "price": "12.00",
      "currency": "EUR",
      "productUrl": "https://shop.example.com/products/enamel-mug",
      "imageUrl": "https://cdn.shop.example.com/enamel-mug.jpg",
      "category": "Mugs",
      "sku": "EH-MUG-01"
    }
  ]
}
```

After that, send each product when your platform says it was created or changed. Each request sends the whole product: fields you leave out are cleared. The response is `201` for a new product and `200` for an update.

```json PUT /api/v1/catalog-products/by-external-id/0191a1e6f1d47c3b9a2e5d8c4b7f6a06 theme={null}
{
  "title": "Hand grinder",
  "description": "Ceramic burrs, 30 g hopper.",
  "price": "59.00",
  "currency": "EUR",
  "productUrl": "https://shop.example.com/products/hand-grinder",
  "imageUrl": "https://cdn.shop.example.com/hand-grinder.jpg",
  "category": "Brewing",
  "tags": ["grinder"],
  "sku": "EH-GRN-01"
}
```

When a product is deleted, archive it. Archived products stop appearing in emails; sending the product again with `PUT` makes it active again.

```bash theme={null}
curl -X POST \
  "https://api.segmentflow.ai/api/v1/catalog-products/by-external-id/0191a1e6f1d47c3b9a2e5d8c4b7f6a05/archive" \
  -H "x-api-key: $SEGMENTFLOW_API_KEY"
```

To take a product out of emails without archiving it, send it with `"status": "hidden"`.

## 2. Import past orders

Send the orders from before you connected, up to 100 per request, with `"historical": true`. They count for revenue, bestsellers, customer signals and product picks, but they never start a Journey or send an email. A year of orders is enough: product picks read the last 365 days.

```json POST /api/v1/events/order-transactions/batch theme={null}
{
  "transactions": [
    {
      "type": "order",
      "source": "ember-hill",
      "orderId": "9001",
      "occurredAt": "2026-09-14T08:12:00+00:00",
      "currency": "EUR",
      "totals": { "total": 25.7, "subtotal": 20.8, "shipping": 4.9 },
      "customer": { "email": "bea@example.com", "externalCustomerId": "10011" },
      "lineItems": [
        {
          "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a01",
          "sku": "EH-ETH-250",
          "title": "Ethiopia Yirgacheffe, 250 g",
          "quantity": 1,
          "unitPrice": 14.9
        },
        {
          "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a03",
          "sku": "EH-FIL-100",
          "title": "Paper filters, 100 pack",
          "quantity": 1,
          "unitPrice": 5.9
        }
      ],
      "historical": true
    },
    {
      "type": "order",
      "source": "ember-hill",
      "orderId": "9002",
      "occurredAt": "2026-09-28T16:40:00+00:00",
      "currency": "EUR",
      "totals": { "total": 25.7, "subtotal": 20.8, "shipping": 4.9 },
      "customer": {
        "email": "chris@example.com",
        "externalCustomerId": "10017"
      },
      "lineItems": [
        {
          "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a01",
          "sku": "EH-ETH-250",
          "title": "Ethiopia Yirgacheffe, 250 g",
          "quantity": 1,
          "unitPrice": 14.9
        },
        {
          "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a03",
          "sku": "EH-FIL-100",
          "title": "Paper filters, 100 pack",
          "quantity": 1,
          "unitPrice": 5.9
        }
      ],
      "historical": true
    },
    {
      "type": "order",
      "source": "ember-hill",
      "orderId": "9003",
      "occurredAt": "2026-10-15T19:22:00+00:00",
      "currency": "EUR",
      "totals": { "total": 42.5, "subtotal": 42.5, "shipping": 0 },
      "customer": {
        "email": "dana@example.com",
        "externalCustomerId": "10023"
      },
      "lineItems": [
        {
          "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a02",
          "sku": "EH-COL-250",
          "title": "Colombia Huila, 250 g",
          "quantity": 1,
          "unitPrice": 13.5
        },
        {
          "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a04",
          "sku": "EH-DRP-01",
          "title": "Ceramic dripper",
          "quantity": 1,
          "unitPrice": 29
        }
      ],
      "historical": true
    }
  ]
}
```

Each transaction gets its own result, in request order. A rejected one doesn't stop the others. If a request fails part way, send the whole batch again: transactions already stored come back as `unchanged`.

## 3. Send new orders and refunds

From now on, send each order once it is paid. If your platform creates orders before payment, for example for bank transfer or cash on delivery, send the order when its payment status changes to paid. Leave out lines that aren't products, such as shipping, discounts and gift cards: they belong in `totals`.

Check the webhook's signature before you trust its body. Shopware signs app webhooks in the `shopware-shop-signature` header and Salla in `X-Salla-Signature`, each as an HMAC-SHA256 of the raw body with your app's secret.

### A Shopware 6 order

A Shopware app receives the order in the `checkout.order.placed` webhook. This is an abridged body; see Shopware's [app webhook documentation](https://developer.shopware.com/docs/guides/plugins/apps/) for the full one. If your store takes payment after checkout, subscribe to `state_enter.order_transaction.state.paid` instead and read the order from the Admin API.

```json Shopware 6 checkout.order.placed webhook (abridged) theme={null}
{
  "data": {
    "event": "checkout.order.placed",
    "payload": {
      "order": {
        "orderNumber": "10024",
        "orderDateTime": "2026-11-20T09:58:12.000+00:00",
        "currency": { "isoCode": "EUR" },
        "amountTotal": 46.2,
        "positionPrice": 41.3,
        "shippingTotal": 4.9,
        "orderCustomer": {
          "email": "alex@example.com",
          "customerNumber": "10042",
          "firstName": "Alex",
          "lastName": "Tamm"
        },
        "lineItems": [
          {
            "type": "product",
            "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a01",
            "label": "Ethiopia Yirgacheffe, 250 g",
            "quantity": 2,
            "unitPrice": 14.9,
            "totalPrice": 29.8,
            "payload": { "productNumber": "EH-ETH-250" }
          },
          {
            "type": "product",
            "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a07",
            "label": "Holiday blend, 250 g",
            "quantity": 1,
            "unitPrice": 11.5,
            "totalPrice": 11.5,
            "payload": { "productNumber": "EH-HOL-250" }
          }
        ]
      }
    }
  },
  "source": {
    "url": "https://shop.example.com",
    "appVersion": "1.0.0",
    "shopId": "aBcD1234eFgH"
  },
  "timestamp": 1795168693
}
```

This function turns a Shopware order into an order transaction. It has no dependencies, so it runs in Node.js, a serverless function or an n8n Code node. Pass `{ historical: true }` when you map past orders for the import.

```js shopware-order.js theme={null}
function shopwareOrderToSegmentflow(order, { historical = false } = {}) {
  return {
    type: "order",
    source: "ember-hill",
    orderId: order.orderNumber,
    occurredAt: order.orderDateTime,
    currency: order.currency.isoCode,
    totals: {
      total: order.amountTotal,
      subtotal: order.positionPrice,
      shipping: order.shippingTotal,
    },
    customer: {
      email: order.orderCustomer.email,
      externalCustomerId: order.orderCustomer.customerNumber,
    },
    lineItems: order.lineItems
      .filter((item) => item.type === "product")
      .map((item) => ({
        productId: item.productId,
        sku: item.payload.productNumber,
        title: item.label,
        quantity: item.quantity,
        unitPrice: item.unitPrice,
      })),
    historical,
  };
}
```

For the webhook above, it returns this request:

```json POST /api/v1/events/order-transactions theme={null}
{
  "type": "order",
  "source": "ember-hill",
  "orderId": "10024",
  "occurredAt": "2026-11-20T09:58:12.000+00:00",
  "currency": "EUR",
  "totals": { "total": 46.2, "subtotal": 41.3, "shipping": 4.9 },
  "customer": { "email": "alex@example.com", "externalCustomerId": "10042" },
  "lineItems": [
    {
      "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a01",
      "sku": "EH-ETH-250",
      "title": "Ethiopia Yirgacheffe, 250 g",
      "quantity": 2,
      "unitPrice": 14.9
    },
    {
      "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a07",
      "sku": "EH-HOL-250",
      "title": "Holiday blend, 250 g",
      "quantity": 1,
      "unitPrice": 11.5
    }
  ],
  "historical": false
}
```

The response says whether the order is new (`created`), changed (`updated`) or a retry (`unchanged`), and which Profile it belongs to. The holiday blend was never sent as a product, so it [matches no product](#4-check-that-it-works).

### A Salla order

Salla sends the order in the `order.created` webhook. This is an abridged body; see Salla's [webhook documentation](https://docs.salla.dev/) for the full one. Salla gives the store's local time without an offset, so the function adds the store's UTC offset. Its order lines carry a SKU, so the order items match products by `sku`.

```json Salla order.created webhook (abridged) theme={null}
{
  "event": "order.created",
  "merchant": 482100731,
  "created_at": "2026-11-19 17:05:31",
  "data": {
    "id": 1739204871,
    "reference_id": 21307,
    "date": {
      "date": "2026-11-19 17:05:31.000000",
      "timezone_type": 3,
      "timezone": "Asia/Riyadh"
    },
    "currency": "SAR",
    "amounts": {
      "sub_total": { "amount": 77, "currency": "SAR" },
      "shipping_cost": { "amount": 15, "currency": "SAR" },
      "total": { "amount": 92, "currency": "SAR" }
    },
    "customer": {
      "id": 873045,
      "first_name": "Sara",
      "last_name": "Al-Harbi",
      "email": "sara@example.com"
    },
    "items": [
      {
        "name": "Colombia Huila, 250 g",
        "sku": "EH-COL-250",
        "quantity": 1,
        "amounts": { "price_without_tax": { "amount": 54, "currency": "SAR" } }
      },
      {
        "name": "Paper filters, 100 pack",
        "sku": "EH-FIL-100",
        "quantity": 1,
        "amounts": { "price_without_tax": { "amount": 23, "currency": "SAR" } }
      }
    ]
  }
}
```

```js salla-order.js theme={null}
// Salla sends the store's local time. This store is in Riyadh (UTC+3).
const STORE_UTC_OFFSET = "+03:00";

function sallaOrderToSegmentflow(webhook) {
  const order = webhook.data;
  return {
    type: "order",
    source: `salla:${webhook.merchant}`,
    orderId: String(order.reference_id),
    occurredAt: `${order.date.date.slice(0, 19).replace(" ", "T")}${STORE_UTC_OFFSET}`,
    currency: order.currency,
    totals: {
      total: order.amounts.total.amount,
      subtotal: order.amounts.sub_total.amount,
      shipping: order.amounts.shipping_cost.amount,
    },
    customer: {
      email: order.customer.email,
      externalCustomerId: String(order.customer.id),
    },
    lineItems: order.items.map((item) => ({
      sku: item.sku,
      title: item.name,
      quantity: item.quantity,
      unitPrice: item.amounts.price_without_tax.amount,
    })),
  };
}
```

```json POST /api/v1/events/order-transactions theme={null}
{
  "type": "order",
  "source": "salla:482100731",
  "orderId": "21307",
  "occurredAt": "2026-11-19T17:05:31+03:00",
  "currency": "SAR",
  "totals": { "total": 92, "subtotal": 77, "shipping": 15 },
  "customer": { "email": "sara@example.com", "externalCustomerId": "873045" },
  "lineItems": [
    {
      "sku": "EH-COL-250",
      "title": "Colombia Huila, 250 g",
      "quantity": 1,
      "unitPrice": 54
    },
    {
      "sku": "EH-FIL-100",
      "title": "Paper filters, 100 pack",
      "quantity": 1,
      "unitPrice": 23
    }
  ]
}
```

### A refund

Send each refund as its own transaction that names its order. Give every refund its own `refundId`, and list the refunded items, or send only `amount` for a refund of an amount such as shipping. Without `customer`, the refund belongs to the customer of the stored order.

```json POST /api/v1/events/order-transactions theme={null}
{
  "type": "refund",
  "source": "ember-hill",
  "orderId": "9003",
  "refundId": "9003-R1",
  "occurredAt": "2026-10-20T12:00:00+00:00",
  "currency": "EUR",
  "lineItems": [
    {
      "productId": "0191a1e6f1d47c3b9a2e5d8c4b7f6a04",
      "sku": "EH-DRP-01",
      "title": "Ceramic dripper",
      "quantity": 1,
      "unitPrice": 29
    }
  ]
}
```

Refunded items stop counting as bought: the dripper above is no longer a bestseller, and its buyer won't see it picked as something they already have.

### Retries

Every request on this page is safe to send again. A product is keyed by its `externalId`, an order by `source` and `orderId`, and a refund by its `refundId` as well. Retry on a network error, `429` and `5xx`. Don't retry a `400`: fix the payload, and read `details.issues[].path` for the field. Send a refund after its order; a refund without `customer` for an order that isn't stored yet fails with `order_not_found`.

## Connect through n8n

**1. Receive the webhook**

Add a **Webhook** node with the method `POST` and copy its production URL into your platform's webhook settings, for example the Shopware app manifest or the Salla Partners app. Check the platform's signature first; n8n's **Crypto** node computes the HMAC.

**2. Map the order**

Add a **Code** node in **Run Once for Each Item** mode. Paste the mapping function from above, then return the mapped order:

```js theme={null}
return { json: shopwareOrderToSegmentflow($json.body.data.payload.order) };
```

**3. Send it to SegmentFlow\.ai**

Add an **HTTP Request** node:

* **Method:** `POST`
* **URL:** `https://api.segmentflow.ai/api/v1/events/order-transactions`
* **Authentication:** Generic credential type, **Header Auth**, with the name `x-api-key` and your API key as the value
* **Send Body:** on, **Body Content Type** JSON, **Specify Body** Using JSON, with `{{ JSON.stringify($json) }}`

In the node's settings, turn on **Retry On Fail**.

Build a second workflow the same way for product webhooks, with a `PUT` to `/api/v1/catalog-products/by-external-id/{{ $json.externalId }}`. For the import, a workflow can page through your platform's API, map each order with `{ historical: true }`, and send batches of 100 to `/api/v1/events/order-transactions/batch`.

## Connect through Make

**1. Receive the webhook**

Start a scenario with **Webhooks → Custom webhook** and copy its address
into your platform's webhook settings. Send one test order so Make learns
the payload's structure.

**2. Build the line items**

Add **Flow Control → Iterator** over the order's line items, then **Flow
Control → Array aggregator** into a data structure with `productId`, `sku`,
`title`, `quantity` and `unitPrice`. Add a **Filter** after the iterator to
keep only product lines.

**3. Build the order**

Add **JSON → Create JSON** with a data structure of the order fields from
step 3: `type`, `source`, `orderId`, `occurredAt`, `currency`, `totals`,
`customer` and `lineItems`. Map the aggregated array to `lineItems`.

**4. Send it to SegmentFlow\.ai**

Add **HTTP → Make a request** with the method `POST`, the URL
`https://api.segmentflow.ai/api/v1/events/order-transactions`, a header
`x-api-key` with your API key, **Body type** Raw, **Content type** JSON
(application/json), and the JSON string as the request content. Turn on
**Parse response**, and add an error handler with **Break** so Make retries
failed runs.

## Connect from your own backend

If you already run a backend, receive the webhook there. This Express handler checks a Shopware app webhook's signature, maps the order with the function above and sends it:

```ts theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/shopware",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const expected = createHmac("sha256", process.env.SHOPWARE_APP_SECRET!)
      .update(req.body)
      .digest();
    const received = Buffer.from(
      req.get("shopware-shop-signature") ?? "",
      "hex",
    );
    if (
      received.length !== expected.length ||
      !timingSafeEqual(received, expected)
    ) {
      return res.sendStatus(401);
    }

    const webhook = JSON.parse(req.body.toString("utf8"));
    if (webhook.data.event !== "checkout.order.placed")
      return res.sendStatus(204);

    const response = await fetch(
      "https://api.segmentflow.ai/api/v1/events/order-transactions",
      {
        method: "POST",
        headers: {
          "content-type": "application/json",
          "x-api-key": process.env.SEGMENTFLOW_API_KEY!,
        },
        body: JSON.stringify(
          shopwareOrderToSegmentflow(webhook.data.payload.order),
        ),
      },
    );
    // A 5xx answer makes the platform deliver the webhook again.
    res.sendStatus(response.status >= 500 ? 502 : 200);
  },
);
```

## 4. Check that it works

SegmentFlow\.ai calculates bestsellers, customer signals and product picks every night at 03:00 in your store's time zone. The day after you connect:

* **Order items without a product.** `GET /api/v1/catalog-products/unmatched-order-items` lists, per source, the order items that matched no product, with the product IDs or SKUs most of them named. For the orders above it lists the holiday blend. Send the missing products, or fix the IDs your orders send; the next count matches past orders again. See [order items that match no product](https://segmentflow.ai/docs/catalog-products.md#find-order-items-that-match-no-product).
* **Bestsellers.** Product blocks set to bestsellers show your best-selling products, counted from your orders after refunds.
* **Product picks.** In the email editor, set a product block's source to **Picked for each customer**, then preview the email as a contact. For Alex, who bought the Ethiopia coffee, the block picks the paper filters, which other customers bought with it, and the Colombia coffee, from their favourite category.

The contact's page shows their last order, usual gap between orders and customer stage, and Segments can use the same values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.