File transfer

File transfers can be used as:

Daily data import

Main data source with scheduled daily uploads to keep your analytics up-to-date

Historical data import

Import historical data that isn’t easily available through current main sources or systems

Supported data types

Costs

Marketing costs data

Indeliveries

Incoming products

Inventory

Stock levels & product attributes

Logistics

Shipping & fulfillment costs

Orders

Customer transactions

Product Attributes

Product metadata & descriptions

Returns

Order return details

File requirements

File naming convention

Files must follow this naming pattern:

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

With optional storefront:

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

File names must be unique. Uploading a new file with the same name will override the existing file.If you need to upload multiple files of the same type for the same date, either:

Merge them into a single file before uploading, or
Use different dates in the filename to distinguish them

Always use yesterday’s date in the filename. Our daily import job runs each morning and only processes files whose {date} equals the previous calendar day. Naming a file with today’s date (or any future date) will cause it to be skipped, resulting in no rows being imported.

merchant

string

required

Your company name

dataType

string

required

One of the supported data types: costs, indeliveries, inventory, logistics, orders, productAttributes, returns

storefront

string

External storefront ID (optional) - assigns entire file to a specific storefront

date

YYYY-MM-DD

required

Last date of data in the file. For daily automated imports, this must always be set to yesterday’s date (today − 1 day). Our daily import job runs each morning and looks specifically for files whose date matches the previous calendar day — a file named with today’s date will not be picked up and will result in no data being imported.Example: If today is 2026-04-15, name your file:

acme_orders_2026-04-14.csv

Files with dates other than yesterday (e.g., for historical data backfills) require manual import by our team.

fileFormat

string

required

One of: .csv, .xls, .xlsx, .parquet

Technical specifications

Specification	Value
Delimiters	Comma `,` or semicolon `;`
Decimal sign	Dot `.` (e.g., `1250.75`)
Multiple values	Pipe-separated and quoted: `"value1\|value2\|value3"`
Column order	Columns can be in any order — we match by header name, not position

Multiple values are only supported on specific fields where noted multi in the schema.

The order of columns in your file does not matter. Our system reads columns by their header name, so feel free to arrange them in whatever order works best for you. Just make sure the header names match the field names listed in the schemas below.

Good to know

COGS priority

Storefront assignment

If you operate multiple storefronts, you can assign data using one of two methods:

Storefront assignment currently applies to orders and returns data types only.

Option 1: Filename-based assignmentInclude the external storefront ID in the filename. This assigns the entire file to one storefront.

acme_SE-STORE_orders_2025-01-15.csv

Option 2: Column-based assignmentInclude the externalStorefrontId column in your data for granular per-row assignment.

Merchant mappings

Setup instructions

Choose your preferred method for uploading files to our platform:

sFTP

Direct upload via secure FTP

Azure Blob Storage

Cloud storage integration with event-driven processing

sFTP
Azure Blob Storage

Contact our customer success team to receive your dedicated sFTP credentials and server details. Once configured, you can upload files directly to your designated folder, and our system will automatically process them.

Request your sFTP credentials through Slack or Teams.

Integrate Azure Blob Storage with our platform using Event Subscriptions.

Prerequisites

An active Azure storage account
Permissions to create event subscriptions
Files following our naming conventions

Navigate to event subscriptions

In the Azure Portal, go to your Storage Account and select Storage → Events → Event Subscription

Create new event subscription

Click + Event Subscription to create a new subscription

Configure settings

Configure the following settings:

Setting	Value
Event schema	Cloud Event Schema v1.0
Event types	Blob Created
Endpoint type	Webhook
Endpoint	`https://s3-blob-webhook.dema.ai/blobs`

Save configuration

Review your settings and click Create to activate the event subscription

Ensure your storage account allows outbound connections to our webhook. For additional support, contact our customer success team with your Azure Storage Account details.

Data schemas

When importing examples into Google Sheets or similar tools, verify that numbers are not malformatted. Pay special attention to decimal points and thousand separators.

Costs

Marketing costs data for campaign tracking and ROI analysis.

See available channel groups and channels for valid values. See Storefront assignment for country-based storefront mapping.

Fields

Example file

date,campaign,campaignId,channel,channelGroup,cost,country,currency
2023-01-15,Summer Sale,CAMP-2023-001,Facebook,Social Paid,1250.75,US,USD
2023-01-15,Summer Sale,CAMP-2023-001,Instagram,Social Paid,875.50,US,USD
2023-01-16,Winter Collection,CAMP-2023-002,Google,Search Paid,2100.25,GB,GBP
2023-01-17,New Arrivals,CAMP-2023-003,CRM,Newsletter,350.00,DE,EUR
2023-01-18,Black Friday,CAMP-2023-004,TikTok,Social Paid,3500.00,US,USD

