Product Feeds

A product feed is a URL IntentFlow fetches on a schedule to keep your catalog in sync — no integration code required. Most merchants configure feeds in the dashboard (Store → Feeds); this page documents the equivalent API for programmatic setup.

For the other import methods see Product Imports (API push) and Importing Products (overview of all three).

Authenticate every request with your store API key via X-Api-Key or Authorization: Bearer.

How feeds work

• IntentFlow fetches the feed URL on your chosen interval and on demand.
• A feed is treated as your complete catalog: products present are added or updated; products missing from the feed are marked out of stock (not deleted).
• Each fetch creates an ingestion run you can inspect for status and counts.
• A failed fetch never wipes your catalog; IntentFlow retries on the next run.

Supported formats

See Feed Formats for the exact CSV, JSON, and Google Merchant XML schemas, complete examples, and custom-site implementation guidance.

feed_format	Description
csv	Hosted UTF-8 CSV using the canonical product columns.
google_xml	Google Merchant / Google Shopping product feed (RSS 2.0, g: namespace).
json	Hosted JSON document using the product fields, either a top-level array or { "products": [...] }.

Register A Feed

POST /api/v1/product-feeds
Content-Type: application/json

{
  "name": "Primary Google feed",
  "feed_url": "https://shop.example.com/feeds/google.xml",
  "feed_format": "google_xml",
  "refresh_interval": "6h"
}

curl -X POST https://app.example.com/api/v1/product-feeds \
  -H "X-Api-Key: if_PLACEHOLDER_KEY" \
  -H "Content-Type: application/json" \
  -d @feed.json

Fields:

Field	Required	Description
name	Yes	A label for the feed.
feed_url	Yes	Absolute https URL to the feed document.
feed_format	Yes	google_xml or json.
refresh_interval	No	15m, 1h, 6h, or 24h. Defaults to 6h.
auth_type	No	basic or header for protected feeds.
auth_secret	No	Credentials for auth_type (stored encrypted).

On success IntentFlow validates the URL is reachable and the format parses, then returns the feed with its uuid and computed next_run_at.

{
  "message": "Feed registered.",
  "feed": {
    "id": "b1d2c3e4-5f6a-47b8-9c0d-1e2f3a4b5c6d",
    "name": "Primary Google feed",
    "feed_url": "https://shop.example.com/feeds/google.xml",
    "feed_format": "google_xml",
    "refresh_interval": "6h",
    "status": "active",
    "last_fetched_at": null,
    "next_run_at": "2026-07-04T16:00:00.000000Z",
    "last_error": null,
    "links": {
      "self": "https://app.example.com/api/v1/product-feeds/b1d2c3e4-5f6a-47b8-9c0d-1e2f3a4b5c6d"
    }
  }
}

List Feeds

GET /api/v1/product-feeds

Returns all feeds for the authenticated store.

Feed Status

GET /api/v1/product-feeds/{feed_id}

Returns the feed plus a summary of its most recent run (status, counts, removed_rows).

Status	Meaning
active	Scheduled and healthy.
paused	Disabled; not fetched until re-activated.
error	The last fetch failed; see last_error. IntentFlow keeps retrying.

Update A Feed

PATCH /api/v1/product-feeds/{feed_id}
Content-Type: application/json

Send any subset of name, feed_url, feed_format, refresh_interval, auth_type, auth_secret, or is_active.

Delete A Feed

DELETE /api/v1/product-feeds/{feed_id}

Stops future fetches. Products already imported by the feed are kept; manage them via the API or another feed.

Refresh Now

POST /api/v1/product-feeds/{feed_id}/refresh

Queues an immediate fetch instead of waiting for the next scheduled run. Returns the ingestion run that was started.

curl -X POST https://app.example.com/api/v1/product-feeds/b1d2c3e4-5f6a-47b8-9c0d-1e2f3a4b5c6d/refresh \
  -H "X-Api-Key: if_PLACEHOLDER_KEY"

Tips

• Keep external_id (g:id in Google XML) stable so updates land on the right product between fetches.
• Choose the longest interval that meets your freshness needs — a 15-minute feed on a large catalog does more work than most shops require.
• Use Refresh now after a big catalog change instead of shortening the interval.
• Protect large feeds behind auth_type rather than a public URL.