Skip to main content

​
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

​
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 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

CategorySupported OptionsExplanation
File formats.csv, .xls, .xlsx, .parquet
DelimitersComma ,, Semicolon ;
Decimal signDot .
Multiple values"value1|value2|value3"Separated by pipe | and wrapped in quotes "

​
Setup instructions

​
sFTP integration

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.

​
Azure Blob Storage integration

To integrate Azure Blob Storage with our platform, you need to configure an Event Subscription that notifies our system whenever new files are uploaded to your storage container.

​
Prerequisites

​
Configuration steps

  1. Navigate to event subscriptions
    • In the Azure Portal, go to your Storage Account
    • Select Storage → Events → Event Subscription
  2. Create new event subscription
    • Click + Event Subscription to create a new subscription
  3. Configure event subscription details
    • Fill in the following settings:
    SettingValueDescription
    Event SchemaCloud Event Schema v1.0Required schema format for our webhook endpoint
    Event TypesBlob CreatedTriggers notification when files are uploaded
    Endpoint TypeWebhookSends notifications to our platform
    Endpointhttps://s3-blob-webhook.dema.ai/blobsOur webhook URL for receiving blob events
  4. Save configuration
    • Review your settings and click Create to activate the event subscription

​
How it works

Once configured:
  1. You upload files to your Azure Blob Storage container
  2. Azure triggers a “Blob Created” event
  3. Our webhook receives the notification
  4. Our system automatically fetches and processes the file
  5. Data becomes available in your Dema app
Important: Ensure your files follow the file name convention specified in this guide. Files that don’t match the expected naming pattern may not be processed correctly.

​
Troubleshooting Azure Blob Storage integration

If you experience issues with Azure Blob Storage integration:
  • Verify that the Event Schema is set to Cloud Event Schema v1.0
  • Confirm the webhook endpoint URL is correct: https://s3-blob-webhook.dema.ai/blobs
  • Check that your storage account allows outbound connections to our webhook
  • Ensure blob names follow our naming convention
For additional support, contact our customer success team with your Azure Storage Account details.

​
Schemas and examples

Important: 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

  • 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.
Column nameFormatData typeDescriptionOptionalExample
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

Column nameFormatData typeDescriptionOptionalExample
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

Column nameFormatData typeDescriptionOptionalMultipleExample
Example 
brand,category,cogs,collection,color,currency,gender,gtin,imageUrls,inventoryQuantity,material,name,productId,size,subCategory,variantNo,warehouse
BrandA,Shirts,15.50,Summer,Blue,USD,Women,7324556789125,https://example.com/shirt-blue.jpg,25,Cotton,Summer Blue Shirt,PROD123,M,Shirts,VAR001,MAIN-WH
BrandA,Shirts,15.50,Summer,Blue,USD,Women,7324556789132,https://example.com/shirt-blue.jpg,18,Polyester,Summer Blue Shirt,PROD123,L,Shirts,VAR002,MAIN-WH
BrandB,Pants,25.00,Winter2025,Black,USD,Men,7324556789149,https://example.com/pants-black.jpg,30,Denim,Winter Black Pants,PROD456,32,Pants,VAR003,SECOND-WH
BrandC,Accessories,8.75,All-Season,Red,USD,Women,7324556789156,https://example.com/scarf-red.jpg,100,Cotton,Classic Red Scarf,PROD789,ONE,Scarves,VAR004,MAIN-WH

​
Logistics

The logistics cost format allows merchants to upload shipping and fulfillment cost data that gets associated with orders. The system supports shipping directions for both outbound shipments to customers and return shipments from customers. Standard CSV format The standard format supports tab-separated or comma-separated CSV files with the following columns:
Column nameFormatData typeDescriptionOptionalMultipleExample
Example 
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

  • 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 for 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.
