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

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

merchant

string

required

Your company name

dataType

string

required

One of the supported data types: costs, indeliveries, inventory, logistics, orders, 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. Should normally be set to yesterday (the last full day of data) to be automatically picked up by our daily import runs. Files with other dates (e.g., for historical data) 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"`

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

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

Merchant mappings assign your external storefront IDs to our platform’s internal storefront IDs. The configuration also optionally assigns country-level marketing cost data to storefronts based on country codes.Setup: Provide the following JSON structure to the commercial team:

[
    {
        "externalStorefrontId": "STORE-001",
        "countries": ["SE", "NO", "DK"]
    },
    {
        "externalStorefrontId": "STORE-002",
        "countries": ["GB"]
    },
    {
        "externalStorefrontId": "STORE-003",
        "countries": ["US"]
    },
    {
        "externalStorefrontId": "STORE-004",
        "countries": []
    }
]

externalStorefrontId

string

required

Your external storefront identifier. Can be any string but preferably something that represents the storefront.

countries

array

Array of ISO 3166 country codes (2 letters) for assigning marketing cost data. Use an empty array [] if no country filtering is needed.

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

date

required

Date of the campaign data (YYYY-MM-DD according to ISO8601).

Format: ISO 8601
Example: 2025-02-20

channel

string

required

Marketing channel used.

Example: Facebook

channelGroup

string

required

Group classification of the channel.

Example: Social paid

cost

number

required

Total cost associated with the campaign.

Example: 1500

country

string

required

Targeted country (2 letters).

Format: ISO 3166
Example: SE

currency

string

required

Currency of the cost data (3 letters).

Format: ISO 4217
Example: SEK

campaign

string

Name of the campaign.

Example: Summer Sale 2025

campaignId

string

Unique identifier for the campaign.

Example: camp_12345

Example file

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

Track incoming product deliveries to your warehouses.

Product level fields

productId

string

required

Unique product identifier.

Example: AK0898

Variant level fields

indeliveryDate

date

required

Expected or actual date of delivery for the items to the warehouse.

Format: ISO 8601
Example: 2025-02-20

quantity

number

required

Quantity of items in delivery.

Format: Non-negative
Example: 1

variantNo

string

required

Product variant number. Unique identifier of product variant (eg. style, color, size).

Example: BUF036

warehouse

string

Warehouse identifier.

Example: warehouse-1

Example file

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

Current stock levels and product attributes across all warehouses.

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

Product level fields

productId

string

required

Unique product identifier. Same as in your datalayer on the website.

Example: AK0898

name

string

required

Product name.

Example: Black Dress no. 1

currency

string

required

Currency code for purchase price.

Format: ISO 4217
Example: SEK

brand

string

Product brand.

Example: brand-1

Logistics

Shipping and fulfillment costs associated with orders.

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

Fields

orderId

string

required

The merchant order ID to associate the cost with.

Example: 4033186

invoiceNumber

string

required

Invoice number for reference and deduplication.

Example: INV-2025-001

date

string

required

Date when the logistics cost was incurred.

Format: ISO 8601
Example: 2025-10-27

currency

string

required

Currency code.

Format: ISO 4217
Example: EUR

cost

number

required

Cost amount.

Format: Decimal
Example: 4.5

shipmentType

enum

required

Direction of shipment: "outbound" for customer deliveries, "return" for customer returns.

Format: outbound | return
Example: outbound

Example file

orderId,invoiceNumber,date,currency,cost,shipmentType
4033186,INV-2025-001,2025-10-27,EUR,4.5,outbound
4033181,INV-2025-002,2025-10-27,EUR,3.2,outbound
4033181,INV-2025-003,2025-10-27,EUR,4.1,return
4033180,INV-2025-004,2025-10-27,EUR,2.8,outbound
4033180,INV-2025-005,2025-10-27,EUR,5.3,return

Orders

Customer transaction data including order details and line items.

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:

orderId

string

required

Unique order identifier from your e-commerce system. Used to link order lines and match with returns.

Example: D12345

createdAt

datetime

required

Timestamp when the order was placed. Used as the primary date for order analytics.

Format: ISO 8601 - UTC
Example: 2025-01-13T11:36:45Z

