> ## 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.
# Data Transfers: Template
In this document, we define the list of data that is required when creating data feeds to integrate Kleep.
The formats and examples shown in the tables below are **indicative only**. They are meant to illustrate which values must correspond to one another across entities (e.g. a `product_id` in the Order table must match the `product_id` in the Product table). The actual format of each reference (IDs, SKUs, etc.) is specific to your shop's own system and may differ from the examples provided.
***
## 1. Product
We differentiate **Products** and **Variants:**
* A **Product** is a piece of clothing available in different sizes. For instance: the "White T-shirt"
* A **Variant** refers to a **Product**'s specific size. For instance: the "White T-shirt in size M"
For each product, please export all variants (for instance even if the variant is out of stock, please include it in the file). This allows our algorithms to understand the product and its sizing. If we receive only one variant per product, we might consider it is one size and deactivate Kleep to avoid confusion. Our past learning on products and brands allows us to continuously improve our size system estimation and remain present on products with very sparse sizes.
| Field | Type | Priority | Description | Example |
| ------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `product_id` | String | Required | ID of the main product | `TSHIRT001` |
| `variant_id` | String | Required | ID of the variant | `TSHIRT001-M` |
| `sku` | String | Required | Stock-keeping unit — inventory ID, can be the same as the variant\_id | `ABC-12345-S-BL` |
| `ean` | String | Required | European Article Numbering — unique ID of the variant | `0123456789123` |
| `title` | String | Required | Title of the product | `"Basic T-shirt"` |
| `description` | String | Required | Product's description as seen on the website | `"Basic T-shirt perfect for all occasions"` |
| `url` | String | Required | URL of the product | `your-website.com/basic-tshirt` |
| `images` | Array | Required | List of the product's images as seen on the website | `["your-website.com/basic-tshirt/image1.png", ...]` |
| `category` | String | Required | Label of the product's category | `"dress"`, `"t-shirt"`, `"jacket"` |
| `gender` | String | Required | Gender of the product | `"male"`, `"female"` |
| `size_label` | String | Required | Label of the size of the variant | `"S"`, `"M"`, `"L"` |
| `active` | Boolean | Required | Boolean defining if the product is live on the website | `True`, `False` |
| `is_new` | Boolean | Required | Product badge displayed when the product is new | `True`, `False` |
| `is_children` | Boolean | Required | `True` if the product is for children | `True`, `False` |
| `brand` | String | Required | **\[Only for multi-brand retailers]** Name of the brand the product belongs to | `"brand-A"`, `"brand-B"` |
| `last_modified_date` | DateTime | Required | Date and time when the product was last modified (ISO 8601 format). This allows incremental processing of only updated products. | `2025-01-15T14:30:00Z` |
| `color` | String | Optional | Name of the product's color | `"white"`, `"red"` |
| `should_deactivate_kleep` | Boolean | Optional | Boolean flag to indicate if Kleep should be deactivated on this product page. Useful for products with single/sparse sizes where sizing recommendations may not be relevant. | `True`, `False` |
### Prices, Stocks & Titles translations
Our solution **Similar Products** uses prices, stocks, and titles. The best option is to expose a single **/product-info** endpoint that returns all this information live.
It takes `product_id` and `market` ([ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)) as input, and returns for each variant its stock quantity, along with the product's `price_amount` (float), `price_currency` (str), `price_discounted_amount` (float, empty if not relevant), and the translated `title` for the requested market language.
Without this endpoint, **Similar Products** may display out-of-stock sizes, will not show prices, and will always use the same language.
Example response:
```json theme={null}
{
"product_id": "TSHIRT001",
"title": "White T-shirt",
"price_amount": 49.90,
"price_currency": "EUR",
"price_discounted_amount": 39.90,
"variants": [
{ "variant_id": "TSHIRT001-S", "stock": 3 },
{ "variant_id": "TSHIRT001-M", "stock": 0 },
{ "variant_id": "TSHIRT001-L", "stock": 12 }
]
}
```
***
## 2. Order
We define **Orders** and **Order Items:**
* An **Order** is the group of **Variants** a customer buys. For instance: "White T-shirt in size M" + "Pink Dress in size L"
* An **Order Item** refers to a specific **Variant** belonging to an order. For instance, from the order above: "Pink Dress in size L" is an **Order Item**
| Field | Type | Priority | Description | Example |
| -------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `order_id` | String | Required | ID of the order | `ORDER999` |
| `order_item_id` | String | Required | ID of the order item | `ORDER999-01` |
| `product_id` | String | Required | ID of the main product corresponding to the variant | `TSHIRT001` |
| `variant_id` | String | Required | ID of the variant ordered | `TSHIRT001-M` |
| `quantity` | Float | Required | Quantity ordered of the order item | `1`, `2`, `3` |
| `customer_id` | String | Required | CRM ID of the customer who made the order | `C123` |
| `last_modified_date` | DateTime | Required | Date and time when the order was last modified (ISO 8601 format). This allows incremental processing of only updated orders. | `2025-01-15T14:30:00Z` |
***
## 3. Return
We define **Returns** and **Return Items** in the exact same logic as above.
| Field | Type | Priority | Description | Example |
| -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| `return_id` | String | Required | Internal ID of the return | `RETURN100` |
| `return_line_id` | String | Required | Internal ID of the return line | `RETURN100-01` |
| `order_id` | String | Required | ID of the order which is (partially or totally) returned | `ORDER999` |
| `order_line_id` | String | Required | ID of the order line of the returned item | `ORDER999-01` |
| `variant_id` | String | Required | ID of the variant returned | `TSHIRT001-M` |
| `quantity` | Integer | Required | Quantity returned of the order item | `1`, `2`, `3` |
| `last_modified_date` | Datetime | Required | Date and time when the return was last modified (ISO 8601 format). This allows incremental processing of only updated returns. | `2025-01-15T14:30:00Z` |
| `customer_id` | String | Optional | CRM ID of the customer who made the order | `C123` |
| `product_id` | String | Optional | ID of the main product corresponding to the variant | `TSHIRT001` |
| `reason` | String | Optional | Reason of the return | `"Size too big"`, `"Size too small"`, `"Other"` |
| `note` | String | Optional | Any comment/note that is left when logging the return | `-` |
**All identifiers refer to the ones used by the Shopify internal order management system:**
* **order\_id**: please provide the Shopify order id, not the Global-e order id. This id is notably present at the end of the Shopify order URL (e.g. `https://admin.shopify.com/store/xyz/orders/5781203157062`). It should look like `5781203157062`
* **order\_line\_id** must be the Shopify order line item id (see [Shopify API documentation](https://shopify.dev/docs/api/storefront/latest/objects/OrderLineItem)). This is not the id of the related variant but the id of the order line that was returned. It should look like `13993313828934`. → This might be called `Cart item id` in the Global-e system
If a return exists in Shopify (i.e. the item is marked as returned in the Shopify system):
* **return\_id**: if the associated return exists in Shopify (see [API documentation](https://shopify.dev/docs/api/admin-graphql/latest/objects/Return)), it should look like `14246216007`
* **return\_line\_id** is analogous to the order line item id, but refers to a line of the return (see [API documentation](https://shopify.dev/docs/api/admin-graphql/latest/objects/ReturnLineItem)). It looks like `24174166343`
If a return doesn't exist in the Shopify system:
* the **variant\_id** is the id of the product variant in the Shopify system (so a product and its size), not the product id. It should look like `42172613361734`
**As a recap, the following data would fit the requirements:**
| GE Order # | Merchant Order # | RMA # | Order Date | RMA Date | Return Reason | Cart Item ID | SKU | Product Reference | Product Name | Qty | Product Attributes | Order id |
| -------------- | ---------------- | ------- | ------------------- | ------------------- | ------------- | -------------- | -------------- | ------------------ | ------------ | --- | ------------------ | ------------- |
| GE8301879346NL | #46151 | 7276787 | 2025-03-29 14:50:47 | 2025-07-10 14:04:56 | Replacement | 13830814662726 | 42173520609350 | 11660\_1125\_00009 | Aimilia | 1 | "Size":"39" | 5781203157062 |
***
## Notes
### Structure and naming
As a reminder, we enforce some naming and file structure conventions in our SFTP space. Please refer to the [SFTP Data Structure Documentation](/data/sftp-structure).
### Best Practices
1. **Consistency** — Maintain consistent field names and formats across all exports
2. **Completeness** — Include all required fields in every export, including out-of-stock variants
3. **Validation** — Validate data before export to ensure quality
4. **Incremental Updates** — Use the `last_modified_date` field to enable efficient processing and ensure fastest updates
5. **Deduplication** — Our system handles duplicate records automatically, processing only the most recent version
***
**Questions?** If you need clarification on any field requirements or have specific data constraints, please contact our integration team.