> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobyco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import product and article information

> Import hierarchy, product, and optional article data into Product Catalog for use across Lobyco integrations.

Import hierarchy, product, and optional article data into Product Catalog so it is available to integrations such as Scan\&Pay, Promotion Platform, and the Data Platform.

Complete the imports in this order:

1. Import the [hierarchy reference book](/api-reference/retail-master-data/products/hierarchyreferencebook/post-v1-hierarchyreferencebook-import) to define the levels in your hierarchy tree.
2. Import the [hierarchy tree structure](/api-reference/retail-master-data/products/hierarchies/post-v1-hierarchies-import) to create product categories.
3. Import [products](/api-reference/retail-master-data/products/post-v1-products-import) and assign each product to a category.
4. Optional: import [articles](/api-reference/retail-master-data/articles-v2/post-v2-articles-import) when you need store-specific information, such as sale prices.

## Choose an import method

Use one of the following methods for each import endpoint:

1. **Data Import Service in the Lobyco Admin Portal (recommended):** Select an available import option in the admin portal. It shows the results of each import, including successfully imported entries and validation errors, and lets you retry failed imports.
2. **Direct API integration:** Call the import endpoints from your own integration. You are responsible for the import logic, including error handling.

After you import the hierarchy, product, and article data, it can be used by:

* Mobile apps through Scan\&Pay
* Promotion Platform
* Data Platform, for example when you configure personal offers

What each of them needs from the data is covered in [Integrations based on Product Catalog data](/integration/retail-master-data/product-data-each-service-needs).

## Import the hierarchy reference book

The hierarchy reference book defines the levels available in your hierarchy tree. This import performs **upserts** (updates existing records or creates new records when they do not exist).

```json theme={"system"}
[
  {
    "depthId": 0,
    "name": "Root",
    "externalDepth": -1
  },
  {
    "depthId": 1,
    "name": "Level 1",
    "externalDepth": 1
  },
  {
    "depthId": 2,
    "name": "Level 2",
    "externalDepth": 2
  },
  {
    "depthId": 3,
    "name": "Level 3",
    "externalDepth": 3
  },
  {
    "depthId": 4,
    "name": "Level 4",
    "externalDepth": 4
  },
  {
    "depthId": 5,
    "name": "Level 5",
    "externalDepth": 5
  }
]
```

<Warning>
  Create a root level with no parent identifier. Ensure that the levels in the hierarchy reference book match the depths used by the hierarchy tree you import next. Keep the hierarchy tree compact so product search can traverse it efficiently.
</Warning>

## Import hierarchies

The hierarchy tree organises categories and supports hierarchy management and navigation. Use the hierarchy import endpoint to upsert a tree structure.

```json theme={"system"}
[
  {
    "name": "Root",
    "id": "1001",
    "parentId": null,
    "imageLink": null
  },
  {
    "name": "Food",
    "id": "1002",
    "parentId": "1001",
    "imageLink": null
  },
  {
    "name": "Bakery",
    "id": "1003",
    "parentId": "1002",
    "imageLink": "https://example.com/images/Bakery.png"
  },
  {
    "name": "Groceries",
    "id": "2001",
    "parentId": "1002",
    "imageLink": "https://example.com/images/groceries.png"
  },
  {
    "name": "Beverages",
    "id": "2002",
    "parentId": "2001",
    "imageLink": "https://example.com/images/beverages.png"
  },
  {
    "name": "Snacks",
    "id": "2003",
    "parentId": "2001",
    "imageLink": "https://example.com/images/snacks.png"
  },
  {
    "name": "Soft Drinks",
    "id": "2004",
    "parentId": "2002",
    "imageLink": "https://example.com/images/softdrinks.png"
  },
  {
    "name": "Chips",
    "id": "2005",
    "parentId": "2003",
    "imageLink": "https://example.com/images/chips.png"
  },
  {
    "name": "Chocolate",
    "id": "2006",
    "parentId": "2003",
    "imageLink": "https://example.com/images/chocolate.png"
  }
]
```

