This feature was built to give stores a reliable path into Run Free when a direct POS integration isn't available.
Quick-Start: which option should I use?
The platform offers two distinct import paths. They are different tools with different rules:
| Inventory Update (the "small" import) | Full Product Info (the "big" import) |
Use when | You're pushing nightly/periodic stock-count updates for products that already exist in Run Free. | You're onboarding new products, fixing product details (names, prices, images, categories), or doing a one-time bulk catalog load. |
Speed | Queued. Typically processes within about an hour. | Real-time. Each row is processed as the file uploads. |
Column-mapping UI | No. Headers must match exact, case-sensitive names. | Yes. Your spreadsheet headers can be anything; you map them to Run Free fields in the browser. |
Updates existing inventory? | Yes - this is its primary purpose. | Yes. |
Creates new products? | No. Unknown rows are silently skipped. | Yes, when |
Updates product details (name, description, images)? | No. Only inventory fields are read. | Yes, on existing and new products (with caveats noted below). |
Required columns |
|
|
If you just need to push stock counts, use Inventory Update. If you're doing anything else, use Full Product Info.
If you only remember five things
Save your spreadsheet as a CSV file before uploading.
If you're using Inventory Update, the header names must match exactly:
UPC,Quantity, andStoreif you have more than one location.Quantitymust be a whole number like0,1, or12. Do not use1.0,2.5, or1,200.Do not open files with UPC codes in them inside Excel. Excel will turn UPCs into scientific notation and ruin them. Just opening the file will ruin it, you don't even have to save it to mess it up. Thanks again Microsoft!
If you're adding brand-new products, use Full Product Info, not Inventory Update.
Import Tool #1: The Inventory Update
Use this option when your products are already set up in Run Free and you just need to push new quantity numbers.
What it does (and what it doesn't)
Inventory Update only changes what is in the file. It does not zero out products that are missing from your file. If a product isn't in the CSV, its current inventory is left exactly as-is. If you want a product to show zero stock, you need to include that row in the file with Quantity set to 0.
Header row rules
The header row is the top row in your CSV file that labels the contents of each column. There are specific rules and formatting each must follow to work properly. So, before we list the columns and their rules themselves, two header-row rules apply to every column in an Inventory Update file:
Column headers must be spelled exactly as shown below, with the exact capitalization.
Quantityworks.quantity,QUANTITY,QUANTity, andQtydo not.Unknown, misspelled, or incorrectly-cased headers are silently ignored. There is no error message - the column is just dropped, and any row that depended on that column won't update the way you expected.
This is the single biggest cause of "my import ran but nothing happened" issues.
Columns and what each cell must contain
For most single-location stores, your nightly inventory update file should look like this:
UPC | Quantity |
123456789012 | 4 |
987654321098 | 0 |
For multi-location stores, add Store:
UPC | Quantity | Store |
123456789012 | 4 | 0 |
987654321098 | 1 | 2 |
The table below lists every column the Inventory Update path reads, whether it is required, and the exact rules for what each cell may contain.
Column header | Required? | What goes in the cell |
| Required | The product's UPC barcode, as plain text. Typically 12 or 13 digits. If a UPC isn't already in Run Free, the whole row is silently skipped - no error message. |
| Required | A whole number (e.g. |
| Required if your account has more than one location, optional for single-location stores | The External Store Id from your Locations settings (typically a short code like |
| Recommended | The manufacturer's SKU. Plain text. Helps resolve ambiguity if the same UPC appears in multiple records. The core component that drives Run Free's auto product grouping function. |
| Recommended (required if your UPCs are not globally unique) | The size as it should display to the customer (e.g. |
| Required for product SKUs with width variants | The width code (e.g. |
Anything else in the file is ignored and could cause an import failure. The Inventory Update path is built to update quantities. It does not change product names, prices, descriptions, images, or categories - even if you include those columns. In some cases, the inclusion of additional information beyond the basic requirements outlined above can cause destruction of existing product data in Run Free. Do not blindly upload exports from your POS without reviewing this guide and verifying column and header requirements.
Remember, if you're updating product information, use Full Product Info for that.
Required-cell rules in plain English
A row without a
UPCvalue is skipped. The row has nothing for Run Free to match against.A row with a UPC we've never seen is skipped. Add the product through Full Product Info first.
A row with
Quantityleft blank, set to a decimal, or set to a non-number is skipped.A row missing
Storein a multi-location account may silently apply to the wrong location. Always include it for multi-location accounts.Header row must be the first row in the file. No blank rows, no notes, no merged cells above it.
File requirements
File must be a
.csvfile.The browser must report the file type as
text/csv. Files saved as.csvfrom standard spreadsheet tools (Google Sheets, LibreOffice Calc, Excel "Save As CSV") will meet this requirement automatically.Only one file can be queued at a time per store. If you try to upload a second file while one is still processing, you'll get an error: "There is a file already pending, you can only queue one update at a time."
The file must have at least one data row (a header row alone is not accepted).
On file size: The platform will prompt you to confirm if your file has more than 1,000 rows. Files are not blocked at that count, but files over roughly 3,000 rows have been known to stall partway through. If you have a large catalog, consider splitting your file and importing in batches. If a batch stalls, skip the rows that already processed and continue with the remainder.
How processing works
When you upload a file, it is saved to your store's processing folder and queued for the inventory processing service. The platform's UI will show a progress animation - this is cosmetic. The actual processing happens separately, typically within an hour depending on queue volume.
Because the file is processed row-by-row, a 100-row file results in approximately 100 separate inventory update operations.
Import Tool #2: The Full Product Info Mapper
Use this option when you're adding new products, updating product details (name, description, price, images, categories), or working from a spreadsheet export that uses different column names.
What it does
Full Product Info reads your CSV in the browser and presents a column-mapping interface. For each column in your file, you choose which Run Free field it maps to. This means your spreadsheet doesn't need to use our exact column names.
Auto-match works by case-insensitive comparison - if your file has a header upc it will auto-map to UPC. You can override any mapping manually.
Required columns: two different minimums
What counts as "required" depends on what you're trying to do:
To update inventory only on products that already exist:
UPC+Quantity(+Storeif multi-location).To create a new product that doesn't exist yet in Run Free:
Sku+Name(+Colorstrongly recommended). You can includeUPC,Quantity,Size,Width, etc. in the same row to seed the first inventory record at the same time.
If both Sku and Name are missing on a row that doesn't match an existing UPC, that row is silently skipped.
Columns and what each cell must contain
A basic Full Product Info file for adding new products might look like this:
Sku | UPC | Brand | Name | Color | Price | Quantity | Size | Width |
1103931-020 | 123456789012 | Brooks | Ghost 16 | Black/White | 140.00 | 3 | 10 | D |
1103931-020 | 123456789013 | Brooks | Ghost 16 | Black/White | 140.00 | 2 | 10.5 | D |
That example creates one product/colorway (Sku) with two sellable size records (UPC + Size).
The Full Product Info mapper lets you remap any spreadsheet column header to any of the Run Free fields below. So your spreadsheet can be titled STYLE or Item ID or anything else - what matters is what you map it to in the browser. The table below covers what each Run Free field expects in the cell once mapping is done.
Field | When it's required | What goes in the cell |
| Required to create a new product | The manufacturer SKU as plain text. Same SKU for all sizes/widths/UPCs that belong to the same colorway. Up to 100 characters. Internally normalized to alphanumeric-only. Required for Run Free's platform to auto-group and arrange your products for display. Click here to learn how. |
| Required to create a new product | Product name (e.g. |
| Required to match inventory rows on existing products | The UPC barcode as plain text, typically 12 or 13 digits. Up to 100 characters. |
| Required to write an inventory count | A whole number. Decimals like |
| Required for multi-location stores | The External Store Id from your Locations settings (e.g. |
| Optional (recommended on new products) | Brand name as plain text (e.g. |
| Optional (strongly recommended on new products) | The colorway name as you want it to display (e.g. |
| Optional | Long-form product description. No length limit through this path. Updates only when the cell is non-empty. |
| Optional | The selling price as a number or |
| Optional | Manufacturer's suggested retail price. Same |
| Optional | A single character: |
| Required to match inventory by size when | The size as it should display (e.g. |
| Required for shoe SKUs with width variants | The width code (e.g. |
| Optional | Run Free's internal product ID. Used as the primary match key when present. Use this only if you're working from a previous Run Free export that already includes it. |
| Optional | Your POS's product/item ID. Used as a fallback match key. Up to 100 characters. |
| Optional | A full image URL ( |
| Optional | Category name as plain text. Up to 100 characters each. Applied on creation. Updates to existing products only take effect if your account has category sync enabled. |
Per-cell length limits, summarized:
Size,Width,Store: up to 50 characters each.All other text fields: up to 100 characters each.
Descriptionand image URLs: no client-side cap.
Values over the limit are truncated to the limit, not rejected.
Required-cell rules in plain English
A row with no
Sku, noName, noUPC, and noRunFreeIdcannot be matched or created. It is silently skipped.A row that's trying to create a new product needs both
SkuandName. Missing one or the other = silent skip.A row with an empty
Quantitycell does not update inventory (but may still create the product and update its details).A row with a non-numeric
Quantity(decimals, text, commas in numbers) silently fails to update inventory.A row missing
Storeon a multi-location account silently applies to whichever location comes up first - usually not what you want.
A note on the "Update Matching Products Only" and "Meta Lookup" toggles
The import interface shows two toggles: "Update Matching Products Only" and "Meta Lookup Images/Description." In the current platform version, these toggles do not affect import behavior. The import processes all rows regardless of which option is selected.
Quantity behavior: decimals and negatives
Decimal quantities (e.g.
1.0,2.5) silently fail to update. The row appears to succeed but inventory is unchanged. Use whole numbers only.Negative quantities: Avoid negative quantities in your import file. See the support team for guidance if your data source produces negative numbers.
Export
The Export button downloads your full product catalog as a CSV file called Inventory.csv. It includes all products and inventory rows for your store. Deleted (archived) products are excluded.
Export columns
The export file uses these columns in this order:
RunFreeId, PosId, Sku, UPC, Brand, Name, Color, Price, Msrp, Markdown, Gender, Quantity, Size, Width, Store, Image1-Image6, Category1-Category6, Description
Things to know about the export format
The export includes a
Markdowncolumn that the import does not accept. If you export and re-import the file, theMarkdowncolumn will appear unmapped and won't cause errors - it's just ignored.Descriptionappears at the end of the export but maps correctly when re-imported (the import mapper is case-insensitive).There is no CSV quoting. If a product name, description, or other field contains a comma, the comma is stripped from the exported value. Round-tripping an export back through import is lossy if any fields contain commas.
Using the SKU Cleaner before your first import
If your POS export contains products without manufacturer SKUs, the Run Free support team can run your file through the SKU Cleaner service. Send a raw, complete CSV export of all products and fields including UPC codes from your POS to support (via the platform chat using the blue dot in the bottom right corner of this screen or by emailing support@runfreeproject.com) and we'll fill in missing SKUs by matching UPCs against our master database. Please don't edit the POS export or open it in Excel before sending it. The output will include a "Run Free SKU" column with the matched values. From there, you can rename that column to match your POS's SKU field and re-import into your POS so that every subsequent export and update to Run Free will include the manufacturer's SKU and ensure the Run Free platform can auto-grid your products to arrange them for your shoppers so you don't have to do it manually (Click here to learn how that works).
Important: Do not open the file in Microsoft Excel before or after this step. Excel will convert UPC codes and some SKU formats to scientific notation just by opening the file, without saving, and the data will be corrupted. Use Google Sheets or LibreOffice Calc instead.
The Store column
For single-location stores, the
Storecolumn is optional. If omitted, all inventory is applied to your one location automatically.For multi-location stores,
Storeis required on every row. The value must match the "External Store Id" shown in the Locations section of your admin panel (typically a short code or integer like1,2). IfStoreis missing from a multi-location import, the system will silently apply all inventory to whichever location comes up first - which is probably not what you want.
Most POS exports do not include a store column. You'll need to add one manually before importing.
Common mistakes checklist
Before you upload, run through this list, one-by-one. It applies to both import paths:
File is saved as
.csv(not.xlsxor.xls(or even.abcbbdfor you Boyz 2 Men fans)).Quantityvalues are whole numbers, no decimals, no commas, no text.UPCvalues are formatted as text (open in Google Sheets, not Excel, to verify).Multi-location stores:
Storecolumn is present and matches your External Store Ids.Header row is the first row in the file (no blank rows or notes above it).
A checklist to follow for the Inventory Update only:
Column headers match exactly, including capitalization (
Quantitynotquantity,UPCnotupc).No other CSV is already queued for your store.
Every UPC in the file is one that already exists in Run Free (unknown UPCs are silently skipped).
A checklist to follow for the Full Product Mapper only:
If you're creating new products, both
SkuandNameare present and mapped.If you're only updating inventory on existing products,
UPCandQuantityare mapped.You've stepped through the column-mapping screen and confirmed each Run Free field is mapped to the correct column from your file.