Step by step guide for Fredhopper customers

A best practice guide for Fredhopper (FHR) implementation.

Documentation and links

• Items API Start Page

• FHR Data Model Example

• Technical Best Practices

• List of Reserved Attributes

FHR-specific considerations when reading the documentation

• environment is your Fredhopper instance: live1, test1, test2, ...

• tenant is your username as provided by your Technical Consultant.

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.

Items API background

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

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.

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.

The authentication token is valid for up to 5 minutes and must be cached and renewed when it expires.

2. Defining a schema

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

Keep in mind:

• Only OBJECT, OBJECTLIST , and LIST can have subtypes as TEXT or LOCALIZEDTEXT

• Object nesting is not supported in FHR.

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.

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

The query parameter fhrValidation=true can be added when creating/updating a schema to ensure that the schema is compatible with the Fredhopper platform

3. Creating Categories

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:

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.

Your system should store the current (and next) category tree as it is required to create a catalog.

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

4. Create a catalog

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.

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

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.

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

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

All use cases will require the use of both Items APIs.

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.

Send items to the API

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

Ensure each message is under ~1 MB in size and respect the API rate limit of 250 messages per second.

Deal with item rejections

The Items API typically returns an HTTP 200 status even if some items fail.

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.

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

6. Activate Catalog

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

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

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.

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

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

Using the Feedback API

It is strongly recommended to have this API early on in the integration process ready in an API Platform like Postman.

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.

Many requests on the Feedback API require the catalog ID, you can use the Catalog API to retrieve a list of catalogs and the latest active version.