Feeds¶

Inspect product feeds and their runs, and look up product data and recent changes.

Tips & tricks

Check the latest feed run before investigating missing products. A failed run explains most gaps.

Show the latest product feed run for my website and whether it succeeded.

createProductFeed¶

Create a new V2 product feed for a customer website. The feed is created in state INACTIVE by default, so it can be configured and verified before it starts running. Once ACTIVE, the feed runs on a schedule every runIntervalSeconds (default: every 24 hours). Returns the full configuration detail of the created feed, including the new feed ID.

Name	Type	Required	Description
`websiteUuid`	string	Yes	UUID of the customer's website. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`name`	string	Yes	Display name of the feed.
`url`	string	Yes	URL the feed will be fetched from. Must be an http(s) URL.
`format`	string	Yes	Content format of the feed response. One of: JSON, XML, DSV, JSONL.
`requestType`	string	No	How the feed is fetched. One of: SINGLE_REQUEST, PAGE_BASED, OFFSET_BASED. PAGE_BASED requires `pageBasedConfig` and OFFSET_BASED requires `offsetBasedConfig`. Default: SINGLE_REQUEST.
`state`	string	No	Initial feed lifecycle state. One of: ACTIVE, INACTIVE. Default: INACTIVE.
`runIntervalSeconds`	integer	No	Seconds between scheduled runs, clamped to between 1800 (30 minutes) and 8640000 (100 days). 0 means manual runs only and is allowed only for INACTIVE feeds. Default: 86400 (24 hours).
`itemsPath`	string	No	Path to the products array in the feed response, as a '>'-separated chain of element names (e.g. "products>product"). Omit or use "root" when the products are at the feed root.
`transformationCode`	string	No	JavaScript executed on each product after parsing. Defaults to an identity transform that passes every product through unchanged.
`basicAuthUser`	string	No	HTTP Basic Auth username.
`basicAuthPassword`	string	No	HTTP Basic Auth password.
`customHeaders`	string	No	JSON object of custom HTTP headers, e.g. `{"X-Api-Key": "abc"}`.
`requestWaitSeconds`	integer	No	Seconds to wait between paginated requests (0-30). Default: 0.
`cacheBusting`	boolean	No	Whether to append a cache-busting query parameter to the URL. Default: true.
`allowDeltaRuns`	boolean	No	Whether to enable incremental delta runs. Default: true.
`pageBasedConfig`	string	No	JSON object for page-based pagination: `{"pageVariable": "page", "pageInitialValue": 1, "sizeVariable": "pageSize", "sizeValue": 200}`. Required when requestType is PAGE_BASED, not allowed otherwise.
`offsetBasedConfig`	string	No	JSON object for offset-based pagination: `{"startOffsetVariable": "from", "offsetInitialValue": 0, "offsetSizeVariable": "length", "offsetSize": 200}`. Required when requestType is OFFSET_BASED, not allowed otherwise.
`createProducts`	boolean	No	Whether the feed is allowed to create new products. Default: true.
`stopIfFewerThanExpected`	boolean	No	Enable/disable the fewer-than-expected safety stop. Default: true.
`stopIfMoreThanExpected`	boolean	No	Enable/disable the more-than-expected safety stop. Default: true.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "createProductFeed",
    "arguments": {
      "websiteUuid": "<string>",
      "name": "<string>",
      "url": "<string>",
      "format": "<string>"
    }
  }
}

Returns

{
  "id": 0,
  "name": "<string>",
  "url": "<string>",
  "state": "<string>",
  "format": "<string>",
  "requestType": "<string>",
  "runIntervalSeconds": 0,
  "lastRunAt": "<string>",
  "nextRunAt": "<string>",
  "itemsPath": "<string>",
  "transformationCode": "<string>",
  "basicAuthUser": "<string>",
  "customHeaders": "<string>",
  "requestWaitSeconds": 0,
  "cacheBusting": false,
  "allowDeltaRuns": false,
  "pageBasedConfig": "<string>",
  "offsetBasedConfig": "<string>",
  "createProducts": false,
  "stopIfFewerThanExpected": false,
  "stopIfMoreThanExpected": false
}

