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

pageAuthorization to APIs

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

Depending on your requirements, you can define different permission types. For example, only your data push system would need WRITE permissions, while a process that checks the upload status of items only requires READ permissions to the feedback API. It is strongly recommended to restrict permissions as much as possible.

For example, you could setup a type of permission to create/delete schemas, categories and catalogs:

curl -X POST \ 
https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token
 \
-H "Authorization: Bearer ${access_token}" \
--data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
--data "audience=attraqt-items" \
--data "permission=test1:SCHEMAS#WRITE"
--data "permission=test1:CATEGORY_TREES#WRITE"
--data "permission=test1:CATALOGS#WRITE"

For your data gathering, you could set only read permissions:

curl -X POST \ https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token \
-H "Authorization: Bearer ${access_token}" \
--data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
--data "audience=attraqt-items" \
--data "permission=test1:CATALOGS#READ"
--data "permission=test1:ITEMS#READ"

2. Defining a schema

When creating your schema, it is recommended to iterate the schema and load small sample sets of data before adding new attributes.

Your Technical Consultant can give 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

• 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. Please 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. It is highly recommended to use catalog01 as the root for your category tree. If you require a change, please speak to your Technical Consultant.

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

Example:

In the above example, please note that you can have localised values for "trousers" in men and women categories, however, 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

Remember! 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 API.

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, it is recommended to have a (manual) way to query the Feedback API to check on the status of the catalog and future items.

5. Sending items

5a) Sending items to the API

When sending items into a new catalog, it is recommended to keep the parent item and all variants in the same message; this avoids a conflict where the parent item is still in the queue and the variants get rejected.

• The Items API is rate limited to 250 messages per second.

• The recommended message size is less than ~1MB.

Send all the items of your catalog with the rate and size limit.

5b) Dealing with item rejections

The HTTP status code for the Items API will most likely be 200 even if one or more items or variants got rejected in the process.

Please 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"
    }]
}

It is recommended to parse the response of the Items API and at least store the body containing a FAILURE status.

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

• 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, it is highly recommended to 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.

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