Skip to main content
Use Catalog Products endpoints to send your store’s products to SegmentFlow.ai, and to read the catalog: products you sent through the API, products synced from Shopify or WooCommerce, and products added in the dashboard.

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 source api. 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 status becomes active.
  • description can be plain text or your store’s HTML. SegmentFlow.ai stores it as plain text.
  • imageUrl stays a link to your image: SegmentFlow.ai shows the image from that URL and copies it only when an email needs its own copy.
  • active products can appear in emails, hidden products stay in the catalog but out of emails, and archived products leave the catalog.
Create or update one product:
Send up to 100 products at once with 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.
Archive a product with 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 with GET /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:
  • primaryImageUrl is the renderable image URL. Shopify-synced products usually return the Shopify CDN URL directly, and products you send return your imageUrl.
  • primaryImageExternalId and primaryImageAltText preserve provider metadata for the primary image.
  • galleryImages contains additional provider image refs as { externalId, url, altText, position }.
  • primaryImageId and imageIds are 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

Use primaryImageUrl as the image src when it is present:
SegmentFlow.ai creates or reuses a local Asset only for workflows that require an owned image copy. Normal Shopify catalog sync does not copy every Shopify product image into Assets.

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.