getProductFeed¶

Retrieve full configuration detail for a single V2 product feed.

Name	Type	Required	Description
`websiteUuid`	string	Yes	UUID of the customer's website. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`feedId`	integer	Yes	ID of the feed. Use `listProductFeeds` to find available feed IDs.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getProductFeed",
    "arguments": {
      "websiteUuid": "<string>",
      "feedId": 0
    }
  }
}

Returns

{
  "id": 0,
  "name": "<string>",
  "url": "<string>",
  "state": "<string>",
  "format": "<string>",
  "requestType": "<string>",
  "runIntervalSeconds": 0,
  "lastRunAt": "<string>",
  "nextRunAt": "<string>",
  "itemsPath": "<string>",
  "transformationCode": "<string>",
  "basicAuthUser": "<string>",
  "customHeaders": "<string>",
  "requestWaitSeconds": 0,
  "cacheBusting": false,
  "allowDeltaRuns": false,
  "pageBasedConfig": "<string>",
  "offsetBasedConfig": "<string>",
  "createProducts": false,
  "stopIfFewerThanExpected": false,
  "stopIfMoreThanExpected": false
}

updateProductFeed¶

Patch one or more fields on a V2 product feed. This is a partial update — only the fields you provide are changed. Every omitted field keeps its current value.

Name	Type	Required	Description
`websiteUuid`	string	Yes	UUID of the customer's website. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`feedId`	integer	Yes	ID of the feed to update. Use `listProductFeeds` to find available feed IDs.
`name`	string	No	Display name of the feed.
`url`	string	No	URL the feed should be fetched from. Must be an http(s) URL.
`state`	string	No	Feed lifecycle state. One of: ACTIVE, INACTIVE, ARCHIVED.
`itemsPath`	string	No	Path to the products array in the feed response, as a '>'-separated chain of element names (e.g. "products>product"). Omit or use "root" when the products are at the feed root.
`crawlConfig`	string	No	JSON string defining how fields are extracted from each product in the feed.
`transformationCode`	string	No	JavaScript executed on each product after parsing.
`basicAuthUser`	string	No	HTTP Basic Auth username.
`basicAuthPassword`	string	No	HTTP Basic Auth password.
`customHeaders`	string	No	JSON object of custom HTTP headers, e.g. `{"X-Api-Key": "abc"}`.
`runIntervalSeconds`	integer	No	Seconds between scheduled runs. Must be positive; values are clamped to between 1800 (30 minutes) and 8640000 (100 days).
`requestWaitSeconds`	integer	No	Seconds to wait between paginated requests (0-30).
`cacheBusting`	boolean	No	Whether to append a cache-busting query parameter to the URL.
`allowDeltaRuns`	boolean	No	Whether to enable incremental delta runs.
`pageBasedConfig`	string	No	JSON object for page-based pagination. Only valid for feeds with requestType PAGE_BASED.
`offsetBasedConfig`	string	No	JSON object for offset-based pagination. Only valid for feeds with requestType OFFSET_BASED.
`createProducts`	boolean	No	Whether the feed is allowed to create new products.
`stopIfFewerThanExpected`	boolean	No	Enable/disable the fewer-than-expected safety stop.
`stopIfMoreThanExpected`	boolean	No	Enable/disable the more-than-expected safety stop.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "updateProductFeed",
    "arguments": {
      "websiteUuid": "<string>",
      "feedId": 0
    }
  }
}

Returns

{
  "id": 0,
  "name": "<string>",
  "state": "<string>",
  "lastModified": "<string>"
}

listProductFeeds¶

List all V2 product feeds for a customer website. Archived feeds are excluded by default.

Name	Type	Required	Description
`websiteUuid`	string	Yes	UUID of the customer's website. Use `getWebsiteInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`includeArchived`	boolean	No	When true, archived feeds are included in the results. Default: false.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listProductFeeds",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

Returns

