How to Configure the Competition Data API

Owned by Jan Panoušek
Last updated: Sept 29, 2021 by Jana Volencová (Deactivated)
14 min read

The Competition Data API provides an option to make a set of products for which you want to get competition data available to an external data provider. Pricefx admin users can define multiple product sets and make them accessible to a 3rd-party provider who can download this product data and upload competition data related to these products back to Pricefx.

In the following sections, you will learn how to authenticate, how to create product sets, and how to download and upload competition data via Pricefx API.

Authentication and Required Permissions

To authenticate, use the API Protocol v1 or v2. See the Authentication section of the API documentation.

A Pricefx Administrator must set up a new User and share the credentials with the 3rd-party data provider.

One of the following user roles must be assigned to this user:

  • Import & Read Competition Data – This allows the user to get Competition Data Product Sets and download data from, and upload data to, the Competition Data table.

  • Import Competition Data – This allows to get Competition Data Product Sets and upload data to the Competition Data table (without the possibility to download them).

Define Product Sets

In Pricefx, as an admin, you can specify products for which you want to receive competition data by using a simple or complex filter. The products are grouped in so-called product sets which can be accessed externally via API.

In the product set definition, you can set the product fields that you want to expose, allow the field name to be overridden (if overridden, the field name in the API response is different from the field name in Pricefx), and add extra information as needed.

  1. In Pricefx, go to Configuration > System Configuration > External Systems > Competition Data API.

     

  2. Click the New Product Set button.

     

  3. Determine the products for which you want to receive competition data. Specify a filter or select products manually. The filter is stored, not the products, so every time the API is called, an up-to-date list of products is returned.

     

  4. Set the parameters:

    • Name the new product set.

    • Options – Define keys and values containing any extra information (not defined in Pricefx master data) which might be needed to further specify the scope of the required data (e.g., "region":"Asia", "retailer":"Amazon"). The value can be an array (note the 255 character limit). This is optional.

    • Output Elements Mapping – Map Pricefx fields to the corresponding fields in the provider's data structure. Manually edit the Competition Data Provider Field Name column as required. Only selected fields will be sent out via the API. SKU is always selected.

  5. Click Save.

  6. Share the name of the Product Set with the 3rd party data provider. They will need this for retrieving the Product Set (see next step).

Get Competition Data Product Sets

Now you can get the defined Product Sets via Pricefx API. This enables the external data provider to obtain the necessary information on the products for which they will be uploading competition data into Pricefx.

Call the following Pricefx API endpoint:

https://{base url}/pricefx/{partition}/productmanager.fetchproductsetcompetition/{label}

where label is the name of the competition data product set.

The URL to access the API is always in the format https://{base url}/pricefx/{partition}/{api} where the value for {base url} is the same as the URL used to access your partition. When configuring a solution, always check that your base URL matches the domain name of the Pricefx instance that you intend to call.

In the response you get all the products from the product set and their exposed fields and options:

{ "response": { "node": "e2e-node", "csrfToken": "", "startRow": 0, "data": [ { "products": [ { "id": "B-0037", "attributes": [ { "field": "attribute9", "value": "Belgian Dark Ale" }, { "field": "unitOfMeasure", "value": null }, { "field": "lastUpdateDate", "value": "2019-07-15T11:18:26" }, { "field": "attribute6", "value": "5.68" }, { "field": "attribute1", "value": null }, { "field": "currency", "value": "EUR" }, { "field": "attribute3", "value": "DG_01" }, { "field": "attribute2", "value": null }, { "field": "sku", "value": "B-0037" } ] }, { "id": "B-0040", "attributes": [ { "field": "attribute9", "value": "American IPA" }, { "field": "unitOfMeasure", "value": null }, { "field": "lastUpdateDate", "value": "2019-07-15T11:18:26" }, { "field": "attribute6", "value": "1.32" }, { "field": "attribute1", "value": null }, { "field": "currency", "value": "EUR" }, { "field": "attribute3", "value": "DG_03" }, { "field": "attribute2", "value": "A" }, { "field": "sku", "value": "B-0040" } ] } ], "options": [ { "region": "Asia" } ] } ], "endRow": 2, "totalRows": 2, "status": 0 } }

Upload Competition Data to Pricefx

Finally, the 3rd-party provider will send the competition data to Pricefx.

This creates new rows in the Competition Data table. Use the product information fetched in the previous step to create the payload.

https://{base url}/pricefx/{partition}/productmanager.importproductcompetition

Payload:

{ "data": { "products": [ { "sku": "PP-0011", "label": "Tomato mild", "price": 171.50, "currency": "JPY", "competitor": "Pomodori Italia", "competitorSku": "A001", "competitionType": "string", "country": "Japan", "priceUnit": 1, "unitOfMeasure": "string", "infoDate": "2021-09-20T12:14:28.646Z", "additionalInfo1": 0, "additionalInfo2": 100, "additionalInfo4": "seasonal" } ] } }

Get Competition Data

You can download the content of the Competition Data table in Pricefx. This way you can also verify that the upload has been successful. The Import & Read Competition Data user role is required for this action.

Call the following Pricefx API endpoint:

https://{base url}/pricefx/{partition}/productmanager.fetchproductcompetition

Be aware that this returns the entire Competition Data table. The table can grow very large when no mechanism is put in place to delete stale records, and if you are employing multiple data providers, this will return all data, irrespective of the source.

Found an issue in documentation? Write to us.

Â