> ## Documentation Index
> Fetch the complete documentation index at: https://docs.churningtracker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CSV imports

> Bulk migrate orders from your spreadsheet with reusable column mappings.

CSV import is the fastest way to get a year of spreadsheet history into Churning Tracker. Map your columns once, save the mapping, and reuse it for every future import. Learn how Churning Tracker compares to [manual spreadsheet tracking](https://churningtracker.com/#spreadsheet-comparison) on the product site.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/churningtracker/images/screenshots/csv-import-upload.png" alt="CSV import upload screen" />
</Frame>

## The 4-step workflow

Go to **Orders** → **Import** to start.

<Steps>
  <Step title="Upload">
    Drag in your CSV file. Churning Tracker auto-detects the header row and previews the first few rows.
  </Step>

  <Step title="Map columns">
    Match each column in your CSV to a Churning Tracker field. The system suggests mappings based on column names.

    Save the mapping with a name (e.g., "My old spreadsheet") to reuse on future imports.
  </Step>

  <Step title="Validate">
    Every row is checked for required fields, valid dates, and known retailers. Errors show inline so you can fix them in the CSV and re-upload.
  </Step>

  <Step title="Import">
    Confirm the row count and run the import. Orders and line items are created in batch.
  </Step>
</Steps>

## Field mappings

Below is the full list of fields you can map. Required fields must be present for the import to run.

### Order fields

| Field            | Required    | Notes                                                        |
| ---------------- | ----------- | ------------------------------------------------------------ |
| Order type       | Yes         | `buying_group`, `cashback`, or `gift_card`                   |
| Retailer         | Yes         | Matched by name; unknown retailers prompt you to create them |
| Order date       | Yes         | Most date formats supported (YYYY-MM-DD, MM/DD/YYYY, etc.)   |
| Order number     | Yes         | The store's order/confirmation number                        |
| Account owner    | Recommended | Matched by name; defaults to the importing user if blank     |
| Credit card      | Recommended | Matched by issuer + last 4                                   |
| Retailer account | Optional    | Matched by label under the retailer                          |
| Buying group     | Conditional | Required when order type is `buying_group`                   |
| Order status     | Optional    | Defaults to `pending`                                        |
| Notes            | Optional    | Free text                                                    |

### Line item fields

Repeat one row per line item, or use a single row per order with comma-separated lists.

| Field       | Required | Notes                         |
| ----------- | -------- | ----------------------------- |
| Description | Yes      | Product description           |
| Model / SKU | Optional | Useful for resale matching    |
| Quantity    | Yes      | Defaults to 1 if blank        |
| Unit price  | Yes      | Numeric, no `$` sign required |

### Order total fields

| Field            | Required | Notes                                    |
| ---------------- | -------- | ---------------------------------------- |
| Subtotal         | Auto     | Calculated from line items               |
| Shipping         | Optional | Numeric                                  |
| Taxes            | Optional | Numeric                                  |
| Discounts / fees | Optional | Negative values reduce the total         |
| Order total      | Optional | Used as a check against calculated total |

### Shipping & tracking

| Field           | Required | Notes                                   |
| --------------- | -------- | --------------------------------------- |
| Tracking number | Optional | Multiple numbers can be comma-separated |
| Carrier         | Optional | Auto-detected if blank                  |

## Saved mappings

Once a mapping is saved, the next import picks it automatically when the column headers match. You can also pick a saved mapping manually from the dropdown.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/churningtracker/images/screenshots/csv-import-mapping.png" alt="CSV column mapping screen with saved mappings dropdown" />
</Frame>

## Validation errors

Common issues you'll see in the validation step:

* **Unknown retailer** — fix the spelling or add the retailer first
* **Invalid date format** — reformat in your CSV
* **Missing required field** — fill in or map a different column
* **Duplicate order number** — Churning Tracker won't import an order with the same number twice for the same retailer

<Tip>
  Fix errors in your source CSV, not in the UI. That way you can re-import the corrected file cleanly if anything else needs to change.
</Tip>

## After import

* Orders appear in the **Orders** list immediately
* Shipment tracking starts on any tracking numbers included
* Payouts are **not** imported — see [CSV imports for payouts](#payouts-import) below or log them manually

## Other imports

Beyond orders, you can also import:

* **Credit cards** — from the **Credit cards** page
* **Point balances** — from **Points** → **Balances**
* **Account owners** — from the **Account owners** page

Each follows the same 4-step workflow with its own field set.