Skip to main content
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 endpoints;
  • its paid orders and refunds, with the products in them, through the order transactions 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 workflow, or a Make scenario. This guide shows the requests, then the mapping for a Shopware 6 and a Salla order.

What to send when

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.
POST /api/v1/catalog-products/batch
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.
PUT /api/v1/catalog-products/by-external-id/0191a1e6f1d47c3b9a2e5d8c4b7f6a06
When a product is deleted, archive it. Archived products stop appearing in emails; sending the product again with PUT makes it active again.
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.
POST /api/v1/events/order-transactions/batch
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 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.
Shopware 6 checkout.order.placed webhook (abridged)
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.
shopware-order.js
For the webhook above, it returns this request:
POST /api/v1/events/order-transactions
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.

A Salla order

Salla sends the order in the order.created webhook. This is an abridged body; see Salla’s webhook documentation 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.
Salla order.created webhook (abridged)
salla-order.js
POST /api/v1/events/order-transactions

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.
POST /api/v1/events/order-transactions
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:
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:

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.
  • 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.