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.

Catalog Data Fields

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) 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:

{
  "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

Order Data Fields

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.

Return Data Fields

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	`-`

Global-e returns

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). 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), 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). 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.

Best Practices

Consistency — Maintain consistent field names and formats across all exports
Completeness — Include all required fields in every export, including out-of-stock variants
Validation — Validate data before export to ensure quality
Incremental Updates — Use the last_modified_date field to enable efficient processing and ensure fastest updates
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.

Welcome

CMS

Mobile

Dashboard

Data

Privacy

Data Transfers: Template

1. Product

Prices, Stocks & Titles translations

2. Order

3. Return

Notes

Structure and naming

Best Practices

​1. Product

​Prices, Stocks & Titles translations

​2. Order

​3. Return

​Notes

​Structure and naming

​Best Practices

1. Product

Prices, Stocks & Titles translations

2. Order

3. Return

Notes

Structure and naming

Best Practices