File transfer

​

Overview

​

Introduction

Our platform supports multiple methods for data integration through file transfers. You can share your data files in two ways:

1. Direct upload via sFTP
2. Cloud storage integration (such as Azure Blob Storage)

Once your files are uploaded, our system automatically processes and synchronizes the data, making it readily available for analytics and insights on our platform.

​

Data Types

• Costs - Marketing costs data
• Indeliveries - Incoming products
• Inventory - Current stock levels and product attributes
• Orders - Customer transaction data
• Returns - Order return details

​

File name convention

We expect the file to be named the following:

{merchant}_{dataType}_{date}.{fileFormat}

where:

• merchant = Company name
• dataType = One of the values specified in Available Data Types
• date = last date of data (normally ‘yesterday’ as it’s the last day containing a full day of data looking at today)
• fileFormat = One of the values specified under Technical specification

​

Technical Specification

​

Schemas & Examples

​

Costs

• Please reach out to commercial team for more info on the channel groups and channels.
• There is a possibility to map rows to different storefronts by country. In case you want that, we need information on how the mapping should look, see Merchant mappings.

Example

campaign;channel;channelGroup;cost;country;currency;date
Summer Sale;Facebook;Social Paid;1250,75;US;USD;2023-01-15
Summer Sale;Instagram;Social Paid;875,50;US;USD;2023-01-15
Winter Collection;Google;Search Paid;2100,25;GB;GBP;2023-01-16
New Arrivals;CRM;Newsletter;350,00;DE;EUR;2023-01-17

​

Indeliveries

Example

productId;indeliveryDate;quantity;variantNo;warehouse
PROD123;2025-01-10;50;VAR001;MAIN-WH
PROD456;2025-01-10;25;VAR002;MAIN-WH
PROD789;2025-01-11;100;VAR003;SECOND-WH
PROD123;2025-01-12;75;VAR001;THIRD-WH

​

Inventory

Example

brand;category;collection;currency;customAttribute1;customAttribute2;customAttribute3;customAttribute4;customAttribute5;gender;name;productId;subCategory;cogs;color;inventoryQuantity;material;size;variantNo;warehouse
BrandA;Shirts;Summer;USD;;;;;;Women;Summer Blue Shirt;PROD123;;15,50;Blue;25;;M;VAR001;MAIN-WH
BrandA;Shirts;Summer;USD;;;;;;Women;Summer Blue Shirt;PROD123;;15,50;Blue;18;Polyester;L;VAR002;MAIN-WH
BrandB;Pants;Winter2025;USD;;;;;;Men;Winter Black Pants;PROD456;;25,75;Black;30;;32;VAR003;SECOND-WH
BrandC;Accessories;All-Season;USD;;;;;;Women;Classic Red Scarf;PROD789;Scarves;5,25;Red;100;Cotton;ONE;VAR004;MAIN-WH

​

Orders

• Orders are matched on productId and variantId so we expect a unique combination of orderId-productId-variantId. If multiple items of the same variant were bought we expect them be aggregated with quantity: number of items bought.
• All prices should include tax.
• Order header level fields should be repeated for all items in the same order. If an item is returned or updated. we expect the original values for all columns except what has been updated (eg. the returned… fields or status line).
• If an order is updated, please fill out the updatedAt field and the fields that have been updated (eg. return details).
• If you want data mapped to a specific storefront, fill out externalStorefrontId and provide us with info about your existing storefronts, see Merchant mappings.

Example

city;country;createdAt;currency;customerIdentifier;externalStorefrontId;orderId;paymentProvider;region;shipping;shippingProvider;status;taxTotal;total;type;updatedAt;voucher;voucherDiscount;voucherType;zipCode;cogs;originalPrice;paidPrice;productId;promotionAmount;promotionId;promotionType;quantityDecimal;returnedAt;returnedQuantityDecimal;returnedReason;returnedShipmentStatus;returnedShipmentId;returnedShippingProvider;returnedWarehouse;shipmentId;shipmentStatus;shippingProviderLine;statusLine;tax;taxRate;variantNo;warehouse
New York;US;2023-01-20T10:15:30Z;USD;CUST123;STORE-001;ORD-001;Stripe;NY;5,99;FedEx;COMPLETED;7,50;129,95;ONLINE;2023-01-20T10:20:30Z;SUMMER10;15,00;PERCENTAGE;10001;;29,99;24,99;PROD123;0;;;1;;;;;;;;SHIP-001;DELIVERED;FedEx;COMPLETED;2,50;;VAR001;MAIN-WH
New York;US;2023-01-20T10:15:30Z;USD;CUST123;STORE-001;ORD-001;Stripe;NY;5,99;FedEx;COMPLETED;7,50;129,95;ONLINE;2023-01-20T10:20:30Z;SUMMER10;15,00;PERCENTAGE;10001;;49,99;44,99;PROD456;0;;;2;;;;;;;;SHIP-001;DELIVERED;FedEx;COMPLETED;5,00;;VAR003;MAIN-WH
Berlin;DE;2023-01-21T14:22:10Z;EUR;CUST456;STORE-002;ORD-002;PayPal;;7,99;DHL;IN_PROGRESS;5,70;37,96;ONLINE;2023-01-21T14:25:10Z;;;;10115;;9,99;9,99;PROD789;;;;1;;;;;;;;SHIP-002;SHIPPED;DHL;COMPLETED;5,70;;VAR004;SECOND-WH
London;GB;2023-01-22T09:45:00Z;GBP;CUST789;STORE-003;ORD-003;Credit Card;;4,99;Royal Mail;COMPLETED;6,00;40,98;ONLINE;2023-01-25T14:30:00Z;;;;20025;15,50;29,99;29,99;PROD123;;;;1;2023-01-30T09:15:00Z;1;Size too small;DELIVERED;RET-001;Royal Mail;MAIN-WH;SHIP-003;DELIVERED;Royal Mail;COMPLETED;20;VAR002;MAIN-WH