[
  {
    "id": 0,
    "name": "<string>",
    "url": "<string>",
    "state": "<string>",
    "format": "<string>",
    "requestType": "<string>",
    "runIntervalSeconds": 0,
    "lastRunAt": "<string>",
    "nextRunAt": "<string>"
  }
]

getProductFeedRun¶

Return the full detail record for a specific run identified by its runId. Use this after listProductFeedRuns to drill into a particular run — for example to compare a failed run against a successful one.

Name	Type	Required	Description
`websiteUuid`	string	Yes	UUID of the customer's website. Find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`feedId`	integer	Yes	ID of the feed the run belongs to. Use `listProductFeeds` to find available feed IDs.
`runId`	string	Yes	Queue item ObjectId hex string. Obtained from the runId field in `listProductFeedRuns`.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getProductFeedRun",
    "arguments": {
      "websiteUuid": "<string>",
      "feedId": 0,
      "runId": "<string>"
    }
  }
}

Returns

{
  "runId": "<string>",
  "runType": "<string>",
  "state": "<string>",
  "interrupted": false,
  "queuedAt": "<string>",
  "itemsTotal": 0,
  "itemsAdded": 0,
  "itemsUpdated": 0,
  "itemsDeleted": 0,
  "itemsFailed": 0,
  "hasErrors": false,
  "itemsSkipped": 0,
  "downloadTimeMs": 0,
  "parsingTimeMs": 0,
  "feedFileSizeBytes": 0,
  "feedUrl": "<string>",
  "messages": [],
  "incompleteFeed": false,
  "issues": [],
  "ignoredFields": [],
  "autoCorrectedFields": [],
  "deltaTokenUsed": "<string>",
  "deltaTokenFound": "<string>"
}

getLatestProductFeedRun¶

Return the full detail record for the most recent run of a V2 product feed. Includes timing, per-field quality diagnostics, log messages, and error information. Use this to diagnose a failed or slow run without first calling listProductFeedRuns.

Name	Type	Required	Description
`websiteUuid`	string	Yes	UUID of the customer's website.
`feedId`	integer	Yes	ID of the feed. Use `listProductFeeds` to find available feed IDs.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "getLatestProductFeedRun",
    "arguments": {
      "websiteUuid": "<string>",
      "feedId": 0
    }
  }
}

Returns

{
  "runId": "<string>",
  "runType": "<string>",
  "state": "<string>",
  "interrupted": false,
  "queuedAt": "<string>",
  "itemsTotal": 0,
  "itemsAdded": 0,
  "itemsUpdated": 0,
  "itemsDeleted": 0,
  "itemsFailed": 0,
  "hasErrors": false,
  "itemsSkipped": 0,
  "downloadTimeMs": 0,
  "parsingTimeMs": 0,
  "feedFileSizeBytes": 0,
  "feedUrl": "<string>",
  "messages": [],
  "incompleteFeed": false,
  "issues": [],
  "ignoredFields": [],
  "autoCorrectedFields": [],
  "deltaTokenUsed": "<string>",
  "deltaTokenFound": "<string>"
}

listProductFeedRuns¶

Return the most recent run history for a V2 product feed, newest first. Useful for checking whether recent runs succeeded and obtaining a runId for getProductFeedRun.

Name	Type	Required	Description
`websiteUuid`	string	Yes	UUID of the customer's website.
`feedId`	integer	Yes	ID of the feed. Use `listProductFeeds` to find available feed IDs.
`limit`	integer	No	Maximum number of runs to return. Between 1 and 50. Default: 10.

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listProductFeedRuns",
    "arguments": {
      "websiteUuid": "<string>",
      "feedId": 0
    }
  }
}

Returns

[
  {
    "runId": "<string>",
    "runType": "<string>",
    "state": "<string>",
    "interrupted": false,
    "queuedAt": "<string>",
    "itemsTotal": 0,
    "itemsAdded": 0,
    "itemsUpdated": 0,
    "itemsDeleted": 0,
    "itemsFailed": 0,
    "hasErrors": false
  }
]