# Import Items via CSV

Save time by importing your product catalog in bulk using a CSV file. You can add new items or update existing ones with the overwrite option.

## Before You Import

{% hint style="danger" %}
**Create custom attributes before importing.** Any attribute columns in your CSV must already exist in Moselle, or the upload will fail silently. Create attributes by adding them to a product first. See [Custom Attributes](/operations/catalog/custom-attributes.md).
{% endhint %}

### Required Fields

Every row in your CSV must include:

| Field                 | Description               |
| --------------------- | ------------------------- |
| `sku` or `identifier` | Unique product identifier |
| `name`                | Product name              |

### Optional Standard Fields

| Field             | Description                         | Format               |
| ----------------- | ----------------------------------- | -------------------- |
| `description`     | Product description                 | Text                 |
| `unit_cost`       | Cost per unit                       | Number (e.g., 12.50) |
| `unit_price`      | Selling price per unit              | Number               |
| `product_line`    | Product line grouping               | Text                 |
| `product_type`    | Product category                    | Text                 |
| `item_type`       | core, component, bundle, or variant | Text                 |
| `archived`        | Whether item is archived            | true/false           |
| `launch_date`     | When the product launched           | Date (YYYY-MM-DD)    |
| `phase_out_date`  | When product is discontinued        | Date (YYYY-MM-DD)    |
| `comparable_skus` | Similar products for forecasting    | Comma-separated SKUs |
| `grade`           | Product grade/tier                  | Text                 |

## Step-by-Step Import Process

### 1. Download the Template

1. Go to **Catalog** from the dashboard
2. Select the **Products** tab
3. Click **Import** on the right side
4. Click **Generate a Sample CSV**

This downloads a template with your existing attribute columns, ensuring compatibility.

<figure><img src="/files/Ry05JayKESbGRFYSgiJe" alt=""><figcaption><p>Import button location in the catalog</p></figcaption></figure>

### 2. Prepare Your Data

1. Open the downloaded template
2. Add your items, one per row
3. Fill in required fields (SKU and Name)
4. Add optional fields and attribute values as needed
5. Save as CSV format

{% hint style="warning" %}
**Do not add new column headers** that aren't in the template or already defined as attributes. Unknown columns cause import failures.
{% endhint %}

### 3. Upload Your File

1. Return to **Catalog > Products > Import**
2. Drag and drop your CSV file, or click to browse
3. Click **Upload**
4. Review the confirmation showing how many items will import
5. Click **Import Products**

### 4. Verify Your Import

After import completes:

1. Refresh the catalog page
2. Check that new items appear
3. Spot-check a few items to verify attribute values

## Update Existing Items

To modify items that already exist in Moselle:

1. Check the **Overwrite Products with Matching SKUs** box before uploading
2. The system will update any item where the CSV SKU matches an existing item

{% hint style="warning" %}
**Overwrite replaces all attribute data.** If you only want to update specific fields, make sure your CSV includes values for ALL attributes on those items. Missing attribute columns will set those values to null/empty.
{% endhint %}

## Troubleshooting Import Issues

### Import Fails Silently

**Cause:** Your CSV includes attribute columns that don't exist in Moselle.

**Solution:**

1. Check each column header against existing attributes
2. Create any missing attributes on a single product first
3. Re-upload the CSV

### Items Not Appearing

**Cause:** Missing required fields (SKU or Name).

**Solution:** Ensure every row has both `sku` (or `identifier`) and `name` values.

### Attributes Show as Empty

**Cause:** Column header doesn't exactly match the attribute name.

**Solution:**

* Attribute names are case-sensitive
* Check for extra spaces in headers
* Spaces in attribute names become underscores (e.g., "Lead Time" → "lead\_time")

### Date Parsing Errors

**Cause:** Invalid date format.

**Solution:** Use YYYY-MM-DD format (e.g., 2024-06-15).

## Best Practices

1. **Always download a fresh template** before importing to get current attribute columns
2. **Create attributes first** by adding them to any single product
3. **Start with a small test file** (5-10 items) to verify your format
4. **Back up existing data** by exporting before overwriting
5. **Use consistent formatting** for attribute values (e.g., always "Cotton" not sometimes "cotton")


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.moselle.io/operations/catalog/import-your-items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.