country

string

required

Customer's country code. Used for geographic segmentation and storefront mapping.

Format: ISO 3166
Example: SE

currency

string

required

Currency of all monetary values in the order (prices, totals, shipping, tax).

Format: ISO 4217
Example: SEK

shipping

number

required

Total shipping fees charged to the customer, including tax. Set to 0 for free shipping.

Format: Non-negative
Example: 80

taxTotal

number

required

Total tax for the entire order, including product tax and shipping tax. Based on final paid amounts.

Format: Non-negative
Example: 200

total

number

required

Final order amount paid by customer after all discounts. Includes tax but excludes shipping. Includes cancelled items.

Format: Non-negative
Example: 3000

updatedAt

datetime

required

Timestamp of the last order modification. Required when updating existing orders with new data.

Format: ISO 8601 - UTC
Example: 2025-01-13T11:36:45Z

city

string

Customer's shipping city. Used for geographic analysis and reporting.

Example: Stockholm

region

string

State, province, or region for the order. Used for regional sales analysis and reporting.

Example: California

zipCode

string

Customer's postal code without spaces. Used for geographic analysis and delivery zone reporting.

Format: No space
Example: 11613

customerIdentifier

string

Unique customer identifier for cohort analysis and repeat purchase tracking. Can be customer ID, email, or hashed email.

Example: [email protected]
Default: UNKNOWN

externalStorefrontId

string

Identifier for the storefront or sales channel where the order originated. Used to separate analytics by storefront.

Example: CH-233

paymentProvider

string

Payment method or provider used for the transaction (e.g., Klarna, Stripe, PayPal, Credit Card).

Example: Klarna

shippingProvider

string

Primary carrier for the order (e.g., UPS, FedEx, DHL, PostNord). Can be overridden per line item.

Example: UPS

status

enum

Overall order fulfillment status. CANCELLED orders are excluded from revenue calculations by default.

Format: PENDING | IN_PROGRESS | COMPLETED | CANCELLED
Example: PENDING
Default: UNKNOWN

type

string

Sales channel type (e.g., ONLINE, RETAIL, WHOLESALE, MARKETPLACE). Used to segment order analytics.

Example: ONLINE
Default: ONLINE

voucher

string

Voucher or discount code entered by the customer at checkout. Used for campaign performance tracking.

Example: BLACK_WEEK25

voucherDiscount

number

Total discount amount applied by the voucher code. Deducted from order total.

Example: 1000

voucherType

string

Category of voucher (e.g., DISCOUNT, FREE_SHIPPING, GIFT_CARD, LOYALTY_REWARD). Used for voucher analysis.

Example: DISCOUNT

Order line fields

Required:

productId

string

required

Unique product identifier. Must match the product ID used in your website's data layer for accurate attribution.

Example: AK0898

variantNo

string

required

Unique variant identifier combining attributes like size and color. Must match inventory data for COGS lookup.

Example: BUF036

quantityDecimal

number

required

Number of units sold. Supports decimals for products sold by weight or length. Aggregate if multiple of the same variant.

Format: Non-negative
Example: 2.5

originalPrice

number

required

Full retail price per unit before any discounts. Including tax, excluding order-level voucher discounts.

Format: Non-negative
Example: 1000

paidPrice

number

required

Actual price paid per unit after item-level discounts. Including tax, excluding order-level voucher discounts.

Format: Non-negative
Example: 900

warehouse

string

required

Fulfillment warehouse for this line item. Used for inventory allocation and logistics analysis.

Example: warehouse-1

Tax fields (one required):

tax

number

Tax amount per unit based on paid price. Required unless taxRate is set.

Format: Non-negative
Example: 30

taxRate

number

Tax rate as a percentage (e.g., 25 for 25% VAT). Required unless tax is set.

Format: Non-negative
Example: 25

cogs

number

Cost of Goods Sold per unit. Overrides COGS from inventory data when specified. Use only if order-level COGS differs from inventory.

Format: Non-negative
Example: 200

cogsCurrency

string

Currency of the COGS value. Required when COGS is specified.

Format: ISO 4217
Example: USD

promotionId

string

Identifier of the promotion rule applied to this item. Links to your promotion management system.

