- 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.
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 asember-hillorsalla:482100731. Use the same name every time. WithorderIdit identifies the order, so sending an order again updates it. - One product ID on both sides. An order item matches a product when its
productIdis theexternalIdyou sent the product with. When an order item has no product ID, it matches the product with the samesku. Use the ID your platform puts on order lines. If those lines carry a variant ID, send the parent product’s ID asproductIdand the variant asvariantId, 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 with400 and nothing is saved.
POST /api/v1/catalog-products/batch
201 for a new product and 200 for an update.
PUT /api/v1/catalog-products/by-external-id/0191a1e6f1d47c3b9a2e5d8c4b7f6a06
PUT makes it active again.
"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
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 intotals.
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 thecheckout.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)
{ historical: true } when you map past orders for the import.
shopware-order.js
POST /api/v1/events/order-transactions
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 theorder.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 ownrefundId, 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
Retries
Every request on this page is safe to send again. A product is keyed by itsexternalId, 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-keyand your API key as the value - Send Body: on, Body Content Type JSON, Specify Body Using JSON, with
{{ JSON.stringify($json) }}
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-itemslists, 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.

