Send products from your store
When your store runs on a platform without a SegmentFlow.ai integration, your backend creates, updates and archives its products through the API, using your own product IDs. Orders you send later match their items to these products by the same IDs. For a whole store connection, with orders and webhook mappings for Shopware and Salla, see Connect another store platform. Products you send have the sourceapi. They appear in the dashboard catalog and in product blocks in emails, like synced products.
- Sending the same product ID again updates that product, so retries are safe and you never get a duplicate.
- Each request sends the whole product. Fields you leave out are cleared, and
statusbecomesactive. descriptioncan be plain text or your store’s HTML. SegmentFlow.ai stores it as plain text.imageUrlstays a link to your image: SegmentFlow.ai shows the image from that URL and copies it only when an email needs its own copy.activeproducts can appear in emails,hiddenproducts stay in the catalog but out of emails, andarchivedproducts leave the catalog.
POST /api/v1/catalog-products/batch. Each product carries its externalId. The batch is saved as a whole: when one product is invalid, the request fails with 400 and nothing is saved.
POST /api/v1/catalog-products/by-external-id/{externalId}/archive, or up to 100 with POST /api/v1/catalog-products/batch-archive and { "externalIds": [...] }. Archived products stop appearing in emails. Sending an archived product again with PUT makes it active again.
Find order items that match no product
An order item matches a catalog product from the same source: an item in an order you sent through the API matches a product you sent through the API with the same product ID, or with the same SKU when the item has no product ID. An item with a product ID that no product has doesn’t fall back to its SKU. Items that match nothing still count in the order’s total and in revenue, but not in bestsellers or product picks. Every night SegmentFlow.ai counts, per source, the items in the last 90 days of orders that matched no product, with the product IDs or SKUs that most of them named. Read the latest count withGET /api/v1/catalog-products/unmatched-order-items:
sources is empty when every item matched, and countedAt is null until the first count. Send the missing products, or fix the product IDs your orders send, and the next count matches past orders again. The dashboard’s Integrations page shows the same count.
Product images
Catalog product image fields can point at either the merchant platform CDN or a SegmentFlow.ai Asset:primaryImageUrlis the renderable image URL. Shopify-synced products usually return the Shopify CDN URL directly, and products you send return yourimageUrl.primaryImageExternalIdandprimaryImageAltTextpreserve provider metadata for the primary image.galleryImagescontains additional provider image refs as{ externalId, url, altText, position }.primaryImageIdandimageIdsare local SegmentFlow.ai Asset refs. They are present for manual products, legacy synced products, or images that were explicitly materialized as Assets.
Do not treat
primaryImageId: null as “no image”. For synced Shopify
products, primaryImageUrl is the primary render path.List products
Render product images
UseprimaryImageUrl as the image src when it is present:
Required scopes
catalog-products:read- list and retrieve catalog products, and read the order items that matched none.catalog-products:write- create, update and archive products by your product ID, and start product metadata enrichment jobs.

