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

# SFTP Data Structure

## 1. Introduction

This documentation describes how to structure your data files — **products**, **orders**, **returns**, and related data — within our SFTP environment once your dedicated space has been provisioned.

If you operate multiple shops, or have multiple environments (prod, preprod, etc), please create a separate subfolder for each (it could also be different brands, different countries, etc).

### Example Directory Structure

```
/root_space
    /shop_fr
    /shop_en
    /shop_it
```

***

## 2. Data Transmission Schedule

Data files should ideally be transmitted **daily** between:

* **02:00 AM**
* **05:00 AM**

This timeframe ensures optimal processing and data ingestion.

***

## 3. File Organization Standards

Within each shop directory, please create the following folders:

* `products`
* `orders`
* `returns`
* `return_reasons` (optional)
* `misc` (optional)

**Notes:**

* The `return_reasons` folder is used for export files containing additional return data such as reasons provided by customers. These exports are optional.
* The `misc` folder can contain miscellaneous files. If you wish to use this folder, please discuss the hierarchy and structure with us beforehand to ensure compatibility.

Each export should be placed in the appropriate folder and **zero-dated** using a timestamped filename.

### Example Filename Format

```
products_2025-01-15T02-00-00.csv
```

***

## 4. Export Content Requirements

A detailed specification of expected fields, formats, and constraints for each dataset type is available in the **Data Transfers: Template** documentation.

**Key requirements for product catalog exports:**

* Export **all product variants**, including out-of-stock items
* Include a **last modification date** field for incremental processing
* Maintain complete variant information to enable proper sizing analysis
* Optionally add a deactivation flag for Kleep presence control

Please refer to the template for comprehensive field definitions and examples.

***

## 5. Handling Repeated Data Across Exports

Records may legitimately appear in multiple daily exports. For example, a given return may be included several times across different files.

Our ingestion system automatically handles deduplication and processes only the **most recent version** of each record.

***

## 6. Data Format Guidelines

All exports should be provided in **CSV** format.

Excel files (`.xlsx`) are discouraged as they introduce formatting inconsistencies and can complicate automated ingestion workflows.

* **Datetime:** Use ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` , example: `2025-01-15T14:30:00Z`
* **Encoding:** UTF-8 encoding for all text fields, properly escape special characters in CSV
* **Boolean values:** Use `true`/`false` (lowercase) or `True`/`False`
* **Decimal values:** Use period (`.`) for decimal separator. Example: `129.99` not `129,99`
* **Null values:** Empty string for missing optional text fields in csv’s, use null in json’s

### File Naming Convention

***

As specified in the SFTP Data Structure Documentation, use the following format:

```
{data_type}_{timestamp}.csv
```

Examples:

* `products_2025-01-15T02-00-00.csv`
* `orders_2025-01-15T02-00-00.csv`
* `returns_2025-01-15T02-00-00.csv`

***

## 7. Exporting Historical Data

If you need to provide **historical data** (i.e., data that is not part of the daily exports), you may export up to **one year of historical records** for all data types, including:

* **Products**
* **Orders**
* **Returns**

Historical datasets can be transmitted either **through the SFTP** or, if more convenient, **via another agreed-upon medium**.

# Example of a Complete SFTP Structure

```
/root_space
    /shop_fr
        /products
            products_2025-01-15T02-00-00.csv
            products_2025-01-16T02-00-00.csv
        /orders
            orders_2025-01-15T02-00-00.csv
            orders_2025-01-16T02-00-00.csv
        /returns
            returns_2025-01-15T02-00-00.csv
            returns_2025-01-16T02-00-00.csv
        /return_reasons
            return_reasons_2025-01-15T02-00-00.csv  (optional)
        /misc
            (optional, please discuss hierarchy with us)

    /shop_en
        /products
        /orders
        /returns
        /return_reasons
        /misc

    /shop_it
        /products
        /orders
        /returns
        /return_reasons
        /misc

```

***