Skip to main content

​
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