Indeliveries

Track incoming product deliveries to your warehouses.

Product level fields

Variant level fields

Example file

indeliveryDate,productId,variantNo,quantity,warehouse
2025-01-10,PROD123,VAR001,50,MAIN-WH
2025-01-10,PROD456,VAR002,25,MAIN-WH
2025-01-11,PROD789,VAR003,100,SECOND-WH
2025-01-12,PROD123,VAR001,75,THIRD-WH
2025-01-13,PROD890,VAR005,200,MAIN-WH
2025-01-13,PROD999,VAR010,150,SECOND-WH

Inventory

Stock levels across your warehouses. Product metadata (name, brand, category, etc.) is sent separately via Product Attributes. See COGS priority for how cost values are resolved.

The filename date must be yesterday’s date, not today’s.Both the product and product inventory extractors apply a built-in −1 day date shift: the file is generated today but must be named with yesterday’s date to be picked up by our daily import job.

Today’s date	Correct filename date	Example filename
`2026-04-15`	`2026-04-14`	`acme_inventory_2026-04-14.csv`

A file named with today’s date (e.g. acme_inventory_2026-04-15.csv) will not be processed and will result in “No rows to insert”.

Each row should have a unique productId-variantNo-warehouseId combination. Aggregate inventory quantities per warehouse location.

Version 2 (Current)
Version 1 (Legacy)

The current inventory format. Contains only stock-level and cost fields. Product attributes (name, brand, category, etc.) are sent separately via the Product Attributes data type.

Fields

Example file

productId,variantNo,inventoryQuantity,warehouseId,warehouseName,cogs,currency
PROD123,VAR001,25,WH-001,Main Warehouse,15.50,USD
PROD123,VAR002,18,WH-001,Main Warehouse,15.50,USD
PROD456,VAR003,30,WH-002,Secondary Warehouse,25.00,USD
PROD789,VAR004,100,WH-001,Main Warehouse,8.75,USD
PROD890,VAR005,50,WH-001,Main Warehouse,45.00,EUR

Inventory V1 is the legacy format that includes both stock levels and product attributes in a single table. New integrations should use Version 2 instead.

Product level fields

Variant level fields

Custom attributes

Example file

productId,variantNo,name,currency,brand,category,subCategory,collection,gender,cogs,inventoryQuantity,warehouse,color,material,size,gtin,imageUrls
PROD123,VAR001,Summer Blue Shirt,USD,BrandA,Shirts,T-Shirts,Summer 2024,Women,15.50,25,MAIN-WH,Blue,Cotton,M,7324556789125,https://example.com/shirt-blue-m.jpg
PROD123,VAR002,Summer Blue Shirt,USD,BrandA,Shirts,T-Shirts,Summer 2024,Women,15.50,18,MAIN-WH,Blue,Cotton,L,7324556789132,https://example.com/shirt-blue-l.jpg
PROD456,VAR003,Winter Black Pants,USD,BrandB,Pants,Jeans,Winter 2025,Men,25.00,30,SECOND-WH,Black,Denim,32,7324556789149,https://example.com/pants-black.jpg
PROD789,VAR004,Classic Red Scarf,USD,BrandC,Accessories,Scarves,All-Season,Unisex,8.75,100,MAIN-WH,Red,Wool,ONE,7324556789156,https://example.com/scarf-red.jpg
PROD890,VAR005,Sport Running Shoes,EUR,BrandD,Footwear,Sneakers,Spring 2024,Men,45.00,50,MAIN-WH,White,Synthetic,42,7324556789163,"https://example.com/shoes-white-1.jpg|https://example.com/shoes-white-2.jpg"

Logistics

Shipping and fulfillment costs associated with orders.

The system supports both outbound shipments to customers and return shipments from customers.

Fields

Example file

date,orderId,invoiceNumber,currency,cost,shipmentType
2023-01-21,ORD-2023-001,INV-2023-001,USD,5.99,outbound
2023-01-22,ORD-2023-002,INV-2023-002,EUR,7.99,outbound
2023-01-23,ORD-2023-003,INV-2023-003,GBP,4.99,outbound
2023-02-01,ORD-2023-003,INV-2023-004,GBP,3.50,return
2023-01-24,ORD-2023-004,INV-2023-005,SEK,49.00,outbound
2023-01-25,ORD-2023-005,INV-2023-006,USD,6.50,outbound

Orders

Customer transaction data including order details and line items. See COGS priority for how cost values are resolved.

How order data should be structured

Each row represents a unique order line, identified by the combination of orderId, productId, and variantNo.