<Warning>
  Create one root node with no parent identifier. Give every intermediate node a valid `parentId`; otherwise, the import creates an orphaned hierarchy. `imageLink` is optional and can support enabled features such as Scan\&Pay.
</Warning>

To modify an existing tree, use the [hierarchy patch endpoint](/api-reference/retail-master-data/products/hierarchies/patch-v1-hierarchies-import). It partially imports the hierarchy by upserting existing nodes and adding new leaf nodes or subtrees.

## Import products

Import products to add non-store-specific product information to Product Catalog. The product import endpoint accepts an array of products and upserts each product.

```json theme={"system"}
[
  {
    "name": "White Sandwich Bread 500 g",
    "externalId": "EXT-1001",
    "hierarchyId": "1001",
    "imageLink": "https://example.com/images/bread_white_500.jpg",
    "eans": [
      "4820001000006"
    ],
    "brand": {
      "id": "BR-001",
      "name": "Daily Loaf"
    },
    "suppliers": [
      {
        "id": "SUP-001",
        "name": "Fresh Market"
      },
      {
        "id": "SUP-002",
        "name": "Local Bakery Co."
      }
    ],
    "saleUnit": "piece",
    "weightUnit": "kg",
    "unitOfMeasure": "piece",
    "unitsPerPiece": 1,
    "isWeightable": false,
    "restrictions": [],
    "metadata": {"isEcological": true}
  }
]
```

Provide the following required fields:

* **Product name:** A name that uniquely identifies the product.
* **External identifier:** Your product identifier.
* **Hierarchy identifier:** The identifier of the category the product belongs to.
* **EANs:** Barcodes that can be scanned in store.

Use the `metadata` field to include custom information that is not covered by the product structure.

## Optional: Import articles

Import articles when you need to store store-specific information, such as sale prices. Product Catalog supports two article import types:

1. **Full article import:** Upserts article information, including non-store-specific product details and store-specific details.
2. **Article prices import:** Upserts prices for existing articles only.

If the product information already exists in Product Catalog, use [article prices import](/api-reference/retail-master-data/articles-v2/post-v2-articles-prices-import) instead of a full article import.

### Full article import

Use a full article import to send product and store-specific information in one request.

```json theme={"system"}
[
  {
    "name": "Coca-Cola Classic 1.5L",
    "externalId": "EXT-1001",
    "hierarchyId": "2001",
    "imageLink": "https://example.com/images/cocacola-1-5l.jpg",
    "brand": {
      "id": "Coca-Cola",
      "name": "BR-COCA"
    },
    "eans": [
      "5449000131805"
    ],
    "suppliers": [
      {
        "id": "Metro Cash & Carry",
        "name": "SUP-201"
      },
      {
        "id": "Retail Partners",
        "name": "SUP-202"
      }
    ],
    "saleUnit": "bottle",
    "units": null,
    "unitOfMeasure": "liter",
    "unitsPerPiece": 1,
    "isWeightable": false,
    "restrictions": [],
    "metadata": {
      "isSugarFree": false,
      "volume": "1.5L"
    },
    "depositItemExternalId": null,
    "hamperItemExternalIds": [],
    "prices": [
      {
        "storeId": "-1",
        "salePrice": 19.99,
        "pricePerUnit": null,
        "pricePerPiece": null,
        "isWithoutBarcode": null,
        "taxCode": "VAT20"
      },
      {
        "storeId": "STORE-002",
        "salePrice": 19.99,
        "pricePerUnit": null,
        "pricePerPiece": null,
        "isWithoutBarcode": true,
        "taxCode": "VAT10"
      }
    ]
  }
]
```

Provide the following required fields:

