> ## 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.
# Integrations based on Product Catalog data
> What the Data Platform, orchestration, Promotion Platform and Scan&Pay need from your product hierarchy, products and articles.
Configure Product Catalog data so Data Platform can allocate Personal Offers, Promotion Platform can apply promotions, and Scan\&Pay can identify scanned products. How to load the data is covered in [Import product and article information](/integration/other-integrations/retail-master-data/importing-product-and-article-information).
## Data Platform
Use Product Catalog data to support [Personal Offers](/integration/other-integrations/1-1-personal-offers-management) (offers matched and allocated to customers based on products). Create a consistent product hierarchy and add the attributes needed for accurate product matching.
### Configure the product hierarchy
1. Upload a product hierarchy to Product Catalog Service.
2. Use **5–6 business hierarchy levels** to balance detail and usability.
3. Use this structure consistently: **Division → Department → Category → Subcategory → Class/Segment → SKU → Unique Product ID**.
4. Apply the same grouping logic at each hierarchy level.
For example:
* Food & Grocery → Dairy → Milk & Cream → Milk → Whole Milk → WM-DAIRY-MILK-WH-1L-0234 → 5701234567890
* Food & Grocery → Fruit → Berries → Strawberries → Local Farms → 45231-STRAW-LOCAL → 5701234998877
*Two branches of a product hierarchy, from Food & Grocery down to the SKU and the product ID*
### Group products by customer need
Use the product hierarchy to match products for Personal Offers. Consistent, focused groups improve match quality; inconsistent or overly broad groups reduce offer relevance.
At the **Class/Segment** level—the level directly before the SKU and unique product ID—group products that meet the same customer need and can substitute for each other. Do not group products with different purposes in the same Class/Segment.
When an exact product match is unavailable, Personal Offers can apply an offer at a higher hierarchy level. Keep Class/Segment groups focused so an offer does not apply to products that are irrelevant to the customer.
Limit the number of products in each hierarchy group. Large groups make it more difficult to allocate relevant offers.
### Optional: Add product attributes
Add the following optional Product Catalog Service attributes to improve Personal Offers allocation quality and reduce customer complaints:
* `Brand`
* `SaleUnit`
* `WeightUnit`
* `UnitOfMeasure`
Add the following attributes to further improve offer relevance:
* **Ecological/organic** — indicates whether a product is ecological or organic.
* **Vegetarian/vegan** — indicates whether a product is vegetarian or vegan.
Use the JSON data-import format to add these attributes as product-level metadata (data attached to a product). For example, the following product has the `isEcological` attribute set to `true`:
```json theme={"system"}
[
{
"name": "EcologicalProduct",
"metadata": {
"isEcological": true
}
}
]
```
**CSV imports:** You can use CSV data import, but you must provide metadata as a JSON string in the `Metadata` CSV column. Use full JSON-format imports when possible.
## Orchestration (Segmentation)
Orchestration uses Product Catalog data in the **Product** criterion of the segment builder. Marketers select categories at any level of the hierarchy, or individual products, to target customers by what they bought in a chosen period. Selecting a category includes every product below it.
*The segment builder with the Product attribute listed under Purchase*
### What to set up
| Data | Fields used |
| - | - |
| Hierarchy levels (reference book) | `DepthId`, `Name` |
| Hierarchy nodes | `Id`, `ParentId`, `Name` |
| Products | `ExternalId`, `Name`, `HierarchyId` |
| Purchases (receipt lines) | Product identifier, the same value as the product's `ExternalId` |
The Product attribute belongs to the **Purchase** category, so Purchase data must be enabled for your setup.
### Requirements
1. Purchases must use the same product ID as the catalog (`ExternalId`). Otherwise segments find no customers.
2. Product IDs must stay stable. Don't issue a new `ExternalId` when a product changes.
3. Every product's `HierarchyId` must point to an existing hierarchy node, preferably at the lowest level.
4. Send one level entry per tree level, with business names (these become the column headers marketers see). Levels can't be removed through the API, so never import the sample payload (`Root`, `Level 1`…).
5. Moving a product to another category also moves its past purchases to the new category.
6. Catalog changes show up in the picker within about a day.
*The Product picker, with one column per hierarchy level and the products in the last column*
## Promotion Platform
Use Product Catalog data to apply promotions to individual products or product categories. Configure product identifiers and a consistent category structure before you create a promotion.
### Configure product data
1. Give each product a unique identifier so product-based promotions apply to the intended product.
2. Organize categories logically and use the same category structure throughout the catalog.
* Categories that are too broad can apply discounts to unintended products.
* Categories that are too narrow can create additional setup work to cover all relevant products.
3. When you create a promotion, use the product and category identifiers already imported into Product Catalog.
* An identifier mismatch can prevent a promotion from applying to the intended product.
* An identifier mismatch can apply a promotion to a product the campaign was not designed for.
## Scan\&Pay
Use Product Catalog article data to identify scanned items and display them in the mobile application. Import complete, store-specific article data so customers can scan and purchase the intended items.
### Configure article data
1. Import articles into Product Catalog, including store-specific data such as `salePrice`. A data mismatch or misconfiguration can make an article unavailable during a Scan\&Pay session or confuse the customer.
2. Ensure that EANs or barcodes uniquely identify each article so customers can scan and purchase it during a Scan\&Pay session.
3. Add `ImageUrls` when possible. Scan\&Pay can use placeholders, but product images help customers identify items in the mobile application.
4. Validate article categories beforehand. A misconfiguration can prevent promotions from applying during a Scan\&Pay session, including discounts and post-purchase bonus allocation.
Product attributes such as `Brand`, `SaleUnit`, `WeightUnit`, and `UnitOfMeasure` are important for Scan\&Pay. For example, the mobile application displays a weighted item differently from an item sold by piece, including how it handles discounts.
## API reference
Endpoint documentation: [Products](/api-reference/retail-master-data/products), [Articles V2](/api-reference/retail-master-data/articles-v2).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.