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.

Price API is doing a proactive Automatic Product Matching in the background and is giving the option to manually adjust frequency on customer needs by connecting directly to the Product Matching Topic API Endpoint.

This Product Matching Topic is available for following sources: Cenowarka, Galaxus, Geizhals, Idealo, Skinflint.

Automatic Product Matching

Automatic Product Matching proactively identifies products that return:

"success": false with the reason "no product matching"
as well as products that repeatedly return "success": true with the reason "not found"

when requested through the product_and_offers topic. For these cases, Price API will now automatically attempt to establish a reliable product mapping in the background on a regular basis.

Automatic matching is now active for: Cenowarka, Galaxus, Geizhals, Idealo, Skinflint (all supported countries).

No changes to your API implementation are required. This automatic matching is performed at no additional cost to you. Once a product has been successfully matched, subsequent product_and_offers requests should return results as usual.

Manual Product Matching still available. The product_matching topic (API endpoint) remains available if you want to proactively trigger a remapping for specific GTINs. Find the documentation described in the points below.

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 searched for this value but received a "not found" response from the source. Hence Price API could not extract a Product ID.

Price API does not charge for this response.

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

Response: Not matchable

Price API tried its best but could not find a valid product match for the given input parameters.
Mostly this is related to so called "loose offers", offers which are not linked to a Product ID.

Price API does not charge for this response.

"success": true,
"reason": "not matchable"
"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:

Source	Topic	Key	Credits per value
Cenowarka	Product matching	GTIN	2
Galaxus	Product matching	GTIN	2
Geizhals	Product matching	GTIN	2
Idealo	Product Matching	GTIN	10
Skinflint	Product matching	GTIN	2

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