Requirement	Description
Unique rows	Each row must have a unique `orderId-productId-variantNo` combination
Quantity handling	If multiple items of the same variant were bought, aggregate them using `quantityDecimal`
Tax inclusion	All prices should include tax
Header repetition	Order header fields (like orderId, currency, total) must be repeated for every line item belonging to the same order
Updates	When updating an order, include the `updatedAt` field along with the changed fields

Order header fields

Required:

Order line fields

Required:Tax fields (one required):

Return fields (within orders)

Include these fields to record returns directly in your orders file.Required (when including returns):

Custom attributes

Order header level:Order line level:

Example file

createdAt,updatedAt,orderId,country,city,region,zipCode,currency,customerIdentifier,externalStorefrontId,paymentProvider,shippingProvider,shipping,status,taxTotal,total,type,voucher,voucherDiscount,voucherType,customAttribute1,customAttribute2,productId,variantNo,quantityDecimal,originalPrice,paidPrice,warehouse,tax,taxRate,cogs,estimatedCogs,estimatedCogsCurrency,promotionId,promotionAmount,promotionType,customAttributeLine1,customAttributeLine2,returnedAt,returnedQuantityDecimal,returnedReason
2023-01-20T10:15:30Z,2023-01-20T10:20:30Z,ORD-2023-001,US,New York,NY,10001,USD,customer123@example.com,STORE-US,Stripe,FedEx,5.99,COMPLETED,7.50,129.95,ONLINE,SUMMER10,5.00,PERCENTAGE,loyalty-gold,referral-friend,PROD123,VAR001,1,29.99,24.99,MAIN-WH,2.50,25,12.00,,,,,gift-wrapped,,,
2023-01-20T10:15:30Z,2023-01-20T10:20:30Z,ORD-2023-001,US,New York,NY,10001,USD,customer123@example.com,STORE-US,Stripe,FedEx,5.99,COMPLETED,7.50,129.95,ONLINE,SUMMER10,5.00,PERCENTAGE,loyalty-gold,referral-friend,PROD456,VAR003,2,49.99,44.99,MAIN-WH,5.00,25,25.00,,,PROMO-001,5.00,PERCENTAGE,express-shipping,,,
2023-01-21T14:22:10Z,2023-01-21T14:25:10Z,ORD-2023-002,DE,Berlin,,10115,EUR,customer456@example.com,STORE-DE,PayPal,DHL,7.99,IN_PROGRESS,5.70,37.96,ONLINE,,,,first-time-buyer,newsletter-signup,PROD789,VAR004,1,9.99,9.99,SECOND-WH,,,8.50,8.50,EUR,,,,,
2023-01-22T09:45:00Z,2023-01-25T14:30:00Z,ORD-2023-003,GB,London,,SW1A 1AA,GBP,customer789@example.com,STORE-UK,Credit Card,Royal Mail,4.99,COMPLETED,6.00,40.98,ONLINE,,,,loyalty-silver,abandoned-cart-recovery,PROD123,VAR002,1,29.99,29.99,MAIN-WH,,20,15.50,,,,,2023-01-30T09:15:00Z,1,Size too small
2023-01-23T16:30:00Z,2023-01-23T16:35:00Z,ORD-2023-004,SE,Stockholm,,11122,SEK,customer999@example.com,STORE-SE,Klarna,PostNord,49.00,COMPLETED,125.00,1000.00,ONLINE,VIP20,100.00,FIXED,loyalty-platinum,influencer-code,PROD890,VAR005,1,600.00,500.00,MAIN-WH,100.00,25,45.00,,,,,priority-fulfillment,,,

Product Attributes

Product metadata including names, categories, and descriptive attributes for your catalog.

Like inventory files, product attribute files generated by the product extractor use a −1 day date shift. Always name the file with yesterday’s date, not today’s.

Each row should have a unique productId-variantNo combination.

Required fields

Optional fields

Custom attributes

Example file

productId,variantNo,name,brand,category,subCategory,collection,gender,color,material,size,gtin,imageUrls
PROD123,VAR001,Summer Blue Shirt,BrandA,Shirts,T-Shirts,Summer 2024,Women,Blue,Cotton,M,7324556789125,https://example.com/shirt.jpg
PROD123,VAR002,Summer Blue Shirt,BrandA,Shirts,T-Shirts,Summer 2024,Women,Blue,Cotton,L,7324556789132,https://example.com/shirt-l.jpg
PROD456,VAR003,Winter Black Pants,BrandB,Pants,Jeans,Winter 2025,Men,Black,Denim,32,7324556789149,https://example.com/pants.jpg
PROD789,VAR004,Classic Red Scarf,BrandC,Accessories,Scarves,All-Season,Unisex,Red,Wool,ONE,7324556789156,https://example.com/scarf.jpg
PROD890,VAR005,Sport Running Shoes,BrandD,Footwear,Sneakers,Spring 2024,Men,White,Synthetic,42,7324556789163,"https://example.com/shoes-1.jpg|https://example.com/shoes-2.jpg"

