Import product and article information

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:

Import the hierarchy reference book to define the levels in your hierarchy tree.
Import the hierarchy tree structure to create product categories.
Import products and assign each product to a category.
Optional: import articles when you need store-specific information, such as sale prices.

Choose an import method

Use one of the following methods for each import endpoint:

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

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

[
  {
    "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
  }
]

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.

Import hierarchies

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

[
  {
    "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"
  }
]

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.

To modify an existing tree, use the hierarchy patch endpoint. 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.

[
  {
    "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:

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

If the product information already exists in Product Catalog, use article 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.

[
  {
    "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.

[
  {
    "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 synchronized 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:

Reference Book
Hierarchy
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.

​Choose an import method

​Import the hierarchy reference book

​Import hierarchies

​Import products

​Optional: Import articles

​Full article import

​Article prices import

​File content and limitations

​1. Reference Book:

​Example of valid content

​Limitations

​2. Hierarchy

​Example of valid content:

​Limitations

​3. Products

​Products

​Example of valid content:

​API reference

Choose an import method

Import the hierarchy reference book

Import hierarchies

Import products

Optional: Import articles

Full article import

Article prices import

File content and limitations

1. Reference Book:

Example of valid content

Limitations

2. Hierarchy

Example of valid content:

Limitations

3. Products

Products

Example of valid content:

API reference