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 (different brands, different countries, etc), please create a separate subfolder for each. Each shop exports into its own folder: two shops never write into the same folder. If you also need to separate multiple environments (e.g. production vs. a staging or dev store), see Section 2 below.

​
Example Directory Structure

​
2. Separating Environments (dev / staging / prod)

If you send us data from more than one environment for the same shop, don’t mix their files in the same folder. Add one extra folder level, above your shop folders, named after the environment. We recognize three canonical environments:
Guidelines:
  • Use exactly these three folder names — dev, staging, prod — lowercase, no variants. Avoid synonyms like development, preprod, production, qa, or test, since each variant otherwise has to be mapped by hand on our side.
  • You don’t need all three: create only the environment folders you actually send us data from (most clients only need prod).
  • The environment folder sits above the shop/brand/country folders, not the other way around, and above the products / orders / returns folders described in Section 4.
  • If you only have one shop in a given environment, you can skip the shop-level folder and place products / orders / returns directly under the environment folder (e.g. /prod/products).
  • If you only ever send us production data, you don’t need an environment folder at all — the plain structure from Section 1 is enough.
  • Confirm your environment folders with your Kleep contact when your access is provisioned, so they’re mapped correctly on our side from the first export.
  • Only production data goes into prod (or into the plain structure without environment folders). Test or sandbox exports go into dev or staging, even during the first weeks.
  • If you move to another e-commerce platform or export tool, tell us before the first file from the new system arrives.

​
3. 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. Send every file every day, even when there is nothing new: a file with only its header row tells us the export ran. Several days without a file look like a broken export, so tell us in advance of any planned stop.

​
4. 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. They are stored, not imported automatically. 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. The timestamp is the export time, to the second, so that every file has its own name: a file uploaded under the name of an earlier one replaces it. Files are processed in the order they arrive.

​
Example Filename Format

​
5. 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:
  • Every products file holds the whole catalogue, not only the changes since the previous export
  • Export all product variants, including out-of-stock items
  • Keep products that are no longer sold in the file, with active set to false
  • Maintain complete variant information to enable proper sizing analysis
  • Optionally add a deactivation flag for Kleep presence control
Orders and returns files can hold only the records created or changed since the previous export. Please refer to the template for comprehensive field definitions and examples.

​
6. 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: when a record appears in several files, the most recently delivered file wins.

​
7. Data Format Guidelines

All exports should be provided in CSV format. Other formats, compressed files included, are processed only by prior agreement with us. Excel files (.xlsx) are not accepted: they introduce formatting inconsistencies, such as barcodes turned into 1.23E+12.
  • Header row: The first line of every file names the columns, with the field names of the template. Keep the same columns in the same order from one export to the next
  • Separator: Comma (,). If your tool can only write semicolons (;), tell us before the first export
  • Quoting: Put a value that contains the separator, a quote or a line break between double quotes ("), and double the quotes inside it: "Shirt ""Oxford"", white"
  • Encoding: UTF-8, with or without a byte order mark (BOM)
  • Datetime: Use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ , example: 2025-01-15T14:30:00Z. A time zone offset is fine too: 2025-01-15T15:30:00+01:00
  • Boolean values: Use true/false (lowercase) or True/False
  • Decimal values: Use period (.) for decimal separator. Example: 129.99 not 129,99
  • Null values: An empty cell when a value is missing. Never a placeholder such as #N/A, N/A, null or -

​
File Naming Convention

As specified in the SFTP Data Structure Documentation, use the following format:
Examples:
  • products_2025-01-15T02-00-00.csv
  • orders_2025-01-15T02-00-00.csv
  • returns_2025-01-15T02-00-00.csv

​
8. 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. Before sending history, tell us how many rows each data type holds. Split it into files under 1 GB each, for instance one file per month: a file above 4 GB cannot be processed, and it holds back every file sent after it.

​
Example of a Complete SFTP Structure

​
Example With Multiple Environments

The same layout, once a dev / staging / prod split (see Section 2) is added on top: