File specifications,
column by column

Every file is a comma-separated text file with one header row. The rules below are the same for all of them, so your export job implements them once. Column order does not matter, and columns we do not recognise are ignored and listed back to you rather than treated as an error — you can add fields to your extract without breaking anything.

Where files go, and what to call them

You write into a private folder that only your workspace can read or write — how that isolation is enforced is in Security and data protection. Each feed has its own folder, and that folder name is what tells us which feed the file is — the file name itself is a label and a cross-check, never the router. Use any unique value per delivery for the upload folder.

File names are <feed_name>_<YYYYMMDD>.csv, optionally .csv.gz, where the date is the business date the data describes rather than the date you sent it. Split parts take _p<NN>of<NN> and corrections take _r<N>; both are set out in The data we need from you.

<your-workspace>/inbox/feed=inventory_position/<upload-id>/inventory_position_20260731.csv.gz
<your-workspace>/inbox/feed=sales_weekly/<upload-id>/sales_weekly_20260731.csv.gz
<your-workspace>/control/2026-07-31/_manifest_1.json          <- written last

The words used in every table

Required

We cannot use the row without it. On a daily file the row is rejected; on a master or configuration file the whole file is.

Optional

Leave it empty and we apply the default given in the Notes column. Empty is a real answer — do not send a placeholder.

Conditional

Required only in a stated case, and it must be empty otherwise. Size curves are the only feed that uses this.

The columns that uniquely identify a row

Listed under every feed. We match what you send against what we already hold on those columns: if the row is there we update it, if it is not we add it. Sending the same file twice is safe.

What happens to a row that fails

Day-to-day files (stock, sales, orders, forecast) reject only the bad row and load the rest. Master and configuration files are all-or-nothing: one bad row and nothing loads, because a half-loaded product list quietly makes every roll-up on the dashboard wrong with no error on screen.

Rejected rows come back to you

Each delivery produces a rejects file listing the row number, the column, the value we saw, the reason, and a suggested fix — for example that store “0115” probably meant store 115, Riverside Mall.

Files reference each other. A sales row names a size and a store, so both must exist first. You can drop everything into one delivery and let us work out the order — the list below is what that order is, and it is the order to use for your first load.

1. 1
   Roots — nothing depends on anything

   fiscal_calendar, dc, vendor, product_style_color, store_group
2. 2
   Sizes, stores and vendor terms

   product_sku, store, vendor_style_terms
3. 3
   Mappings, curves and date windows

   store_dc_mapping, product_dc_mapping, product_store_eligibility, size_curve, store_status_period, product_status_period, product_supersession, new_store, constraint_set, product_store_rule
4. 4
   Transactions

   inventory_position, purchase_order, sales_weekly, price_promo
5. 5
   Forecast

   forecast_granular, then forecast_layer if you send one
6. 6
   The completion file (manifest), last

   It says the delivery is finished. Write it only once every file above has finished uploading. Section 07 is entirely about it.

You send these once at onboarding, then again whenever they change. Most teams find it easier to send a complete refresh nightly or weekly than to work out what changed; that is fine and is what we expect. A complete refresh never deletes anything — a product or store that disappears from the file is retired, not erased, so two years of history survives a bad extract.

fiscal_calendar — your retail week grid

Which calendar dates make up week 17 of your 2026. Every weekly grid in the platform is addressed by week_start_date, so this file is the root of the whole load.

File name: fiscal_calendar_20260731.csv

Uniquely identifies a row: week_start_date.

week_start_date,week_end_date,fiscal_year,fiscal_week_no,week_label,month_label
2026-07-18,2026-07-24,2026,16,07/18-07/24,July_2026
2026-07-25,2026-07-31,2026,17,07/25-07/31,July_2026
2026-08-01,2026-08-07,2026,18,08/01-08/07,August_2026

dc — your distribution centres

File name: dc_20260731.csv

Uniquely identifies a row: dc_code.

dc_code,dc_name,city,country,serves_channels,status,capacity_units
DC-EAST,East Coast DC,Newark,US,B&M|Ecom,Active,820000
DC-CENT,Central DC,Columbus,US,B&M|Ecom,Active,950000
DC-WEST,West Coast DC,Ontario,US,B&M|Ecom,Active,760000

store — every selling location

Including e-commerce, which you send as a store with channel set to Ecom. Nothing in the platform works without stores.