* **Product name**
* **External identifier:** Your product identifier.
* **Hierarchy identifier:** The identifier of the category the product belongs to.
* **EANs:** Barcodes that can be scanned in store.
* **Prices:** Store-level price information, including:
  * **Store identifier:** Your unique store identifier.
  * **Sale price:** The price for the product in that store or group of stores.
  * **Tax code:** The unique tax-code identifier, such as `VAT10`.

When an article has the same price across multiple stores, set `storeId` to `-1` to create a default article price. When a store has its own price, Product Catalog returns that store-specific price instead.

### Article prices import

Use article prices import to update price information for existing articles. You can run this import during business hours because prices change more frequently than other article data.

```json theme={"system"}
[
  {
    "externalId": "EXT-1001",
    "storeId": "-1",
    "salePrice": 19.99,
    "pricePerUnit": null,
    "pricePerPiece": null,
    "isWithoutBarcode": null,
    "taxCode": "VAT20"
  },
  {
    "externalId": "EXT-1001",
    "storeId": "STORE-002",
    "salePrice": 19.99,
    "pricePerUnit": null,
    "pricePerPiece": null,
    "isWithoutBarcode": true,
    "taxCode": "VAT10"
  }
]
```

Provide the following required fields:

* **External identifier:** Your unique product identifier.
* **Store identifier:** Your unique store identifier.
* **Sale price:** The price for the product in that store or group of stores.
* **Tax code:** The unique tax-code identifier, such as `VAT10`.

## File content and limitations

The Product (Catalog) Service is used internally to expose core product (or article) information across different Lobyco features and flows. It serves as a central source for key product attributes, such as names, categories, hierarchy, and base pricing.

Product data is typically synchronised from the retailer’s Product Information Management (PIM) system to ensure consistency of product hierarchy and main product details across the platform. The service does not handle store-specific data (for example, store-level pricing).

Possible Integrations within Lobyco ecosystem:

* Purchase Load Enricher: retrieve the brandId and hierarchy
* Data Platform: required for the 1:1 Personal Offers algorithm: product hierarchy, product attributes
* Shopping List: retrieve the product name

Entities must be loaded sequentially in the following order:

1. Reference Book
2. Hierarchy
3. Products.

## **1. Reference Book**:

* **depthId**: Internal depth level identifier (starting from 0)
* **name**: Specific name for each level (e.g., *Root*, *Level 1*, or client-specific names)
* **externalDepth**: Depth level from the client’s system (e.g., root level might be -1)

### **Example of valid content**

**Json file format:**

```
{"depthId": 0, "name": "Root", "externalDepth": -1}
{"depthId": 1, "name": "Level 1", "externalDepth": 1}
```

**Json format:**

```
POST: /v1/entities/HierarchyReferenceBook/import
Body :
[
  {
    "depthId": 0,
    "name": "Root",
    "externalDepth": -1
  },
  {
    "depthId": 1,
    "name": "Level 1",
    "externalDepth": 1
  }
]
```

### Limitations

* The HierarchyReferenceBook should be created first and it should be created only once.
* An array of hierarchy items. Successful loading depends on the existence of a **reference book with appropriate levels** and **valid hierarchy items** (each with a name, ID, and proper parent-child relationships).
* When the hierarchy is created, products should not be included as a hierarchical level. Hierarchical levels should be created only for categories of products.

## **2. Hierarchy**

This is the format of the hierarchies.

* **name**: Name specific to this hierarchy level
* **id**: Unique identifier of the current item
* **parentId**: Identifier of the parent item (one level above). In case it's a **root item**, the `parentId` should be `null`
* **ImageLink**: Link of hierarchy image. Can be `null`

### **Example of valid content:**

**Json file format:**

```
{"name": "Food", "id": "1", "parentId": null, "imageLink": null}
{"name": "Sweets", "id": "2", "parentId": "1", "imageLink": null}
{"name": "Chocolate", "id": "3", "parentId": "1", "imageLink": null}

```

**Json format:**

