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”
The products file has one row per variant. Product fields (title, category, gender…) are repeated on every variant row of the product.
Every products file must contain your whole catalogue, not only what changed since the last export, and not only what is in stock:
  • Include every variant of every product, including out-of-stock sizes. 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.
  • Include products that are no longer sold with active set to false, rather than leaving them out.
  • Include children’s products, with is_children set to true.
A product missing from the file can lose its Kleep widget on your site.

​
Which id is the product?

Kleep looks a product up by the reference your product page sends to the Kleep widget. product_id must be exactly that reference. If your catalogue has a model level and a colour level (for instance model TSHIRT001, sold in white TSHIRT001-WH and black TSHIRT001-BK), tell us which of the two your product pages send, and use that one as product_id.

​
Size systems

A size label alone does not always say which size it is. A 40 can be a French 40 or an Italian 40, two sizes apart. An 8 can be a UK 8 or a US 8. When you sell several brands, each brand follows its own size chart, so the same label changes meaning from one product to the next. The size_system field tells us which chart a product’s labels follow, so we read them as you meant them instead of guessing. Use one of the values below. Case does not matter. Give every variant of a product the same value. If a size chart you use is not in this list (German sizes, ages on children’s products, …), send its name as your size guide shows it. Leave the field empty when you don’t know the system: we then work it out from the labels. Tell your Kleep contact that your feed carries size_system, and which values you use, so we set up your integration to read it.

​
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.
You don’t need to return translated titles live if your product feed already includes the title in every language you sell in. In that case, the /product-info endpoint only has to return stocks and prices.
Example response:

​
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
The orders file has one row per order item. Each row names the variant bought, so the size bought is known: an order item without a size-level variant_id cannot be used for sizing.
order_date must be when the order was placed, not when the file was exported or the order last updated. Without it, a history load dates every order on the day it is loaded.

​
3. Return

We define Returns and Return Items in the exact same logic as above. A return line points to the order line it returns: order_id and order_line_id are copied exactly from the order_id and order_item_id of the orders file, and variant_id is the size returned.
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:

​
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. Full catalogue — Every products file holds the whole catalogue, inactive and out-of-stock products included. Orders and returns files can hold only what changed since the previous export
  2. Consistent references — An ID means the same thing in every file: each variant_id in an order or a return exists in the products file, each return line points to an order line
  3. Real values or nothing — Leave a cell empty when you don’t have the value. Never fill it with a placeholder such as #N/A, N/A, null, - or 0
  4. Real dates — Dates say when things happened (order placed, return created), never when the file was exported
  5. Personal data — Customer IDs are opaque references. Never send names, email addresses, phone numbers or postal addresses
  6. Deduplication — A record can appear in several files: the most recently delivered file wins

​
Before your first export

Send your Kleep contact the answers to these questions. They are the ones that otherwise delay an integration:
  • Is the access for production or for a test environment? Only production data goes to production.
  • Which reference does your product page send to the Kleep widget: the model or the colour?
  • Which size guide applies to each product line, and does your feed carry size_system?
  • How many sites or markets do you export, and into which folders?
  • From which date do your orders and returns start, and how many rows does the history hold? See Exporting historical data.
  • If your return reasons are codes, what does each code mean?
  • Who should we contact when a file is missing or malformed?
Questions? If you need clarification on any field requirements or have specific data constraints, please contact our integration team.