> ## 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.
# Retail Master Data
> Get product and article master data into Lobyco.
Master data is the first integration to get right. A long list of Lobyco services will not function until it is in place, because they all reference your articles, products, stores and transactions.
There are four areas.
| Area | Enables | Detail |
| ----------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **Article data** | Scan\&Pay, self-checkout, local bonus | Below |
| **Product data** | Category-based challenges and offers, 1:1 personal offers, shopping list | Below |
| **Purchase data** | Digital receipts, bonus, challenges | [Transaction Data](/integration/pos-point-of-sale-integrations/transaction-data) |
| **Store data** | Store finder, preferred store, chain- and store-level coupons | [Importing store and chain data](/integration/other-integrations/retail-master-data/importing-store-and-chain-data) |
## Article data
The Product Catalog service manages articles — creating, updating and retrieving them. Article information is **store-specific as well as general**, so the store identifier matters: sale prices differ between stores and chains.
For retrieval you can look up a single article by store and article identifier, or run a configurable search across a set of articles, narrowing by store, by an optional set of article identifiers, and by whether you want only articles sold via displayed barcodes or those available through a catalog such as pastry.
### Import scenarios
| Scenario | What you send | Use when |
| ------------------------ | ---------------------------------------- | ----------------------------------------------------------- |
| **Full** | The complete dataset | You want a comprehensive refresh |
| **Partial** | Modified articles together with new ones | Ongoing maintenance |
| **Incremental (prices)** | Only what changed | Price movements — small enough to run during business hours |
All three upsert the records they carry.
## Product data
The same service stores **core product properties that apply across all stores**. If store-level pricing is not part of your integration, product data alone may be enough.
A product record holds its unique identifier and name, EAN numbers, images, brand, suppliers, and any additional attributes you need.
Products are stored in a **hierarchical tree**, grouping related products under common parent categories — broad classifications down to specific items. That structure is what makes category-based promotions possible.
## Purchase data
Send checkout transactions to Lobyco to allocate benefits and generate digital receipts. The rules, validation and integration options are covered in [Transaction Data](/integration/pos-point-of-sale-integrations/transaction-data).
## Store data
The Store service handles retail chains and individual stores: identifiers, names, contact details, physical location, operational status and opening hours. Chain data carries the branding that unifies stores under one identity — logos, colours and identifiers.
Chains must exist before the stores that reference them. Both can be imported in bulk or maintained individually.
Fields, import modes, validation rules and the order to run imports in are covered in [Importing store and chain data](/integration/other-integrations/retail-master-data/importing-store-and-chain-data).
## Data Import Service
The Data Import Service is the bulk loading path used by Store Service, Offers and others. It validates, processes and imports data from external systems in a controlled, observable way — **asynchronously**, so a large load never blocks your call.
It handles tens of thousands of records or more, and applies back-pressure and throttling so a big import cannot overwhelm the service receiving it.
Use it to migrate from legacy systems, bulk load POS transactions, run scheduled synchronisations, or correct records in bulk.
### How an import runs
### Create the job
Returns a `jobId` that identifies the operation from here on.
### Upload and validate
The file is parsed and every record checked against business rules.
### Process valid records
Validated data is passed to the target service.
### Read the results
Processed, succeeded and failed counts, with detailed errors per failed row.
Poll the job status to follow progress. When rows fail validation, pull the errors, fix the source and re-run.
The **v2 API** creates the job and uploads the file in one request. Prefer it for new integrations — it removes a round trip and a whole class of half-created-job states.
### File formats
Both formats require field names matching the target entity's schema.
| | CSV | JSONL |
| ---------- | ---------------------------------- | ----------------------------------------------------------------- |
| Encoding | UTF-8 | UTF-8 |
| Structure | Header row plus rows | One JSON object per line |
| Delimiters | Comma or semicolon | n/a |
| Suits | Exports from spreadsheets and ERPs | Streaming and high volumes — each line is processed independently |
A JSONL file looks like this:
```json theme={"system"}
{"id": "store-1", "name": "Main Store"}
{"id": "store-2", "name": "Second Store"}
```
## Detailed import guides
* [Importing product and article information](/integration/other-integrations/retail-master-data/importing-product-and-article-information)
* [Importing store and chain data](/integration/other-integrations/retail-master-data/importing-store-and-chain-data)
## API reference
Endpoint documentation: [Retail Master Data](/api-reference/retail-master-data) and [Data Import](/api-reference/data-import).