```
POST: /v1/entities/Hierarchy/import
Body :
[
  {
    "name": "Food",
    "id": "1",
    "parentId": null,
    "imageLink": null
  },
  {
    "name": "Bakery",
    "id": "2",
    "parentId": "1",
    "imageLink": null
  },
  {
    "name": "Sweets",
    "id": "3",
    "parentId": "1",
    "imageLink": null
  }
]

```

### Limitations

* Hierarchies must be created in a single request. You can't create just the root level in one request and then add additional levels for it in a separate request.
* If you want to update a hierarchy, you must send the **entire structure**, from the root level down to the last category — otherwise, the operation will fail.
* Hierarchical levels should match the depth used when the HierarchyReferenceBook was created.

## **3. Products**

This final step depends on the successful loading of the hierarchy, as it contains the hierarchy identifier.

### **Products**

* **name**: Product name
* **externalId**: Product identifier
* **imageLink**: Product image URL \[**optional**]
* **eans**: Array of EANs and/or UPCs
* **brand**: Brand name and identifier \[**optional**]
* **suppliers**: Array of suppliers with identifiers and names \[**optional**]
* **saleUnit**: Sale unit \[**optional**]
* **weightUnit**: Weight unit \[**optional**]
* **hierarchyId**: Identifier of the hierarchy leaf, which must exist in our DB (`externalId` in our DB, previously referred to as `id` in the contract)

### **Example of valid content:**

**Json file format:**

```
{"name":"Milka chocolate","externalId":"12345","imageLink":"some url","eans":["1234567890123","346534343434"],"brand":{"id":"32","name":"Milka"},"suppliers":[{"id":"432","name":"Some supplier"}],"saleUnit":"12","weightUnit":"321","hierarchyId":"3"}
{"name":"Toblerone 360g","externalId":"54321","imageLink":"some url","eans":["1234567890123","346534343434"],"brand":{"id":"32","name":"Toblerone"},"suppliers":[{"id":"432","name":"Some supplier"}],"saleUnit":"15","weightUnit":"1","hierarchyId":"3"}
{"name":"Whole Grain Bread","externalId":"98765","imageLink":"https://example.com/images/whole-grain-bread.jpg","eans":["8901234567890","8901234567891"],"brand":{"id":"78","name":"PanGust"},"suppliers":[{"id":"876","name":"Rustic Bakery Co."}],"saleUnit":"1","weightUnit":"500g","hierarchyId":"2"}

```

**Json format:**

```
POST: /v1/entities/Product/import
Body:
[
  {
    "name": "Milka chocolate",
    "externalId": "12345",
    "imageLink": "some url",
    "eans": [
      "1234567890123",
      "346534343434"
    ],
    "brand": {
      "id": "32",
      "name": "Milka"
    },
    "suppliers": [
      {
        "id": "432",
        "name": "Some supplier"
      }
    ],
    "saleUnit": "12",
    "weightUnit": "321",
    "hierarchyId": "3"
  },
  {
    "name": "Toblerone 360g",
    "externalId": "54321",
    "imageLink": "some url",
    "eans": [
      "1234567890123",
      "346534343434"
    ],
    "brand": {
      "id": "32",
      "name": "Toblerone"
    },
    "suppliers": [
      {
        "id": "432",
        "name": "Some supplier"
      }
     ],
    "saleUnit": "15",
    "weightUnit": "1",
    "hierarchyId": "3"
  },
  {
    "name": "Whole Grain Bread",
    "externalId": "98765",
    "imageLink": "https://example.com/images/whole-grain-bread.jpg",
    "eans": [
      "8901234567890",
      "8901234567891"
    ],
    "brand": {
      "id": "78",
      "name": "PanGust"
    },
    "suppliers": [
      {
        "id": "876",
        "name": "Rustic Bakery Co."
    }
   ],
   "saleUnit": "1",
   "weightUnit": "500g",
   "hierarchyId": "2"
  }
]
```

## API reference

Endpoint documentation: [Products](/api-reference/retail-master-data/products).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.