# Fredhopper Step-by-Step Guide

### Documentation and links <a href="#cidp-external-bestpracticeguide-documentationandlinks" id="cidp-external-bestpracticeguide-documentationandlinks"></a>

* [Items API Start Page](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items.md)
* [FHR Data Model Example](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/best-practice.md)
* [Technical Best Practices](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/best-practice/items-api-best-practices.md)
* [List of Reserved Attributes](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items/item-schema/list-of-reserved-attributes.md)

#### FHR-specific considerations when reading the documentation <a href="#cidp-external-bestpracticeguide-fhr-specificconsiderationswhenreadingthedocumentation" id="cidp-external-bestpracticeguide-fhr-specificconsiderationswhenreadingthedocumentation"></a>

* **environment** is your Fredhopper instance: `live1`, `test1`, `test2`, ...
* **tenant** is your username as provided by your Technical Consultant.

{% hint style="warning" %}
The item API is designed as a multi-purpose API for all Attraqt products, and allows some object types and definitions that are not supported by FHR.
{% endhint %}

### Items API background <a href="#cidp-external-bestpracticeguide-itemsapibackground" id="cidp-external-bestpracticeguide-itemsapibackground"></a>

The Items API consists of 3 major categories:

* Setup & Definitions
  * Authorization: Generate an authorized user/token
  * Schema API: Create an Items schema to upload Items
  * Category API: Define & Upload your category tree
  * Catalog API: Create and active your (new) catalog
* Uploading and Updating Items (Products and Variants)
  * Items API Upload, Update and Delete Items
* Feedback
  * Feedback API: Retrieve product meta information, successful and failed product processing in the pipeline, additional information etc.

### API setup, step by step <a href="#cidp-external-bestpracticeguide-apisetup-stepbystep" id="cidp-external-bestpracticeguide-apisetup-stepbystep"></a>

The Crownpeak Product Discovery Items API requires authentication and a set of calls to complete the process of sending items. It is strongly recommended to have access to the feedback API early in the development to troubleshoot uploading items and activate the catalog.

<figure><img src="/files/F4X9r9U1ki2NKGZIN7IO" alt=""><figcaption></figcaption></figure>

1. **Authentication**

All API calls need to be authenticated using an access token. You can find all relevant information on how to retrieve access tokens and pass them on [here](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/authorization-to-apis.md).

{% hint style="info" %}
The authentication token is valid for up to 5 minutes and must be cached and renewed when it expires.
{% endhint %}

#### 2. Defining a schema <a href="#cidp-external-bestpracticeguide-2.definingaschema" id="cidp-external-bestpracticeguide-2.definingaschema"></a>

When creating your schema, we recommend you iterate over the schema and load small sample sets of data before adding new attributes.

Your Technical Consultant will provide guidance and create an example set for you.

|             |      |                        |                                                                                |
| ----------- | ---- | ---------------------- | ------------------------------------------------------------------------------ |
| \_imageUrl  | TEXT | Image                  | TEXT, must be an absolute link                                                 |
| \_thumbnail | TEXT | Thumbnail              | TEXT, must be an absolute link                                                 |
| categories  | LIST | Categories             | LIST (array) send valid category IDs defined in categories call must be \[a-z] |
| id          | TEXT | Unique item identifier | Each product and variant must have a unique identifier                         |

{% hint style="warning" %}
Keep in mind:

* Only `OBJECT`, `OBJECTLIST` , and `LIST` can have subtypes as `TEXT` or `LOCALIZEDTEXT`
* Object nesting is not supported in FHR.
  {% endhint %}

Conflated attributes can be used, e.g. `price_gbp`, `price_eur`, `price_usd` and are retrieved based on your FHR search. Ensure to discuss this during integration calls with your Technical Consultant to define the parameters as needed.

{% hint style="info" %}
Conflated attributes allow global rules to be created for which data points (like price, pageviews, stock etc) which would adapt automatically to the context of the shopper (markets, currency, region, store, etc).
{% endhint %}

{% hint style="info" %}
The query parameter fhrValidation=true can be added when creating/updating a schema to ensure that the schema is compatible with the Fredhopper platform
{% endhint %}

#### 3. Creating Categories <a href="#cidp-external-bestpracticeguide-3.creatingcategories" id="cidp-external-bestpracticeguide-3.creatingcategories"></a>

The Categories API represents a real tree structure of your categories. Each child category must have one (and only one) parent ID. We highly recommended you use `catalog01` as the root for your category tree. If you require a change, speak to your Technical Consultant.

The category ID (`name` in the API) must be following the format: `[a-z]+`

Example:

<figure><img src="/files/GLonLoYpDytPxQrUpacz" alt=""><figcaption></figcaption></figure>

In the above example, note that you can have localised values for "trousers" in men and women categories but their identifier must be unique.

Please find the relational table and JSON example for this diagram in the appendix.

{% hint style="warning" %}
Your system should store the current (and next) category tree as it is required to create a catalog.
{% endhint %}

{% hint style="info" %}
The query parameter fhrValidation=true can be added when creating/updating a category tree to ensure that the category tree is compatible with the Fredhopper platform
{% endhint %}

#### 4. Create a catalog <a href="#cidp-external-bestpracticeguide-4.createcatalog" id="cidp-external-bestpracticeguide-4.createcatalog"></a>