File name: store_20260731.csv

Uniquely identifies a row: store_code.

store_code,store_name,channel,region,state,store_tier,store_group_default,open_date,close_date,capacity_units,status
115,Riverside Mall,B&M,Midwest,MI,A,Flagship,2011-08-19,,240,Open
704,Northgate Center,B&M,East,VA,A,Flagship,2009-11-12,,250,Open
ECOM01,Ecom - National,Ecom,National,,Online,Ecom,2015-01-01,,,Open

vendor — the suppliers you raise orders on

File name: vendor_20260731.csv

Uniquely identifies a row: vendor_id.

vendor_id,name,incoterm,currency,status
V-100,Apex Footwear Co.,FOB,USD,Active
V-200,Northwind Athletic,DDP,USD,Active
V-300,Corso Leather Works,FOB,USD,Active

product_style_color — every style-colour you plan

The thing a buyer orders and an allocator allocates: 994257 “Trailblazer Runner White/Frost”, not the style behind it and not the individual size.

File name: product_style_color_20260731.csv

Uniquely identifies a row: style_color_id.

style_color_id,description,style_id,color,division,department,class,subclass,product_type,lifecycle_status,product_group,launch_date,image_url,unit_cost,unit_retail,active_flag
994257,Trailblazer Runner White/Frost,9942,White/Frost,Footwear,Men's Footwear,Running,Road Running,Core,Reg Mid Life,Performance Running,2025-10-18,https://cdn.example.com/img/994257.jpg,54.00,120.00,Y
998503,Dash Runner K Blue/Volt,9985,Blue/Volt,Footwear,Kids' Footwear,Running,Kids Running,Core,Reg Mid Life,Kids Performance,2026-01-10,https://cdn.example.com/img/998503.jpg,28.00,65.00,Y

product_sku — every size of every style-colour

The thing that is physically counted. Stock, sales, orders and forecast all reference a size, so nothing transactional loads before this file does.

File name: product_sku_20260731.csv

Uniquely identifies a row: sku_id. A size may appear only once within a style-colour; two rows claiming size 9 make the size curve unresolvable and the file is rejected.

sku_id,style_color_id,size,size_sort_order,barcode
99425701,994257,6,0,"0990001440016"
99425702,994257,7,1,"0990001440023"
99425703,994257,8,2,"0990001440030"

vendor_style_terms — how the vendor actually ships

The four numbers that turn “we need 137 pairs” into an order you can place: lead time, minimum, pack size and order multiple.

File name: vendor_style_terms_20260731.csv

Uniquely identifies a row: vendor_id + style_color_id. One row per pair — a style sourced from two vendors gets two rows.

vendor_id,style_color_id,lead_time_days,moq_eaches,order_multiple_packs,pack_size_eaches,order_cycle,valid_from,valid_to
V-100,994257,21,48,1,6,monthly,2026-01-01,
V-100,994258,21,48,1,6,monthly,2026-01-01,
V-100,994260,21,48,1,6,monthly,2026-01-01,

These arrive every night before the overnight run. They are large and they come from operational systems, so we reject bad rows one at a time rather than losing a whole night’s position to one size that exists in the till system but not yet in your product file.

inventory_position — where the stock is right now

How many of each size are sitting in each store and each distribution centre. This is the single most important file you send.

File name: inventory_position_20260731.csv.gz

Uniquely identifies a row: sku_id + location_type + location_code.

sku_id,location_type,location_code,oh,it,oo,as_of_date
99425703,STORE,115,0,6,0,2026-07-31
99425704,STORE,115,2,6,0,2026-07-31
99425703,STORE,704,4,0,0,2026-07-31
99425703,DC,DC-CENT,312,144,300,2026-07-31

purchase_order — what is on the water

Every open order on a vendor: what is coming, to which distribution centre, and when. One row per order line, with the order-level columns repeated on each line.

File name: purchase_order_20260731.csv

Uniquely identifies a row: po_id + sku_id + po_delivery_date. Whenever an order appears in a file we replace all of its lines with the ones in that file, so re-sending your whole open order book every night is safe and is what we recommend.