Example: promotion-12345

promotionAmount

string

Discount amount applied per unit from a promotion rule. Used for promotion performance analysis.

Example: 100

promotionType

enum

How the promotion discount is calculated. FIXED for absolute amounts, PERCENTAGE for percentage-based discounts.

Format: FIXED | PERCENTAGE
Example: FIXED

statusLine

enum

Fulfillment status for this specific line item. Overrides the order-level status when set.

Format: PENDING | IN_PROGRESS | COMPLETED | CANCELLED
Example: PENDING

shipmentId

string

Tracking identifier for the outbound shipment from the shipping carrier.

Example: shipment-id

shipmentStatus

enum

Current status of the outbound shipment tracking the item's delivery to the customer.

Format: CREATED | SHIPPED | DELIVERED | CANCELLED
Example: CREATED

shippingProviderLine

string

Carrier for this specific line item. Use when items ship from different locations or via different carriers.

Example: UPS

Return fields (within orders)

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

returnedAt

datetime

required

Timestamp when the return was processed. Used to calculate time-to-return metrics.

Format: ISO 8601 - UTC
Example: 2025-01-14T11:36:45Z

returnedQuantityDecimal

number

required

Number of units returned. Supports decimals for products sold by weight or length.

Format: Non-negative
Example: 1.5

returnedReason

string

Customer's reason for returning the item (e.g., TOO_SMALL, DEFECTIVE, WRONG_ITEM, CHANGED_MIND).

Example: TOO_SMALL

returnedShipmentStatus

enum

Current status of the return shipment tracking the item's journey back to the warehouse.

Format: CREATED | SHIPPED | DELIVERED | CANCELLED
Example: DELIVERED

returnedShipmentId

string

Tracking identifier for the return shipment from the shipping carrier.

Example: shipment-id

returnedShippingProvider

string

Carrier handling the return shipment (e.g., UPS, FedEx, DHL, PostNord).

Example: UPS

returnedWarehouse

string

Destination warehouse where the returned item will be received and processed.

Example: warehouse-1

Custom attributes

Order header level:

customAttribute1-20

string

Up to 20 custom attributes for additional order header metadata.

Example: loyalty-program

Order line level:

customAttributeLine1-20

string

Up to 20 custom attributes for additional order line metadata.

Example: gift-wrapped

Example file

city,country,createdAt,currency,customerIdentifier,externalStorefrontId,orderId,paymentProvider,shipping,shippingProvider,status,taxTotal,total,type,updatedAt,voucher,voucherDiscount,voucherType,zipCode,originalPrice,paidPrice,productId,quantityDecimal,tax,taxRate,variantNo,warehouse,returnedAt,returnedQuantityDecimal,returnedReason
Stockholm,SE,2025-01-13T11:36:45Z,SEK,[email protected],CH-233,D12345,Klarna,49.00,PostNord,COMPLETED,125.00,1000.00,ONLINE,2025-01-13T11:40:45Z,SUMMER10,100.00,PERCENTAGE,11122,900.00,800.00,AK0898,1.0,125.00,0.25,VAR001,MAIN-WH,,,,
Stockholm,SE,2025-01-13T11:36:45Z,SEK,[email protected],CH-233,D12345,Klarna,49.00,PostNord,COMPLETED,125.00,1000.00,ONLINE,2025-01-13T11:40:45Z,SUMMER10,100.00,PERCENTAGE,11122,600.00,500.00,AK0899,2.0,125.00,0.25,VAR002,MAIN-WH,,,,
London,GB,2025-01-15T14:45:00Z,GBP,[email protected],GB-789,D12347,Credit Card,4.99,Royal Mail,COMPLETED,12.00,82.98,ONLINE,2025-01-18T16:30:00Z,SPRING20,20.00,PERCENTAGE,SW1A 1AA,69.99,49.99,AK0901,1.0,12.00,0.20,VAR004,MAIN-WH,2025-01-25T10:15:00Z,1.0,Size too small

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

orderId

string

required

Unique order identifier from your e-commerce system. Used to link order lines and match with returns.

Example: D12345

productId

string

required

Unique product identifier. Must match the product ID used in your website's data layer for accurate attribution.

Example: AK0898

