> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.pricer24.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Technical specification for developing a feed to transfer a catalog to Pricer24

# Purpose of the document

This article describes the technical requirements for the JSON feed (file) used to transfer your product catalog to Pricer24.
General principles for working with feeds, supported data formats, and transfer methods are described in [this article](https://help.pricer24.com/en/article/automatic-transfer-of-your-catalog-to-pricer24-general-principles-and-requirements-149kjbm/).

# General Requirements

You provide the feed URL, and Pricer24 regularly downloads the file with your product catalog from this link.

*  Compression: not required. If needed, use gzip.
*  Size limit: none.

The feed (file) must contain the **complete** and **up-to-date** product catalog. After the file is downloaded, Pricer24 automatically compares it with the current catalog and updates only what is needed.
Only the products that are present in the feed (file) at the time it is downloaded are considered up to date.

# JSON feed example:

This is an example of what a feed may look like. The detailed structure and requirements for the feed fields are described [below](#1-struktura-fidu).

```
{
  "categories": [
    { "id": "1000", "parent_id": null, "name": "Groceries" },
    { "id": "1001", "parent_id": "1000", "name": "Confectionery" },
    { "id": "1002", "parent_id": "1001", "name": "Chocolate" }
  ],
  "price_types": [
    { "id": "1", "name": "Warsaw Store 1" },
    { "id": "2", "name": "Warsaw Store 2" },
    { "id": "3", "name": "Krakow Store 1" },
    { "id": "4", "name": "Online" }
  ],
  "properties": [
    { "id": "weight", "name": "Weight (kg)", "type": "decimal" },
    { "id": "stock", "name": "Stock quantity", "type": "int" },
    { "id": "follow_rrp", "name": "Follow RRP", "type": "bool"},
    { "id": "category_manager", "name": "Category manager", "type": "string" }
  ],
  "products": [
    {
      "id": "153",
      "category_id": "1002",
      "name": "Baltic Cocoa Dark Chocolate 70% 100g",
      "vendor": "Baltic Cocoa",
      "vendor_code": "BC-DC70-100",       
      "barcode": "0000000000001",
      "link": "https://example.com/products/baltic-cocoa-dark-chocolate-70-100g",
      "image_link": "https://example.com/products/baltic-cocoa-dark-chocolate-70-100g.jpg",
      "availability": "+",
      "prices": [
        		{ "price_type_id": "1", "price": 9.99, "currency": "PLN" },
        		{ "price_type_id": "2", "price": 9.49, "currency": "PLN" }
      ],
      "properties": {"weight": 0.100, "stock": 20, "follow_rrp": true, "category_manager": "John Smith"}
     },
    {
      "id": "154",
      "category_id": "1002",
      "name": "Vistula Milk Chocolate with Hazelnuts 100g",
      "vendor": "Vistula Sweets",
      "vendor_code": "VS-MH-100",
      "barcode": "0000000000002",
      "link": "https://example.com/products/vistula-milk-chocolate-hazelnuts-100g",
      "image_link": "https://example.com/products/vistula-milk-chocolate-hazelnuts-100g.jpg",
      "availability": "-",
      "prices": [
        		{ "price_type_id": "3", "price": 8.00, "currency": "PLN" },
        		{ "price_type_id": "4", "price": 8, "currency": "PLN" }
      ],
      "properties": {"weight": 0.100, "stock": 0, "follow_rrp": false, "category_manager": "John Smith"}
    }
  ]
}
```

# Feed structure

At the top level, the JSON feed consists of four arrays: categories, price types, properties, and products.

* categories:	product category structure
* price\_types: 	dictionary of price types referenced by product prices 
* properties: additional custom fields not covered by the base contract
* products: 	detailed product catalog

```
{
"categories": [ ... ],
"price_types": [ ... ],
"properties": [ ... ],
"products": [ ... ]
}
```

# The **categories[ ]** array:

The **categories[ ]** array is used to transfer all product categories in the same hierarchy as they exist in your catalog, for example: Pet food → Cat food → Dry cat food → … 
The nesting depth should match your own catalog.
The relationship between categories at different levels is set through **parent\_id**.

Data format of the **categories[ ]** array:
| **Field** | **Data type** | **Required** | **Description** |
| **id** | string | Yes | Product category code (identifier). Unique within the array. Must remain unchanged in each subsequent feed. |
| **parent\_id** | string / null | Yes | Identifier of the parent category. For a root category, the value must be **null**. |
| **name** | string | Yes | Product category name |


Example of the **categories[ ]** array:
```
"categories": 
[
  { "id": "1000", "parent_id": null, "name": "Groceries" },
  { "id": "1001", "parent_id": "1000", "name": "Confectionery" },
  { "id": "1002", "parent_id": "1001", "name": "Chocolate" },
    ...
    ...
  { "id": "100Х", "parent_id": "100(Х-1)", "name": "Dark Chocolate"},
  { "id": "100(Х+1)", "parent_id": "100Х", "name": "Dark Chocolate 100g" }
]
```

# The price\_types[ ] array:

In the **price\_types[ ]**, you define the price types you want to synchronize with our system.
These can be standard price types or prices at specific retail locations or sales channels.
For example:
*     retail price
*     recommended retail price
*     promotional price
*     wholesale price
*     purchase price
*     price of a specific sales channel

Data format of the **price\_types[ ]** array:
| **Field** | **Data type** | **Required** | **Description** |
| **id** | string | Yes | Price type code (identifier). Unique within the array. Must remain unchanged in each subsequent feed. |
| **name** | string | Yes | Price type name. For example: "Retail price", "Promotional price", "RRP", "Warsaw Store", "Online". |

Examples of the **price\_types[ ]** array:

```
[ { "id": "1", "name": "My price" } ]
```
 

```
[ { "id": "1", "name": "Retail price" }, 
  { "id": "2", "name": "Promotional price" }, 
  { "id": "3", "name": "RRP" } ]
```

```
[ { "id": "XXXX", "name": "Krakow Store" }, 
  { "id": "YYYY", "name": "Online" } ]
```

# The properties[ ] array:

In the **properties[ ]** array, you define additional fields, their names, and types, used to synchronize supplementary data. This can include: product stock quantities, the ID or name of the department responsible for the product, the ID or name of the category manager, and so on — any additional information needed for the project.

Data format of the **properties[ ]** array:
| **Field** | **Data type** | **Required** | **Description** |
| **id** | string | Yes | Identifier of the additional field. This is exactly what we will look for in the products array. |
| **name** | string | Yes | Name of the additional field. Used solely to clarify what is being transferred in the corresponding field. |
| **type** | enum | Yes | Synchronization supports a limited set of data types. Supported values: **int**, **decimal**, **bool**, **string**. |

Any property with a different type will be ignored by the system.

Examples of the **properties[ ]** array:

```
[ { "id": "weight", "name": "Weight (kg)", "type": "decimal" } ]
```

```
[ { "id": "stock", "name": "Stock quantity", "type": "int" } ]
```

```
[ { "id": "follow_rrp", "name": "Follow RRP", "type": "bool"}, 
  { "id": "category_manager", "name": "Category manager", "type": "string" } ]
```

The actual property values are set for each product in the **products[ ]** array.

# The products[ ] array:

The **products[ ]** array is the main part of the feed: this is where all your products, their characteristics, availability, and prices are transferred.

Data format of the **products[ ]** array:
| **Field** | **Data type** | **Required** | **Description** |
| **id** | string | Yes | Product code (identifier). It is key for updating the product in Pricer24. It must be **unique** and **permanent** for the same product. Pricer24 uses it to update the same product in subsequent feed versions. |
| **category\_id** | string | Yes | Code (identifier) of the category the product belongs to. Must match one of the ids in the **categories[]** array. |
| **name** | string | Yes | Product name |
| **vendor** | string | No | Product manufacturer name |
| **vendor\_code** | string | No | Product article number (manufacturer code). Transferred if available. |
| **barcode** | string | No | Product barcode (EAN/UPC) |
| **link** | string (URL) | No | Link to the product page on your website |
| **image\_link** | string (URL) | No | Link to the product image |
| **availabilty** | boolean / string | No | Current product availability status |
| **prices** | array<object> | No | Array of product prices (price type, price value, currency) |
| **properties** | object | No | Object containing the values of additional fields in standard JSON format. Contains `key: value` pairs, where `key` is the `property_id` and `value` is the corresponding field's value for the product. |

||| ${color}[#ff0000](⚠ IMPORTANT !) Product, price type, property, and category identifiers (${color}[#ff0000](id)) must remain unchanged in each subsequent feed throughout the entire period of working with Pricer24.

It is by the ${color}[#ff0000](**id**) that Pricer24 determines whether an existing record should be updated or a new one should be created.
The product name can be refined, translated, or expanded, but the ${color}[#ff0000](id) should not be changed if the product remains the same.

||| Changing the ${color}[#ff0000](id) of a product or category that has already been transferred may lead to the loss of previous matches between your products and competitors’ offers.
**In this case, the setup will have to be done again**, which will lead to avoidable financial costs.

# The prices[ ] array inside the product object:
The **product.prices[ ]** array contains all prices you transfer for one specific product.
Each price must reference one of the price types described in the root **price\_types[ ]** array.
First, you describe all price types in the root **price\_types[ ]** array, and then, for each product (in **product.prices[ ]** ), you transfer prices with a reference to the corresponding **id** from the **price\_types[ ]** dictionary..

`product.prices.price_type_id` ← `price_types.id`


Data format of the **product.prices[ ]** array:
| **Field** | **Data type** | **Required** | **Description** |
| **price\_type\_id** | string | Yes | Price type identifier. Must match one of the **ids** in the **price\_types[]** array |
| **price** | number | Yes | Product price for this price type. The value must be a number. Use a dot as the decimal separator, for example  **189.99** |
| **currency** | string | Yes | Price currency according to the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)  ("UAH", "PLN", "USD", "EUR" … ) |

# The properties object inside the product object:

The **product.properties {}** object contains the values of all properties (additional fields) for a specific product. First, you describe all the properties you need in the root **properties[ ]** array, and then, for each product (in **product.properties**), you transfer the corresponding values.

Examples of the **properties** object:

```
{
  ... ,
  "properties": [ ... ],
  "products": [
    {
      ... ,
      "properties": {
      	"weight": 0.100,
      	"stock": 20,
      	"follow_rrp": true,
      	"category_manager": "John Smith"
      }
    },
    {
      ...,
      "properties": {
      	"weight": 0.100,
      	"stock": 0,
      	"follow_rrp": false,
      	"category_manager": "John Smith"
      }
    }
  ]
}
```

||| ${color}[#ff0000](⚠ IMPORTANT !) The value types in `product.properties` must match the types defined in the **properties[ ]** array. For example, if the `stock` property is declared as an integer, but the product transfers its value as a string — `"properties": {"stock": "20"}` — data synchronization will be **completely paused** until the error is fixed.

# The availability field - transfer rules

The **availability** field shows whether the product is in stock. The value can be transferred in the format already used in your catalog.

Examples:
| **Format** | **Product in stock** | **Product out of stock** |
| **boolean** | true | false |
| **string** | "+" | "-" |
| **string** | "1" | "0" |
| **string** | "yes", "in\_stock", "Х", … | "no", "out\_of\_stock", … |