Column nameFormatData typeDescriptionOptionalExampleDefault
Example 
city,country,createdAt,currency,customerIdentifier,externalStorefrontId,orderCustomAttribute1,orderCustomAttribute2,orderCustomAttribute3,orderCustomAttribute4,orderCustomAttribute5,orderLineCustomAttribute1,orderLineCustomAttribute2,orderLineCustomAttribute3,orderLineCustomAttribute4,orderLineCustomAttribute5,orderId,paymentProvider,region,shipping,shippingProvider,status,taxTotal,total,type,updatedAt,voucher,voucherDiscount,voucherType,zipCode,cogs,cogsCurrency,originalPrice,paidPrice,productId,promotionAmount,promotionId,promotionType,quantityDecimal,returnedAt,returnedQuantityDecimal,returnedReason,returnedShipmentStatus,returnedShipmentId,returnedShippingProvider,returnedWarehouse,shipmentId,shipmentStatus,shippingProviderLine,statusLine,tax,taxRate,variantNo,warehouse
Stockholm,SE,2025-01-13T11:36:45Z,SEK,david@dema.ai,CH-233,VIP customer,Store name,Seasonal sale,Affiliate partner,Loyalty tier,Bundle ID,Bundle name,Subscription plan,Custom engraving,Warranty type,D12345,Klarna,Stockholm,49.00,PostNord,COMPLETED,125.00,1000.00,ONLINE,2025-01-13T11:40:45Z,SUMMER10,100.00,PERCENTAGE,11122,200.00,SEK,900.00,800.00,AK0898,100.00,promotion-12345,PERCENTAGE,1.0,,,,,,,,SHIP-001,DELIVERED,PostNord,COMPLETED,125.00,0.25,VAR001,MAIN-WH
Stockholm,SE,2025-01-13T11:36:45Z,SEK,david@dema.ai,CH-233,VIP customer,Store name,Seasonal sale,Affiliate partner,Loyalty tier,Bundle ID,Bundle name,Subscription plan,Custom engraving,Warranty type,D12345,Klarna,Stockholm,49.00,PostNord,COMPLETED,125.00,1000.00,ONLINE,2025-01-13T11:40:45Z,SUMMER10,100.00,PERCENTAGE,11122,150.00,SEK,600.00,500.00,AK0899,100.00,promotion-12345,PERCENTAGE,2.0,,,,,,,,SHIP-001,DELIVERED,PostNord,COMPLETED,125.00,0.25,VAR002,MAIN-WH
Berlin,DE,2025-01-14T09:22:10Z,EUR,anna@example.com,DE-456,Regular customer,Online store,Winter collection,Direct,Standard,Single item,Standard,Standard,None,Standard,D12346,PayPal,Berlin,7.99,DHL,IN_PROGRESS,15.70,87.96,ONLINE,2025-01-14T09:25:10Z,WINTER15,15.00,PERCENTAGE,10115,25.00,EUR,59.99,59.99,AK0900,15.00,winter-promo,PERCENTAGE,1.0,,,,,,,,SHIP-002,SHIPPED,DHL,COMPLETED,15.70,0.19,VAR003,SECOND-WH
London,GB,2025-01-15T14:45:00Z,GBP,john@example.co.uk,GB-789,Premium customer,Flagship store,Spring launch,Influencer,Gold,Gift set,Premium,Annual,Personalized,Extended,D12347,Credit Card,London,4.99,Royal Mail,COMPLETED,12.00,82.98,ONLINE,2025-01-18T16:30:00Z,SPRING20,20.00,PERCENTAGE,SW1A 1AA,35.00,GBP,69.99,49.99,AK0901,20.00,spring-promo,PERCENTAGE,1.0,2025-01-25T10:15:00Z,1.0,Size too small,DELIVERED,RET-001,Royal Mail,MAIN-WH,SHIP-003,DELIVERED,Royal Mail,COMPLETED,12.00,0.20,VAR004,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 Referenced return
  3. Separate file without an order reference, see Unreferenced return
The last two options can be sent individually or combined with the file type returns. For details on the fields, please refer to Orders.

​
Referenced return

  • 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 referenced returns: 
    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, returnedQuantityDecimal, returnedAt, variantNo
Optional fields:
  • externalStorefrontId, returnedReason, returnedShipmentStatus, returnedShipmentId, returnedShippingProvider, returnedWarehouse, warehouse

​
Unreferenced return

  • Unreferenced returns are 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.
Please include as many fields from the Orders schema as possible to improve data matching and analytics.
Required fields:
  • returnId (replaces orderId, unique identifier for the return)
  • currency, paidPrice, productId, returnedAt, returnedQuantityDecimal, tax, taxTotal, total, variantNo
Example (combination of referenced and unreferenced returns) 
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 customer success team directly for assistance.