Product Matching

Over time, the complexity of matching the right product to a given GTIN / Input has increased significantly. A few years ago, it was much easier to match products on the fly; today, the process varies greatly.

By separating the product matching from the extraction of the more frequent product & offer information, we are also able to limit credit cost increases only for the matching process, rather than for all requests.

Customers can now also benefit from individual timeliness requirements. This and a few other reasons led the Price API to move to an asynchronous product matching process. We will continue to migrate more and more data sources to this approach.

Endpoint Usage

Price API checks the customer's input values against existing matches in the Customer-specific product database and returns the results. If we do not already have a match for the requested value, or the product match is outdated (specified by the max_age parameter), Price API will start the asynchronous process of matching the value.

Typical customer implementations look like this

• have an internal (updated / refreshed) product list
• request all values from your product list through the product matching topic in batches of 1,000 values
• Outdated products and / or new products from the product list trigger a new matching process
• Repeat process for other / more Price API sources

Customer can adjust their timeliness requirements by adjusting the max_age parameter while requesting the product matching topic. Price API uses 30 days by default. It may be useful for customers to lower this setting to actively trigger a re-matching whenever needed.

Customer-specific product database

To optimize convenience for Price API customers, an additional database layer has been developed. This database allows customers to continue using the key GTIN for product_and_offers requests without changing implementations on their side.

The additional database layer will enhance matching rates based on received results and can be individually updated on customer needs (e.g.: more timeliness product matching).

Responses

Using the Product Matching topic will return a number of different responses, which are described below:

Response: Found

Price API found a product match in the database that also meets the customer's timeliness requirement (max_age parameter). This product match is automatically used when a customer requests the topic product_and_offers.

Price API does not charge for this response.

"success": true,
"content": {
    "gtin": "4260426837468",
    "product_id": "shimoda-regenschutz-rucksack-zubehoer-9813688",
    "updated_at": "2024-03-06T04:39:36.000Z"
 }

Response: To be searched

Price API does not find a product matching with the given input parameters.
This could be for 2 reasons:

• New product /: Price API has not found a valid match in the database and is starting to search for a product match with the given input parameters
• Outdated match: Price API has a match in the database, but it does not meet the request age requirement (max_age parameter), Price API will refresh this product match by redoing the work of matching the product

Price API charges for this response.

"success": true,
"reason": "to_be_searched"
"content": {}

Response: Search in progress

Price API is actually already trying to match this product. Processing times may vary depending on system load and complexity. As soon as Price API finishes the product matching process for the given value, the response will change.

Price API does not charge for this response.

"success": true,
"reason": "search_in_progress"
"content": {}

Response: Not found

Price API tried its best but could not find a valid product match for the given input parameters.

Price API does not charge for this response.

"success": true,
"reason": "not found"
"content": {}

Response: Last search failed

Price API tried its best, but even with internal retries we were not able to successfully process this value. There could be several internal/external reasons for this. Receiving this response automatically triggers another product matching attempt from the beginning.

Price API does not charge for this response or the retry itself.

"success": true,
"reason": "last search failed, search_in_progress again"
"content": {}

Charging Mechanism

Customers are only getting charged for the amount of values that result in a Response: To be searched.
We do not charge for any other type of responses (for this topic).

The complexity and cost of generating a proper product match varies from source to source and can change at any time. Typically, this is not something that Price API can influence on its own.

Current credits are listed below:

📘

Adjustment of credits per value

Price API will adjust the amount of credits charged when the complexity of sources changes.
We will notify affected customers in advance.