po_id,vendor_id,dc_code,order_placed_date,po_status,sku_id,style_color_id,po_delivery_date,on_order_units,line_status,cost
99425703DC-CENT202617,V-100,DC-CENT,2026-07-06,Approved,99425703,994257,2026-08-08,300,Approved,54.00
99425704DC-CENT202617,V-100,DC-CENT,2026-07-06,Approved,99425704,994257,2026-08-08,360,Approved,54.00
99425703DC-EAST202618,V-100,DC-EAST,2026-07-13,Approved,99425703,994257,2026-08-15,180,Approved,54.00

sales_weekly — what actually sold

Units and money, per size, per store, per retail week. At onboarding send 104 weeks if you can and never fewer than 52. After that, send the last four weeks every night — restating the recent weeks absorbs late postings, voids and returns without any risk of double counting.

File name: sales_weekly_20260731.csv.gz

Uniquely identifies a row: week_start + sku_id + store_code.

week_start,sku_id,store_code,units,net_sales,cogs,margin,discount_pct
2026-07-18,99425703,115,7,798.00,378.00,420.00,0.0500
2026-07-25,99425703,115,6,684.00,324.00,360.00,0.0500
2026-07-25,99425703,704,5,600.00,270.00,330.00,0.0000

forecast_granular — your demand forecast

Your forecasting engine’s answer: how many of each size each store will sell each week. One file is one version of the forecast; the newest one becomes the version every screen uses, and we keep the previous ones so accuracy can be measured against them.

File name: forecast_granular_20260731.csv.gz

Uniquely identifies a row: week_start + sku_id + store_code, within one forecast version.

week_start,sku_id,store_code,channel,forecast_units,forecast_retail,lower_bound,upper_bound,launched_flag,model_version,generated_at
2026-08-01,99425703,115,B&M,6.400,768.00,4.100,9.200,Y,fc-2026.07.3,2026-07-31T22:15:00Z
2026-08-01,99425704,115,B&M,7.100,852.00,4.600,10.100,Y,fc-2026.07.3,2026-07-31T22:15:00Z
2026-08-01,99425703,704,B&M,5.200,624.00,3.300,7.500,Y,fc-2026.07.3,2026-07-31T22:15:00Z

forecast_layer — the planner’s view, if you already hold one

The forecast stack per style-colour: the engine number, the planner override, the financial plan, and which of them is being used. Send it only if your own planning system already holds overrides or plan numbers we would otherwise lose. If you do not send it, we build the same view by adding up forecast_granular, and planner edits apply on top of that.

Uniquely identifies a row: week_start + style_color_id + channel.

price_promo — planned price and markdown

What you plan to charge, per style-colour, per channel, per week. Without it the discount panel on the forecast screen is empty: markdown still drives demand, the planner just cannot see why.

Uniquely identifies a row: week_start + style_color_id + channel.

store_dc_mapping — which centre ships to which store

Without this the allocation engine cannot pick a source and the transfer engine cannot work out a lane. Both steps skip and the Action Center is empty, so treat it as required even though it sits with the configuration files.

Uniquely identifies a row: store_code + dc_code.

store_code,dc_code,primary_flag,sourcing_priority,transit_lead_time_days,active_flag
115,DC-CENT,Y,1,2,Y
115,DC-EAST,N,2,4,Y
704,DC-EAST,Y,1,2,Y

size_curve — how demand splits across the size run

One row per size, with each size’s share as a fraction. You can send one curve for a style-colour everywhere, or a different curve for a store group, or for a single store — the most specific one wins when the allocator reads it.

Uniquely identifies a row: style_color_id + scope_type + store_code + store_group_name + size.

style_color_id,scope_type,store_code,store_group_name,size,contribution_fraction,source,curve_version,approved_flag
994257,GLOBAL,,,6,0.065000,USER,1,Y
994257,GLOBAL,,,7,0.129000,USER,1,Y
994257,GLOBAL,,,8,0.204000,USER,1,Y
994257,GLOBAL,,,9,0.237000,USER,1,Y
994257,GLOBAL,,,10,0.204000,USER,1,Y
994257,GLOBAL,,,11,0.108000,USER,1,Y
994257,GLOBAL,,,12,0.053000,USER,1,Y

The remaining configuration files

All optional, all the same shape as the files above, all all-or-nothing. Send them when the underlying policy exists in your systems; skip them and we fall back to the behaviour in the last column.

Write the completion file (manifest) last. It tells us your delivery is finished, so we do not start loading a stock file that is still uploading, and it lets us check that nothing was lost in transit. It goes in the control folder for the business date, and it is the only JSON file in the whole contract. What we do with it on the night, and what happens when it never arrives, is in How your data flows.

