---
title: Import products
description: Use Runner's CSV template to start a catalog import and follow its processing history.
---

Import products from a prepared CSV when entering the same structured catalog information one product at a time would be inefficient.

## Why and when to use import

Use Import when you already have product data in a spreadsheet or another system and can map it to Runner's CSV template. Use the manual [Products](./products) form for a small catalog or when you need to learn the fields first.

## Availability and prerequisites

- Open **Store Operations → Products** in a ready store.
- Complete the store publish/readiness setup that creates its live storefront catalog channel; the import task cannot continue without that channel.
- The populated desktop product list shows **Import**. In an empty catalog, first use **Add First Product**; the mobile view emphasizes manual creation.
- Import accepts CSV files only.
- Use Runner's current Template. Required columns are `handle` and `title`; variant rows must include the required `sku` and option values shown by the template.
- Starting an import changes the store catalog. Review the file before submitting it.

## Open Import Products

**Entry path:** **Workspace → choose a store → Store Operations → Products → Import**

![Import Products dialog](https://ixft9x6szo.ufs.sh/f/Cc8uxBgAYTzgObeFKMJCcW62zHrU8smjSnqvixd1twlAf4uK)

## Main controls

| Control | Why you use it | What happens when selected |
| --- | --- | --- |
| **Import** | Open the bulk-import workflow | Opens the Import Products dialog without starting a task. |
| **Template** | Start from Runner's expected columns | Downloads the current `product-import-template.csv` file. |
| **History** | Check earlier import tasks | Switches to a list of import files and their latest states. |
| Upload area | Choose the prepared CSV | Reads the file locally and shows it as ready when content is available. |
| Remove-file control | Correct a wrong selection | Clears the selected file so you can choose another. |
| **Start Import** | Submit the selected CSV | Starts an import task, then moves to History when Runner accepts it. |
| **Cancel** | Leave without submitting | Closes the dialog and clears the selected file. |
| **Refresh** in History | Request the latest task state | Reloads the visible import history. |
| **Back to Import** | Prepare another file | Returns from History to the upload view. |
| **Close** | Leave History | Closes the dialog without changing the task already submitted. |

## Prepare and submit a CSV

1. Select **Import**, then **Template**.
2. Open the downloaded CSV in a spreadsheet editor that preserves CSV formatting.
3. Keep the template headers. Complete `handle` and `title` for products, plus the shown `sku` and option values for variants.
4. Review product handles, titles, prices, variants, and any repeated rows before exporting as CSV.
5. Return to the dialog and choose or drag the CSV into the upload area.
6. Wait until the file shows **Ready to import**.
7. Select **Start Import** once.
8. In **History**, follow the submitted file until it reaches a terminal state, then refresh the Products list and inspect the resulting rows.

## Understand History states

| State | Meaning | What to do |
| --- | --- | --- |
| **Pending** | The task is waiting to start | Leave it in place and check again later; do not immediately submit a duplicate. |
| **Processing** | Runner is working through the file | Keep the dialog open or return to History later. |
| **Completed** | Runner finished handing the file to the catalog importer | Product processing can continue after this state. Refresh Products and inspect names, variants, prices, status, and inventory. |
| **Failed** | Runner could not finish the import task | The current History card records the failed state but not a detailed cause. Check the prerequisites and source CSV before submitting a new file. |
| **Cancelled** | The task did not continue | Confirm whether any products were created before deciding what to submit next. |

History can also show the file size, total rows, and a transaction ID when Runner has those values. These details identify the task; they do not replace checking the product records.

## Limits and troubleshooting

- **Start Import is disabled:** Select a `.csv` file and wait for Runner to finish reading non-empty content.
- **Invalid File Type:** Export the spreadsheet as CSV; renaming another file format does not convert it.
- **File Read Error:** Re-export the CSV, confirm it opens normally on your device, and choose it again.
- **Import Failed:** Confirm the store publish/readiness setup created the live storefront catalog channel, then use the provided template, restore required columns, and check variant `sku` and option values.
- **The task looks stuck:** Open History and select **Refresh**. Pending and Processing are not proof of completion.
- **Unexpected product rows appear:** Do not repeat the same import blindly. Compare the CSV handles with the Products list and correct records deliberately.

## Related guides

- [Products](./products)
- [Inventory and variants](./inventory-and-variants)
- [Onboarding and General settings](./onboarding-and-general-settings)
- [Store Operations overview](./)