# Item Synchronization

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/item-sync-options.html)

> **IMPORTANT:**
> 
> Item synchronization is shared setup for every Froomle integration and is not provided by the frontend SDK. Complete it before choosing how to implement event tracking and recommendation delivery.

<a id="item-sync-schema"></a>

## Item Metadata

Item metadata serves 3 purposes within the Froomle system:

1.  **Filtering & Constraints** — Filter recommendations by category, price range, brand, or custom attributes
    
2.  **Reporting & Analytics** — Attribute recommendation performance to specific items, categories, or content types
    
3.  **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.

<a id="_standard_fields"></a>

### 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. | ✓ | ✓ |
| **`flags`** | **`list<string>`** — Custom labels to filter on. |  | ✓ |
| **`item_attributes`** | **`map<string, string>`** — Custom key-value attributes. | ✓ | `*` |

`*` Specific fields within item\_attributes can be set up as filters on demand.

<a id="_timestamp_fields"></a>

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

<a id="_enrichment_fields"></a>

### 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`** — A short summary, abstract, or introduction to the item. |  |  |
| **`content_body`** | **`string`** — The complete textual content of the item. |  |  |

<a id="_hierarchy_fields"></a>

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

<a id="item-sync-connectors"></a>

## Item Synchronization

<a id="_items_api_push"></a>

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

<a id="_operations"></a>

#### Operations

| Operation | Method |
| --- | --- |
| Create or update (RESTful) | `PUT /api/{environment}/items/{item_type}/{item_id}` |
| Create or update (Webhook-friendly) | `POST /api/{environment}/items/{item_type}` |
| 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}` |

<a id="_authentication"></a>

#### Authentication

Froomle’s Items API uses OAuth 2.0 Bearer token flow, see [Authentication Flow](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/authentication-flow.html).

<a id="_data_currency"></a>

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

<a id="_scale_considerations"></a>

#### Scale considerations

High-frequency or bulk updates (>100/s) are supported, but require careful burst management to avoid overwhelming the Items API.

<a id="_when_appropriate"></a>

#### 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](https://docs.froomle.com/froomle-doc-main/v2/api_reference/items/index.html).

<a id="_feed_read_pull"></a>

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

<a id="_operations_2"></a>

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

<a id="_authentication_2"></a>

#### Authentication

Froomle’s Feed Reader can provide a static authentication header when crawling your endpoint.

<a id="_data_currency_2"></a>

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

<a id="item-sync-feed-formats"></a>

#### 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](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](https://about.flipboard.com/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 |

<a id="_scale_considerations_2"></a>

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

<a id="_when_appropriate_2"></a>

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

<a id="_sftpfile_upload_batch"></a>

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

<a id="_operations_3"></a>

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

<a id="_authentication_3"></a>

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

<a id="_data_currency_3"></a>

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

<a id="_file_format_options"></a>

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

<a id="_scale_considerations_3"></a>

#### Scale considerations

Scales with file size and SFTP server capacity. Gigabyte-scale files are routine. For massive catalogs (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.

<a id="_when_appropriate_3"></a>

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

<a id="item-sync-operations"></a>

## Best practices

<a id="_timestamps_and_timezones"></a>

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

<a id="_nested_fields_in_csv"></a>

### Nested fields in CSV

When using CSV format, serialize nested fields as JSON strings:

```csv
item_id,title,categories,tags
article_001,"Title",["[Sports/Football]","[News/National]"],"[Breaking,UK]"
```

<a id="_continuously_updated_content"></a>

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

<a id="_hierarchical_categories"></a>

### Hierarchical categories

Categories should be hierarchical paths:

```json
"categories": [
    ["/Electronics/Computers/Laptops"],
    ["/Electronics/Computers"]
]
```

This allows filtering at any level of specificity.

<a id="_optimization_tips"></a>

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

<a id="_contentbased_recommendations"></a>

### Content‑based recommendations

Metadata like categories, tags, and editorial labels improves content‑based recommendations and reporting insights.

<a id="_related_topics"></a>

## Related topics

-   [Filters and constraints](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/filters-and-constraints.html)
    
-   [Recommendation request model](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/recommendation-requests.html)
    
-   [Item catalog](https://docs.froomle.com/froomle-doc-main/v2/guide/item-sync.html)