{
  "manifest_version": "1.0",
  "workspace": "your-workspace",
  "delivery_id": "5f2b6c1e-9d3a-4a7c-8f10-6b2d9e4c1a77",
  "business_date": "2026-07-31",
  "generated_at": "2026-07-31T23:40:12Z",
  "source_system": "RETAIL-ERP",
  "sequence": 20260731001,
  "is_complete": true,
  "files": [
    {
      "feed_type": "inventory_position",
      "key": "inventory_position_20260731.csv.gz",
      "bytes": 41533712,
      "sha256": "3b1f8a0c9d47e2a5b6c8f1d0e9a2b4c6d8e0f2a4b6c8d0e2f4a6b8c0d2e4f6a8",
      "row_count": 1842551,
      "encoding": "UTF-8",
      "compression": "gzip",
      "mode": "full",
      "extract_watermark": "2026-07-31T22:00:00Z"
    },
    {
      "feed_type": "sales_weekly",
      "key": "sales_weekly_20260731.csv.gz",
      "bytes": 9822104,
      "sha256": "a7c3e1b5d9f2048a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a",
      "row_count": 412887,
      "encoding": "UTF-8",
      "compression": "gzip",
      "mode": "restate",
      "restate_from": "2026-07-18",
      "restate_to": "2026-07-31"
    },
    {
      "feed_type": "purchase_order",
      "key": "purchase_order_20260731.csv",
      "bytes": 2210344,
      "sha256": "c1e5a9d3b7f0246e8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f",
      "row_count": 18422,
      "encoding": "UTF-8",
      "compression": "none",
      "mode": "full"
    }
  ]
}

Why the row count and the checksum are there

They are a safety net, not paperwork. The most common real-world failure is not a badly formatted file — it is a truncated one. A stock extract that dies two-thirds of the way through still parses perfectly, still passes every column rule, and quietly tells us that a third of your estate has no stock. Nothing inside the file can catch that. A row count and a checksum can, in one comparison, before a single row is loaded. If either disagrees we load nothing and tell you, rather than half-loading a day.

The three delivery modes

full

The file is the complete current picture for that feed. Anything absent from it is zeroed (stock) or retired (masters), never left behind. inventory_position must always be full.

delta

Only what changed. Anything absent is left exactly as it was. Safe for masters, never accepted for stock.

restate

The file replaces a bounded window completely — used for sales_weekly, price_promo and forecast_granular. State the window in restate_from and restate_to.

Three outcomes are possible for anything that does not validate: the row is rejected and the rest of the file loads, the whole file is stopped, or we load it and tell you. Which one applies depends on the file, and it is chosen so that a small operational mess never costs you a day and a systematic mistake never loads quietly.

What we correct for you

• Header names are trimmed, lower-cased, and spaces become underscores — so Week_Start and week start both land on week_start. Column order never matters.
• margin defaults to net_sales minus cogs when both are present.
• style_color_id on an order line is filled in from the size when you leave it empty; line_status defaults to the order status.
• Yes/no columns accept true, false, 1, 0, Yes and No in any case.
• A byte-order mark at the start of the file is stripped rather than corrupting your first column name.

How many bad rows are too many

Each file has an error budget. Below it, the bad rows are rejected and the file loads; above it the whole file is held, because at that point the file is telling you something about your extract rather than about your business.

The volume check

This is the one that saves the most days. We compare each file’s row count against the median of your last eight successful deliveries of that feed. If it is more than 40% away in either direction, we hold the file and ask you to confirm before loading it. Nothing is rejected and nothing is lost — it simply waits for a yes.

Getting the rejected rows back

Every delivery produces a rejects file you can read from your folder, one row per rejection, with the row number, the column, the value we saw, the reason, and where we can work it out, a suggestion — "0115" did you mean 115 (Riverside Mall)? Most rejects turn out to be a leading zero, a date format, or a product that has not been set up yet, and the suggestion column usually resolves them without anyone opening a support ticket.

These are the exact files described above, for a small footwear range: five style-colours, the full size 6 to 12 run for 994257, six stores, three distribution centres and three vendors. Every transactional row references only masters that are present in the same set, so you can load the whole thing end to end and see what a good delivery looks like before you write a line of export code.