Item Synchronization Item Metadata Item metadata serves 3 purposes within the Froomle system: Filtering & Constraints — Filter recommendations by category, price range, brand, or custom attributes Reporting & Analytics — Attribute recommendation performance to specific items, categories, or content types Response Enrichment — Include item metadata in recommendation responses, eliminating the need for additional back-end lookups and reducing latency While technically it is possible to return all available metadata for each item in a Froomle response, keep in mind that the size of the response negatively impacts the speed of the system. This feature is not meant, for example, to return the full body text of articles. Limitations may be placed upon response size. Standard fields Field Description Returned Filterable item_id string — A stable identifier of the item, unique for a given environment and item_type. The same item_id must be used consistently in events to refer to this item. ✓ item_type string — The type of entity this item represents (e.g., article, video, product, or generic item). We recommended varying the item type only if there is a substantial different in user experience between these items. Items always have to be referenced using both item_id and item_type. ✓ ✓ title string — The human-readable name of the item, a primary label users would recognize. Used in dashboards to refer to an item. ✓ uri string — The URL/resource identifier of the item. Used in dashboards to link to an item. ✓ categories list<list<string>> — Hierarchical category paths, with categories listed from most general to most specific (e.g., [["Sports", "Football"], ["News", "National"]]). ✓ ✓ tags list<string> — Tags providing extra context and semantic meaning. ✓ ✓ images list<string> — URLs of item images. Used in dashboards to visualize items. ✓ access_type string — Specifies access restrictions to users, e.g., PAID or USERS_ONLY. Although Froomle itself does not apply access control, this field can be useful for filtering or module configurations. ✓ ✓ item_attributes map<string, string> — Custom key-value attributes. ✓ ✓ Timestamp fields Provide fully qualified timestamps (ISO‑8601 with timezone offset) or UTC to avoid ambiguity. Field Description Returned Filterable publication_datetime string — Timestamp of the item’s publication, i.e., earliest moment it was made available to users in its current form. Essential for recency filtering and time-based recommendations. ✓ end_datetime string — Timestamp marking when the item has "expired" and should no longer be recommended. Enrichment fields These fields are used behind the scenes by Froomle’s algorithms to acquire a deeper understanding of the item. Field Description Returned Filterable description string — The full text or summary description of the item. Hierarchy fields Items can belong to a taxonomy, in which case their parents and ancestry_level can additionally be specified. Field Description Returned Filterable parent string — The identifier of the parent item when items are hierarchically structured. ✓ ancestry_level string — The hierarchical level of this item. Valid values: group (highest), item, model (lowest). ✓ Item Synchronization Items API (Push) Your system maintains the source of truth, and pushes each item create, update, or delete operation to Froomle via direct API calls. When an item changes, translate it into a JSON payload and POST/PUT it to Froomle’s Items API endpoint. Take care to handle 4xx and 5xx error responses on your end as well. Operations Operation Method Create or update PUT /api/{environment}/items/{item_type}/{item_id} Disable for recommendations POST /api/{environment}/items/{item_type}/{item_id}/disable Enable for recommendations POST /api/{environment}/items/{item_type}/{item_id}/enable Delete entirely DELETE /api/{environment}/items/{item_type}/{item_id} Authentication Froomle’s Items API uses OAuth 2.0 Bearer token flow, see Authentication Flow. Data currency Items are available for recommendations as soon as the API call succeeds, subject to Froomle’s ingestion pipeline (typically sub-minute). New items may take an addional period of time before they are incorporated in Froomle’s trained AI models. Scale considerations High-frequency or bulk updates (>100/s) are supported, but require careful burst management to avoid overwhelming the Items API. When appropriate Choose push when your data system is event-driven, you have development resources to maintain integration logic, and timeliness matters. Common in e-commerce (inventory updates), content platforms (article publishing), and real-time personalization scenarios. For API operations and examples, see Items API Reference. Feed Read (Pull) Your system publishes item data as a structured feed (RSS, Atom, JSON, XML, or CSV) on a static endpoint. Froomle periodically polls this feed endpoint, parses it, and ingests any new or modified items. Expose an HTTP endpoint that generates and serves the most recent items in your catalog in a supported format. Items have to persist in the published feed for long enough to be ingested by Froomle (preferably >1 hour). Operations Operation Method Create or update Publish item with full metadata on your endpoint Disable Re-publish item with agreed-upon disable marker Enable Re-publish item without disable marker Delete ✗ Not supported through feed reed Authentication Froomle’s Feed Reader can provide a static authentication header when crawling your endpoint. Data currency Froomle checks your feed every 15 minutes by default (configurable). Items are available after the feed has been parsed and processed (typically minutes). New items may take an addional period of time before they are incorporated in Froomle’s trained AI models. Feed format options RSS 2.0 and Atom 1.0 — Standard formats natively supported by WordPress, Drupal, and content management platforms. Field mapping is automatic (title, description, link, pubDate, category). XML, JSON, CSV — Custom schemas mapped by the Froomle team during onboarding. Requires careful alignment on field names and data types. RSS field mapping Standards and Validation: https://www.rssboard.org/rss-specification RSS Source Froomle Field Notes title title Item title link uri Item URL/resource identifier dc:creator Custom attribute (author) Use Dublin Core namespace; see RSS Guidelines pubDate publication_datetime Publication timestamp (ISO-8601 format recommended) category categories One or more category tags; becomes a single-level list in Froomle guid item_id Unique item identifier; should be stable across feed updates description description Item summary or full text image or media:content[url] images Image URLs; supports multiple media:content elements Scale considerations The endpoint must be highly available, and return a fast response of moderate size. Excessively large item feeds, both in number of items and in content size, add parsing and processing delay, and may bottleneck the feed reader. When appropriate Choose pull when you’re integrating a content or commerce platform with native feed support, expect moderate update frequencies, and want minimal development overhead. Typical for blogs (WordPress RSS), news sites (Atom feeds), and CMS-driven e-commerce (Shopify, Magento feeds). For detailed RSS setup, see RSS Reference. SFTP/File Upload (Batch) Your system generates item data files (CSV, JSON, or XML) and uploads them to a dedicated storage on Froomle’s servers. Froomle monitors the server, detects new files, and processes them. Create a scheduled job that queries your database, exports items to one or more files, and exports this file to your assigned storage location. The storage can either be an SFTP location, or a Google Cloud Storage bucket. Operations Add an operation field to each entry in your file to specify the action. All three operations are supported: ADD, UPDATE, and DELETE. When operations are specified, every entry must include one. Authentication Credentials for SFTP will be provided. In case of a GCS bucket, we can either assign permissions to an existing service account, or provide you with a new service account. Data currency Froomle will begin processing the file shortly after it arrives on our storage. Depending on size, this may take up to 30 minutes. We do not support a frequency of more than one export per hour. File format options CSV — Easy to generate from relational databases; fields as comma-separated columns. Nested fields serialized as JSON. JSON — More expressive; supports nested structures natively. XML — Flexible; supports custom namespaces and hierarchies. Scale considerations Scales with file size and SFTP server capacity. Gigabyte-scale files are routine. For massive catalogues (10M+ items), consider splitting into multiple files uploaded in parallel (one per category, brand, or region). SFTP server disk space must accommodate your full export plus Froomle’s retention buffer. When appropriate: Choose batch when your data originates from a data warehouse or relational database, updates are scheduled or infrequent, and you want operational simplicity. Common in large e-commerce (nightly inventory exports), publishing (asset management systems), and legacy migrations. Best practices Timestamps and timezones Always provide fully qualified ISO-8601 timestamps with timezone offsets (e.g., 2021-07-29T13:02:03+02:00) or UTC (2021-07-29T13:02:03Z). Without timezone information, ambiguity can arise between systems. Nested fields in CSV When using CSV format, serialize nested fields as JSON strings: item_id,title,categories,tags article_001,"Title",["[Sports/Football]","[News/National]"],"[Breaking,UK]" Continuously updated content Highly dynamic content such as live feeds or ongoing coverage can be complex to handle. Strategy 1: Update publication_datetime Keep the same item_id and update publication_datetime to the current time whenever the content changes. This signals to Froomle that the item is fresh and should remain eligible for recommendations. Pros: Simple; reuses the same item identity. Cons: Froomle’s models may struggle with items that are constantly "refreshed"; recency signals become noisy if you update too frequently. Strategy 2: Create new item_id per significant change Once content has changed substantially (e.g., different outcome, phase, or significance), treat it as a new item with a new item_id. Retire the old item (via deletion or end_datetime) and publish a fresh one. Pros: Cleaner semantics; Froomle treats each phase as a distinct item. Analytics separate old and new content. Cons: More operational complexity; requires versioning logic. If your catalog contains a non-negligible amount of such content, discuss with the Froomle team which strategy fits best. Hierarchical categories Categories should be hierarchical paths: "categories": [ ["/Electronics/Computers/Laptops"], ["/Electronics/Computers"] ] This allows filtering at any level of specificity. Optimization tips Provide as many metadata fields as possible for better results: Titles & descriptions — Help Froomle understand content and improve analytics Categories & tags — Essential for content-based recommendations and filtering Images — Improve portal demos and UI displays Timestamps — Enable recency-based recommendations and time-sensitive filtering Content‑based recommendations Metadata like categories, tags, and editorial labels improves content‑based recommendations and reporting insights. Related topics Filters and constraints Recommendation requests Item catalog