{% hint style="warning" %}
The Catalog API can handle only 2 catalogs at the same time. If this limit is reached, one inactive catalog must be deleted by using the API before creating a new one. Determining the inactive catalog is done by listing all catalogs.
{% endhint %}

Create a new catalog by defining which version of the schema and category tree should be used.

{% hint style="info" %}
Fredhopper requires both schema and category tree to be present in the catalog creation API call. Multiple catalogs can reuse the same schema and/or category tree versions. Consequently, creating a new catalog does not require creating new schema and category tree versions if suitable versions already exist.
{% endhint %}

At this point, we recommended to have a (manual) way to query the Feedback API to check on the status of the catalog and future items.

#### 5. Send items <a href="#cidp-external-bestpracticeguide-5.sendingitems" id="cidp-external-bestpracticeguide-5.sendingitems"></a>

**Choose the appropriate Items API for each type of update**

Crownpeak offers two Items APIs. Pick the appropriate one depending on the type of update you need to make:

* [The Streaming Items API](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items/items/using-the-items-api.md)\
  Use the Streaming Items API to push frequent **updates throughout the day**. This API is ideal for stock changes or real-time pricing.\
  It is optimized for smaller, incremental updates and requires fewer API calls than the Batch Items API.
* [The Batch Items API](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items/items/using-the-batch-items-api.md)\
  Use the Batch Items API to **replace an entire catalog**.\
  This API also includes advanced capabilities, such as automatically deleting items not included in the latest batch.

{% hint style="warning" %}
All use cases will require the use of both Items APIs.
{% endhint %}

{% hint style="success" %}
As a Fredhopper customer, we recommend you do one full catalog update every day using the Batch Items API and use the Streaming Items API for necessary partial updates throughout the day.
{% endhint %}

**Send items to the API**

Group parent item and all variants in a single message to avoid rejections caused by queue order.

{% hint style="warning" %}
Ensure each message is under \~1 MB in size and respect the API rate limit of 250 messages per second.
{% endhint %}

**Deal with item rejections**

{% hint style="warning" %}
The Items API typically returns an HTTP 200 status even if some items fail.
{% endhint %}

Parse the error response to ensure you capture all error messages.

Example:

```
{
    "receiptIds": [
        { "itemId": {
            "id": "A0002",
            "catalogVersion": 243,
            "context": "",
            "type": "product",
            "tenant": "exampletenant",
            "environment": "test1"
        },
        "receiptId": "36fb85ce-db71-4t0a-9891-afb737d00c65",
        "status": "FAILURE",
        "statusMessage": "Item validation errors: Missing required attributes: price_gbp"
    }]
}
```

Parse the response of the Items API and at least store the body containing a `FAILURE` status.

We recommend you keep a record of successfully loaded products to decide if a catalog should be activated.

{% hint style="info" %}
The query parameter fhrValidation=true can be added when creating/updatign an item to ensure that the item data is compatible with the Fredhopper platform
{% endhint %}

#### 6. Activate Catalog <a href="#cidp-external-bestpracticeguide-6.activatecatalog" id="cidp-external-bestpracticeguide-6.activatecatalog"></a>

Activate a catalog by catalog ID.

* This activates the catalog chosen and moves the current catalog to `INACTIVE`. Note: changing the state to `INACTIVE` happens only after a successful activation of the new catalog.
* Activations are not instant. The activation triggers the handover from the Items Queue to the Fredhopper data processing and enrichment process.

### Incremental Data <a href="#cidp-external-bestpracticeguide-incrementaldata" id="cidp-external-bestpracticeguide-incrementaldata"></a>

You can either upload a new product or variant as a new item, delete a complete item, or update an item partially.

{% hint style="warning" %}
Keep in mind:

* Only `DELETE` a product after deleting all variants.
* To add a new variant, the parent product must exist.
  * You can send a new parent and variants in the same request. All new products are queued up and processed in an incremental update process every 5 minutes.
    {% endhint %}

Similar to the full data load, you should parse the response of the Items API and at least store the body containing a `FAILURE` status.

You should keep track of the number of items sent and ideally keep a full transaction log for troubleshooting.

### Feedback & Statistics <a href="#cidp-external-bestpracticeguide-feedback-and-statistics" id="cidp-external-bestpracticeguide-feedback-and-statistics"></a>

The Feedback API is used to provide feedback and statistics of your catalogs, items and catalog activations.

{% content-ref url="/pages/xbodw7e4C0YFrwviUxtM" %}
[Verifying Data Processing](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/feedback-api.md)
{% endcontent-ref %}

It is strongly recommended to have this API early on in the integration process ready in an API Platform like [Postman](https://www.postman.com).

It is recommended to check the **Summary of updates** on a regular basis. For an integration that uses full data loads only, it is sufficient to retrieve this after an activation. If you are using incremental data loads, you should check on an hourly basis if there have been errors in the last hour.

{% hint style="info" %}
Many requests on the Feedback API require the catalog ID, you can use the [Catalog API](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items/item-catalog/using-the-catalog-api.md) to retrieve a list of catalogs and the latest active version.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://crownpeak.gitbook.io/product-discovery/sending-and-managing-product-data/what-is-the-items-api/step-by-step-guide-for-fredhopper-customers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.