​

Returns

Returns can be sent to us in three ways (listed in preferred order):

1. Part of orders, see Orders
2. Separate file with an order reference, see Return snapshot
3. Separate file without an order reference, see Orphan return

The last two options can be sent in the same file called returns if a combination is needed. For details on the fields, please refer to Orders.

​

Return snapshot

• We expect the file to contain all items that have been returned between uploads (so if one file is sent every day, the file should contain only returns that happened the day before).

• We expect a snapshot, that is, each row should have a unique combination of orderId-productId-variantNo. That is returned quantities should be aggregated, and all returned items from the same order should be included.

  Example of snapshots:

  Copy

  Ask AI

  Original order (only here for context):  
  {orderId: 'ORD-001', products: [{productid: 'PROD-001', variantNo': 'VAR-001', quantity; 1}, {productid: PROD-002', variantNo': 'VAR-002', quantity; 2}, {productid: 'PROD-003', variantNo': 'VAR-001', quantity; 1}]}
  
  1st Return:
  {orderId: 'ORD-001'', productid: 'PROD-003', variantNo': 'VAR-001', returnedQuantityDecimal; 1},
  {orderId: 'ORD-001'', productid: 'PROD-002', variantNo': 'VAR-002', returnedQuantityDecimal; 1}
  
  2nd Return (latest snapshot): 
  {orderId: 'ORD-001'', productid: 'PROD-003', variantNo': 'VAR-001', returnedQuantityDecimal; 1}, (no change) 
  {orderId: 'ORD-001'', productid: 'PROD-002', variantNo': 'VAR-002', returnedQuantityDecimal; 2}, (one additional item returned)
  {orderId: 'ORD-001'', productid: 'PROD-001', variantNo': 'VAR-001', returnedQuantityDecimal; 1}  (new item returned)
  

Required fields:

• orderId, productId, variantNo, returnedQuantityDecimal, returnedAt

Optional fields:

• externalStorefrontId, returnedReason, returnedShipmentStatus, returnedShipmentId, returnedShippingProvider, returnedWarehouse, warehouse

​

Orphan return

• Orphan returns can never be linked to an original order, and hence, it has limitations for certain types of analysis. Without the original order context, metrics like time-to-return and complete return rate calculations will be incomplete.

Required fields:

• returnId (replaces orderId, unique identifier for the return)
• productId, variantNo, returnedAt, returnedQuantityDecimal, taxTotal, total, paidPrice, tax or taxRate

Example (combination of return snapshot and orphan return)

orderId;returnId;productId;variantNo;returnedAt;returnedQuantityDecimal;returnedReason;returnedShipmentStatus;returnedShipmentId;returnedShippingProvider;returnedWarehouse;warehouse;externalStorefrontId;total;taxTotal;paidPrice;tax;taxRate
ORD-001;;PROD-001;VAR-001;2024-03-15T14:30:00Z;1;Wrong size;DELIVERED;RET-001;FedEx;MAIN-WH;MAIN-WH;STORE-001;;;;;
ORD-001;;PROD-002;VAR-002;2024-03-15T14:30:00Z;2;Damaged;DELIVERED;RET-001;FedEx;MAIN-WH;MAIN-WH;STORE-001;;;;;
ORD-002;;PROD-001;VAR-003;2024-03-16T09:15:00Z;1;;;;;;;;;;;;
;RET-001;PROD-003;VAR-004;2024-03-16T11:45:00Z;1;Defective;DELIVERED;RET-003;UPS;MAIN-WH;MAIN-WH;;89.99;15.00;74.99;;0.20
;RET-002;PROD-004;VAR-005;2024-03-16T13:20:00Z;2;Wrong color;DELIVERED;RET-004;UPS;MAIN-WH;MAIN-WH;;159.98;26.66;133.32;26.66;

​

Troubleshooting and Support

For common issues and solutions, contact our support team directly for assistance.