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

# Catalog products

> List synced product catalog records and understand product image URLs.

Use Catalog Products endpoints when your backend or MCP host needs read access to products synced from Shopify, WooCommerce, or manual dashboard entries.

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.
* `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.

<Note>
  Do not treat `primaryImageId: null` as "no image". For synced Shopify
  products, `primaryImageUrl` is the primary render path.
</Note>

## List products

```ts theme={null}
import Segmentflow from "@segmentflow/segmentflow-typescript";

const client = new Segmentflow({ apiKey: process.env.SEGMENTFLOW_API_KEY });

const products = await client.v1.catalogProducts.list({
  source: "shopify",
  status: "active",
  limit: 20,
});
```

## Render product images

Use `primaryImageUrl` as the image `src` when it is present:

```ts theme={null}
const product = products.data[0];

if (product?.primaryImageUrl) {
  renderProductCard({
    title: product.title,
    imageUrl: product.primaryImageUrl,
    altText: product.primaryImageAltText ?? product.title,
  });
}
```

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.
* `catalog-products:write` - start product metadata enrichment jobs.