variantNo

string

required

Unique variant identifier combining attributes like size and color. Must match inventory data for COGS lookup.

Example: BUF036

returnedQuantityDecimal

number

required

Number of units returned. Supports decimals for products sold by weight or length.

Format: Non-negative
Example: 1.5

returnedAt

date

required

Timestamp when the return was processed. Used to calculate time-to-return metrics.

Format: ISO 8601 - UTC
Example: 2025-01-14T11:36:45Z

externalStorefrontId

string

Identifier for the storefront or sales channel where the order originated. Used to separate analytics by storefront.

Example: CH-233

returnedReason

string

Customer's reason for returning the item (e.g., TOO_SMALL, DEFECTIVE, WRONG_ITEM, CHANGED_MIND).

Example: TOO_SMALL

returnedShipmentStatus

enum

Current status of the return shipment tracking the item's journey back to the warehouse.

Format: CREATED | SHIPPED | DELIVERED | CANCELLED

returnedShipmentId

string

Tracking identifier for the return shipment from the shipping carrier.

Example: shipment-id

returnedShippingProvider

string

Carrier handling the return shipment (e.g., UPS, FedEx, DHL, PostNord).

Example: UPS

returnedWarehouse

string

Destination warehouse where the returned item will be received and processed.

Example: warehouse-1

warehouse

string

Fulfillment warehouse for this line item. Used for inventory allocation and logistics analysis.

Example: warehouse-1

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

Returns that cannot be linked to an original order.

Without the original order context, some metrics like time-to-return and complete return rate calculations will be estimated and less accurate.

All fields from Orders can be used. Include as many fields as possible to improve data matching and analytics.

Return header fields

Required:

returnId

string

required

Unique return identifier. Used for unreferenced returns when order ID is not available. (replaces `orderId`)

Example: RETURN-1

currency

string

required

Currency of all monetary values in the order (prices, totals, shipping, tax).

Format: ISO 4217
Example: SEK

taxTotal

number

required

Total tax for the entire order, including product tax and shipping tax. Based on final paid amounts.

Format: Non-negative
Example: 200

total

number

required

Final order amount paid by customer after all discounts. Includes tax but excludes shipping. Includes cancelled items.

Format: Non-negative
Example: 3000

Return line fields

Required:

productId

string

required

Unique product identifier. Must match the product ID used in your website's data layer for accurate attribution.

Example: AK0898

variantNo

string

required

Unique variant identifier combining attributes like size and color. Must match inventory data for COGS lookup.

Example: BUF036

returnedQuantityDecimal

number

required

Number of units returned. Supports decimals for products sold by weight or length.

Format: Non-negative
Example: 1.5

returnedAt

date

required

Timestamp when the return was processed. Used to calculate time-to-return metrics.

Format: ISO 8601 - UTC
Example: 2025-01-14T11:36:45Z

paidPrice

number

required

Actual price paid per unit after item-level discounts. Including tax, excluding order-level voucher discounts.

Format: Non-negative
Example: 900

Tax fields (one required):

tax

number

Tax amount per unit based on paid price. Required unless `taxRate` is set.

Format: Non-negative
Example: 30

taxRate

number

Tax rate as a percentage (e.g., 25 for 25% VAT). Required unless `tax` is set.

Format: Non-negative
Example: 25

Example file (mixed referenced and unreferenced)

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,

Integrations

Daily data import

Historical data import

Supported data types

Costs

Indeliveries

Inventory

Logistics

Orders

Returns

File requirements

Merchant mappings

Setup instructions

sFTP

Azure Blob Storage

Prerequisites

Data schemas

Costs

Indeliveries

Inventory

Logistics

Orders

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

Returns

​File requirements

​Merchant mappings

​Setup instructions

sFTP

Azure Blob Storage

​Prerequisites

​Data schemas

​Costs

​Indeliveries

​Inventory

​Logistics

​Orders

​Returns

1. Part of orders

2. Referenced return

3. Unreferenced return

​Need help?

Contact support

Storefront assignment

Supported data types

File requirements

Merchant mappings

Setup instructions

Prerequisites

Data schemas

Costs

Indeliveries

Inventory

Logistics

Orders

Returns

Need help?