--- title: Mandatory Dataset slug: mandatory-dataset createdAt: 2026-03-18T16:36:32.095Z --- The following core dataset files are mandatory for building the Yieldigo instance and must be provided in the structure described below. :::hint{type="info"} Each table indicates the column name in the file, the data type, and a description. Primary keys (unique values) are highlighted in **bold**. ::: ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/YtnkUPBHxOH5ggTNg0F9E-20260323-133917.zip" label="mandatory_dataset.zip"} ## Categories To enable accurate product categorization, a complete list of all product categories must be provided, including both the category names and their hierarchical position within the category tree. ![](https://d3jwyy9rhyhl55.cloudfront.net/v2/4158/contents/iSSJEH0LE25e8GbQ/mw1920_categories.png "Categories") Only one category structure can be implemented — either a Tree or a Horizontal structure. If multiple category structures exist on the client’s side, the client must designate one primary structure to be used for product classification. | **Column** | **Data Type** | **Description** | | ---------------- | ------------- | ------------------------------------------------------------------- | | **category\_id** | string | Unique category identifier | | name | string | Name of the category | | parent\_id | string | Identifier of the parent category. Leave empty for root categories. | ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/bUullneQ4V9E_F513262R-20260323-134128.csv" label="categories.csv"} :::hint{type="warning"} **Data Checks** All rows with an empty parent\_id represent top-level categories. Categories must form a tree-like structure, i.e. an acyclic graph. A category tree typically consists of 3–6 levels. The category hierarchy must be unambiguous — if multiple structures exist, a single primary structure must be chosen. Each category must contain at least some products. ::: **Other Options for Export** An alternative approach to exporting categories is the Horizontal structure. ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/9JbPT-Ck6YsRtYdA5E2CE-20260323-135828.csv" label="horizontal_categories.csv"} ## Products A complete list of all products included in the analysis must be provided. This dataset should contain all essential information for each product, including the product name, description, and any other relevant metadata. Multipacks: If each multipack's pricing is independent of its products, then each multipack should have its unique identifier. However, if the pricing of a multipack depends on the products it contains, then multipacks should not be included in the product table. | **Column** | **Data Type** | **Description** | | ------------------ | -------------- | ------------------------------------------------------------------------------ | | **product\_id** | integer/string | Unique product identifier | | name | string | Name of the product | | status | integer | 0/6/9: 0 - active. 6 - temporarily not active (seasonal). 9 - delisted | | leaf\_category\_id | integer | Identifier of the lowest-level category in the category structure (leaf node). | | vat | decimal | Value-added tax | **Optional Columns** | **Column** | **Data Type** | **Description** | | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | unit\_size | decimal | The product size can be expressed in kilograms, grams, or liters, but the same unit must be used consistently across the entire lowest-level category. | | unit\_count | integer | For multipacks, this value specifies the number of individual products contained in one pack. | ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/1htjlqNOnRmIEaWWXE3X9-20260323-135828.csv" label="products.csv"} :::hint{type="warning"} **Data Checks** Each leaf\_category\_id must reference a leaf node — i.e. the last and most detailed level of the category tree. Active products are defined as items that have been sold in the recent past or are newly listed. unit\_size represents the expected measurement unit within a given category. For example, do not mix grams and kilograms. In case of discrepancies, all values should be converted to kilograms. The prices file should contain entries for the majority of active products. ::: **Other Options for Export** Products, brands, and suppliers may be combined into a single table, but only if each product has exactly **one brand and one supplier assigned**. If a product can be associated with multiple brands or suppliers, this information should be provided in separate files (see sections Brands and Suppliers). **Possible Modifications** - status – a binary field (true/false) can be used. - custom\_data – a column for any additional information the client would like to display on the reporting page. ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/oJdOHIb8fMXtjhWw5Hjm9-20260323-135828.csv" label="product_brands_suppliers.csv"} ## Stores This table is mandatory and may only be omitted if a single price applies to the entire market. | **Column** | **Data type** | **Description** | | ------------- | ------------- | ----------------------- | | **store\_id** | string | Unique store identifier | | name | string | Name of the store | **Optional Columns** | **Column** | **Data Type** | **Description** | | ---------- | ------------- | -------------------------------------------------------- | | city | string | City of the store (used for sourcing local weather data) | ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/ydxoc3qyGR2qGFnE-55qY-20260323-135828.csv" label="stores.csv"} ## Zones A pricing zone is defined as a group of stores that share the same regular sale price. This table is mandatory and may only be omitted if there is a single pricing zone, i.e. all stores use the same price list. | **Column** | **Data type** | **Description** | | ------------- | ------------- | ----------------------- | | **store\_id** | string | Unique store identifier | | zone\_id | string | Zone identifier | | zone\_name | string | Name of the zone | ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/Nt1rCBBqWawuJe0OouBLj-20260323-135828.csv" label="zones.csv"} :::hint{type="info"} All stores within a single zone must share the same price (or be intended to share it in the future). Each existing store must be assigned to exactly one zone. ::: :::hint{type="warning"} **Data Checks** store\_id must not contain any whitespace characters. Each store must be assigned to a zone. ::: **Other Options for Export** Export zone\_id and zone\_name as additional columns in the stores file. ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/nsF9Gk9nr4nZ3Q3WH_1E--20260323-135828.csv" label="stores_zones.csv"} Export zone\_id as a new column in the stores file. The zones file must contain both zone\_id and zone\_name. ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/gfWWOHguA1uh_HvPqZa5w-20260323-135828.csv" label="zones_limited.csv"} ## Actual Prices Provide the current valid regular prices for each zone and product. :::hint{type="info"} **Do you maintain multiple “layers” of price lists?** For example, can promotional and regular prices be valid at the same time? Please provide only regular prices in the data you send. **What is your primary data source for margin calculation?** Is it the purchase price, the cost price, or the stock price? It is important to keep this choice consistent over time. **How is the cost price calculated?** Do you apply retroactive adjustments (e.g. back bonuses)? **Can promotional and regular purchase prices be distinguished?** If yes, please compute the cost price using only the regular purchase prices. **All sale prices must exclude promotional prices.** ::: | **Column** | **Data type** | **Description** | | --------------- | ------------- | --------------------------------------------- | | **product\_id** | string | Product identifier  | | **zone\_id** | string | Zone identifier | | regular\_price | decimal | Actual regular shelf selling price, incl. VAT | | cost | decimal | Cost price, excl. VAT | **Optional Columns** | **Column** | **Data Type** | **Description** | | ---------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------ | | regular\_price\_detail | text | Any additional information related to the regular price, such as its source, tax rates, or other relevant context. | | cost\_detail | text | Any additional information related to the cost, such as its source, calculation logic, or other relevant context. | ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/hOjwiWTxxs_yR2EsuRYXF_prices.csv" label="prices.csv" isUploading="false"} :::hint{type="warning"} **Data Checks** The majority of active products must have an entry in the prices file. All values in the zone\_id column must exist in the zones file. Prices must not include promotional prices. The majority of products should have a positive margin. ::: **Other Options for Export** Export is\_promo\_price as a new boolean column in the prices file. This column enables the export of actual promotional prices. It should be used in cases where the regular price is not available during promotions, and the cost price may vary significantly. ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/ioTks71WUAZbTZkKEKEWI-20260323-135828.csv" label="prices_with_promo_flag.csv"} ## Sales The sales files must contain all sales transactions. Ideally, they should cover **three years of sales history**, including daily increments for the most recent days. For the **first iteration**, please provide **two months of sales data** only. This smaller dataset will be sufficient to verify the format and identify potential data issues. **For sales data, we distinguish between two types:** - **Historical data** – Exported as monthly files in the format: sales-YYYYMM.csv (e.g., sales-201901.csv, sales-201902.csv) - **Incremental data (daily/weekly)** – Exported as files in the format: sales-YYYYMM.csv (monthly) or sales-YYYYMMDD.csv (daily / starting day of the week). :::hint{type="info"} **Deletion of records** – Clarify whether sales records can disappear (e.g., visible one day, missing the next). Consistency of records is required. **Full-day data –** The system requires complete sales data for each day. It is preferable to provide data that is two days old but complete, rather than incomplete data from the previous day. **State of orders (e-shops)** – Define which orders should be treated as final sales, ensuring they are stable and unlikely to be canceled. **Vouchers, discounts, and promotions** – Specify which activities affect the regular sale price and how these can be identified in the data. **Returns** – Returns must not be included in the dataset. ::: | **Column** | **Data Type** | **Description** | | --------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **store\_id** | string | Store identifier | | **product\_id** | string | Product identifier | | **date** | date | Date of the sale (in e-shops, ordering date) | | **price\_type** | integer | 0 - Regular sales (standard price)
2 - Global promotion (discounted price available to all customers - leaflets, special offers)
3 - Individual promotion (targeted coupons, etc.)
4 - End-of-life sellout (clearance)
5 - Expiration markdown
6 - Multibuy discount (discount when buying more than X units)
99 - Other
Rare case: 1 - Regular sales individual price (VIP customer discount, Golden Card) | | quantity | decimal | Sales volume.
May contain decimal values in the case of weighted goods. | | price | decimal | Sale price (incl. VAT).
In the case of aggregated data, use the weighted average (weighted by quantity). | | cost\_price | decimal | Cost price (excl. VAT) for the transaction.
This can be either the cost/stock price or the purchase price from the supplier. In the case of aggregated data, use the weighted average (weighted by quantity).
This value is used to calculate profitability in sales reports and charts and should match the definition currently applied in your systems.
The column must always be filled, never NULL or negative; 0 is acceptable. | **Optional Columns** | **Column** | **Data type** | **Description** | **Usage** | | ----------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | vat | decimal | VAT is applied at the time of sale. | Necessary if VAT is used. | | basket\_id | string | Basket identifier.
Does not have a relation to other tables. | Necessary for basket size insights and analysis. | | promo\_type\_id | string | Promotion Type identifier.
Relates to the table of Promotion Types that is imported separately.
Do not fill if the promotion\_ids column is filled, as that carries more details and this field would be redundant. | Recommended if promotion\_ids cannot be provided. | | promotion\_ids | string | List of Promotion identifiers.
Pipe-delimited when multiple stacked promotions were applied at the same time, e.g. "38123\|23231"
Relates to the table of Promotions History that is imported separately. | Necessary for the full functionality of Promotion Analytics. | | shelf\_price | decimal | The price shown on the price tag that all customers see.
This is the standard price available to everyone, without any basket discounts / employee discounts, or other privileges. | Important for improving price elasticity estimation if customers commonly pay less than the price they see and primarily decide upon. | | timestamp | date | Sales date and time in the format HH\:MM\:SS. | Markdown Management Module. | | batch\_id | string | Batch identifier | Markdown Management Module. | | customer\_id | string | Customer identifier.
Does not have a relation to other tables. | | | segment\_id | string | Customer segment to which the customer belonged.
Relates to the table of Segments that is imported separately. | Allows to see historical sales charts per segment and plan segment-specific promotions. | | bulk\_tier\_limit | decimal | Quantity tier limit that defines when the discounted price applies. | Multibuy Module. | ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/bHe1E6Hu1jRViE6oRQrsD_sales.csv" label="sales.csv" isUploading="false"} :::hint{type="warning"} **Data Checks** Price and shelf\_price must always include VAT (if VAT is applied). Cost price must always exclude VAT. No duplicate records are allowed in the file. promo\_type\_id should contain only values from a predefined, limited set of options. Zero values in the quantity, price, or cost\_price columns must be checked for validity. Transactions with significantly negative margins must be reviewed — they are typically caused by promotions or data errors. ::: **Other Options for Export** Export aggregated by Day/Store/Product/Price Type/Promo Type. Within a single day, multiple rows may exist — one for regular sales and additional rows for each price\_type\_id or promo\_type\_id. ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/sgKm1ryELuMyqyr0qoI02-20260323-135828.csv" label="sales_aggregated.csv"} :::hint{type="danger"} This option is not recommended because it restricts access to certain product features. ::: ## Cross-check Please provide aggregated transaction data once the Sales file structure has been confirmed and valid transaction history has been delivered. This is a one-time export table used to verify data quality after the Sales history is provided. If inconsistencies are found between this manually exported data and the data exported automatically, further investigation will be required to identify and resolve the discrepancies. The purpose of this table is to validate automatically exported data and cross-check sold quantities, revenues, and margins. :::hint{type="info"} Aggregation must be performed at the top-category level. At least 12 months of history must be provided. ::: | **Column** | **Data Type** | **Description** | | ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **month** | string | Month in YYYY-MM format (e.g., 2019-01) | | **category\_id** | string | Category identifier | | **store\_id** | string | Store identifier.
If store\_id is not provided, the data will be considered applicable to all stores within the defined category. | | category\_name | string | Name of category | | store\_name | string | Name of store | | total\_quantity | decimal | Regular + Promo Quantity | | total\_revenue | decimal | Regular + Promo Revenue, excl. VAT | | total\_profit | decimal | Regular + Promo Profit computed as (Total Revenue excl. VAT - Total Costs, excl. VAT) | | promo\_quantity | decimal | Promo Quantity | | promo\_revenue | decimal | Promo Revenue, excl. VAT | | promo\_profit | decimal | Promo Profit computed as (Promo Revenue excl. VAT - Promo Costs, excl. VAT) | ::File{src="https://api.archbee.com/api/presign/xX31HJQLjJcLNeK2EhfOl/QvvSmomXssecblFdDxDbW-20260323-135827.csv" label="cross_check.csv"} :::hint{type="warning"} **Data Checks** Total quantities, revenue, and profit should correspond to expectations.  Total quantities contain either the total number of products or the weighted goods that are not counted in.  Promo share should correspond to expectations. :::