Returns

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

1. Part of orders

Include return fields directly in your orders data

2. Referenced return

Separate file with order reference

3. Unreferenced return

Separate file without order reference

Referenced returns
Unreferenced returns

Returns that link back to an original order for complete tracking.

Each row should have a unique orderId-productId-variantNo combination. Aggregate returned quantities and include only returns since your last upload.

Fields

Explanation: Snapshot logic

Each return file should contain the latest cumulative state of all returned items for each order. We use snapshot logic, meaning each file replaces the previous state rather than adding to it.Example:

Original order (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 file:
{orderId: 'ORD-001', productId: 'PROD-003', variantNo: 'VAR-001', returnedQuantityDecimal: 1}
{orderId: 'ORD-001', productId: 'PROD-002', variantNo: 'VAR-002', returnedQuantityDecimal: 1}

2nd Return file (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} // +1 item
{orderId: 'ORD-001', productId: 'PROD-001', variantNo: 'VAR-001', returnedQuantityDecimal: 1} // new return

Example file (mixed referenced and unreferenced)

returnedAt,orderId,returnId,productId,variantNo,returnedQuantityDecimal,returnedReason,returnedShipmentStatus,returnedShipmentId,returnedShippingProvider,returnedWarehouse,warehouse,externalStorefrontId,currency,total,taxTotal,paidPrice,tax,taxRate
2023-02-05T14:30:00Z,ORD-2023-001,,PROD123,VAR001,1,Wrong size,DELIVERED,SHIP-RET-001,FedEx,MAIN-WH,MAIN-WH,STORE-US,,,,,,
2023-02-05T14:30:00Z,ORD-2023-001,,PROD456,VAR003,1,Changed mind,DELIVERED,SHIP-RET-001,FedEx,MAIN-WH,MAIN-WH,STORE-US,,,,,,
2023-02-08T11:45:00Z,,RET-2023-001,PROD999,VAR010,1,Wrong item received,DELIVERED,SHIP-RET-004,UPS,SECOND-WH,SECOND-WH,,EUR,89.99,15.00,74.99,,20
2023-02-09T13:20:00Z,,RET-2023-002,PROD111,VAR020,2,Poor quality,DELIVERED,SHIP-RET-005,DHL,MAIN-WH,MAIN-WH,,EUR,159.98,26.66,133.32,26.66,
2023-02-10T09:15:00Z,ORD-2023-003,,PROD123,VAR002,1,Size too small,DELIVERED,SHIP-RET-002,Royal Mail,MAIN-WH,MAIN-WH,STORE-UK,,,,,,
2023-02-11T10:00:00Z,,RET-2023-003,PROD222,VAR030,1,Not as described,DELIVERED,SHIP-RET-006,DHL,MAIN-WH,MAIN-WH,,USD,45.00,,45.00,4.50,
2023-02-12T16:45:00Z,ORD-2023-004,,PROD890,VAR005,1,Defective,IN_TRANSIT,SHIP-RET-003,PostNord,MAIN-WH,MAIN-WH,STORE-SE,,,,,,

Integrations

Daily data import

Historical data import

Supported data types

Costs

Indeliveries

Inventory

Logistics

Orders

Product Attributes

Returns

File requirements

Good to know

Merchant mappings

Setup instructions

sFTP

Azure Blob Storage

Prerequisites

Data schemas

Costs

Indeliveries

Inventory

Logistics

Orders

Product Attributes

Returns

1. Part of orders

2. Referenced return

3. Unreferenced return

Need help?

Contact support

Storefront assignment

Integrations

Daily data import

Historical data import

​Supported data types

Costs

Indeliveries

Inventory

Logistics

Orders

Product Attributes

Returns

​File requirements

​Good to know

​Merchant mappings

​Setup instructions

sFTP

Azure Blob Storage

​Prerequisites

​Data schemas

​Costs

​Indeliveries

​Inventory

​Logistics

​Orders

​Product Attributes

​Returns

1. Part of orders

2. Referenced return

3. Unreferenced return

​Need help?

Contact support

Storefront assignment

Supported data types

File requirements

Good to know

Merchant mappings

Setup instructions

Prerequisites

Data schemas

Costs

Indeliveries

Inventory

Logistics

Orders

Product Attributes

Returns

Need help?