Skip to main content
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.
FieldTypePriorityDescriptionExample
product_idStringRequiredID of the main productTSHIRT001
variant_idStringRequiredID of the variantTSHIRT001-M
skuStringRequiredStock-keeping unit — inventory ID, can be the same as the variant_idABC-12345-S-BL
eanStringRequiredEuropean Article Numbering — unique ID of the variant0123456789123
titleStringRequiredTitle of the product"Basic T-shirt"
descriptionStringRequiredProduct’s description as seen on the website"Basic T-shirt perfect for all occasions"
urlStringRequiredURL of the productyour-website.com/basic-tshirt
imagesArrayRequiredList of the product’s images as seen on the website["your-website.com/basic-tshirt/image1.png", ...]
categoryStringRequiredLabel of the product’s category"dress", "t-shirt", "jacket"
genderStringRequiredGender of the product"male", "female"
size_labelStringRequiredLabel of the size of the variant"S", "M", "L"
activeBooleanRequiredBoolean defining if the product is live on the websiteTrue, False
is_newBooleanRequiredProduct badge displayed when the product is newTrue, False
is_childrenBooleanRequiredTrue if the product is for childrenTrue, False
brandStringRequired[Only for multi-brand retailers] Name of the brand the product belongs to"brand-A", "brand-B"
last_modified_dateDateTimeRequiredDate and time when the product was last modified (ISO 8601 format). This allows incremental processing of only updated products.2025-01-15T14:30:00Z
colorStringOptionalName of the product’s color"white", "red"
should_deactivate_kleepBooleanOptionalBoolean 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
FieldTypePriorityDescriptionExample
order_idStringRequiredID of the orderORDER999
order_item_idStringRequiredID of the order itemORDER999-01
product_idStringRequiredID of the main product corresponding to the variantTSHIRT001
variant_idStringRequiredID of the variant orderedTSHIRT001-M
quantityFloatRequiredQuantity ordered of the order item1, 2, 3
customer_idStringRequiredCRM ID of the customer who made the orderC123
last_modified_dateDateTimeRequiredDate 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.
FieldTypePriorityDescriptionExample
return_idStringRequiredInternal ID of the returnRETURN100
return_line_idStringRequiredInternal ID of the return lineRETURN100-01
order_idStringRequiredID of the order which is (partially or totally) returnedORDER999
order_line_idStringRequiredID of the order line of the returned itemORDER999-01
variant_idStringRequiredID of the variant returnedTSHIRT001-M
quantityIntegerRequiredQuantity returned of the order item1, 2, 3
last_modified_dateDatetimeRequiredDate 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_idStringOptionalCRM ID of the customer who made the orderC123
product_idStringOptionalID of the main product corresponding to the variantTSHIRT001
reasonStringOptionalReason of the return"Size too big", "Size too small", "Other"
noteStringOptionalAny 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). 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 DateRMA DateReturn ReasonCart Item IDSKUProduct ReferenceProduct NameQtyProduct AttributesOrder id
GE8301879346NL#4615172767872025-03-29 14:50:472025-07-10 14:04:56Replacement138308146627264217352060935011660_1125_00009Aimilia1”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

  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.