# Automotive Fitment CSV Cleaner for Shopify (`heihaha/automotive-fitment-shopify-mapper`) Actor

Turn messy, authorized auto-parts supplier CSV/JSON into draft Shopify product imports, structured Year-Make-Model fitment records and diagnostic error reports.

- **URL**: https://apify.com/heihaha/automotive-fitment-shopify-mapper.md
- **Developed by:** [heihaha heihaha](https://apify.com/heihaha) (community)
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.25 / catalog batch (100 items)

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Automotive Fitment CSV Cleaner for Shopify

**Shopify Year Make Model (YMM) CSV cleaner and automotive fitment data mapper.** Turn messy supplier CSV/JSON into Shopify draft-product imports, structured vehicle fitment records, and diagnostic reports. No scraping, proxies, supplier-account access, or store credentials required.

> Fits and supersessions are *supplier-supplied assertions*, NOT validated against OEM reference catalogs. Vehicle fitment CSV is vendor-neutral and is **not advertised as directly importable** into Globo, Searchanise, EasySearch, or other YMM plugins. Manufacturer and plugin-specific templates may require a separate mapping step.

### Try a free demo in 30 seconds

1. Open the Actor's Input tab.
2. Enable **Run FREE 50-SKU synthetic demo** and run.
3. Open **Output → Download all converted files (ZIP)**.
4. Inspect 5 exports: `shopify_products.csv`, `vehicle_fitments.csv`, `supersession_relations.csv`, `issues.csv`, `report.json`.
5. For your own **authorized** supplier file, disable Demo, upload a CSV/JSON, choose its shop currency, and run.

The 50-row demo is fabricated and deliberately includes dirty records. Do **not** publish demo part numbers or fitment assertions to a shop.

### What it cleans

- **Supplier column-name changes:** handles aliases such as `Item_Number`, `Part#`, `Manufacturer`, `Unit_Price`, and `YMM_Compatibility`. Specify a `field_mapping` JSON object when aliases don't match.
- **Vehicle ranges:** parses `MY18-22`, `2018-2022`, `15-20`, and semicolon-separated multiple fitments (`Make|Model|Years|Engine`).
- **SKU/price quality:** flags duplicates, unrecognized dates, empty SKU or title, cross-currency prices, supersession cycles and replacement targets missing from the batch.
- **Safety:** exports Shopify products as **draft/unpublished**, keeps images off by default, never performs currency conversion or contacts manufacturer portals.

### Five outputs

| File | What it contains |
|---|---|
| `shopify_products.csv` | Shopify product import with vendor, SKU, price, draft status |
| `vehicle_fitments.csv` | SKU ↔ Make/Model/Year-range/Engine associations marked UNVERIFIED |
| `supersession_relations.csv` | Original part → supplier-stated replacement relations |
| `issues.csv` | Invalid years, empty values, duplicate SKU, currency mismatches and other warnings |
| `report.json` | Mapping decisions, row counts and a quality summary |

The output ZIP is also available as a key-value store record named `RESULTS_ZIP`, with direct links in the Actor Output tab.

### Input examples

CSV (for demonstration only):

```csv
Item_Number,Manufacturer,Item_Description,Unit_Price,Money_Ccy,YMM_Compatibility
TEST-001,Land Rover,Demo Brake Pads,99.00,USD,Land Rover|Demo Model|MY18-22|V6
```

Nested JSON:

```json
[
  {
    "sku": "TEST-001",
    "brand": "Land Rover",
    "part_name": "Demo Brake Pads",
    "price": 99,
    "currency": "USD",
    "fitment": [{"make": "Land Rover", "model": "Demo Model", "years": "MY18-22"}]
  }
]
```

Optional source column override: `{"sku":"Item_Number","fitment":"YMM_Compatibility"}`.

### Pricing transparency

This Actor uses **pay per event** pricing: the `catalog-batch-100` custom event costs **$0.25 per 100 source rows**, rounded up. For example, 1–100 input rows = $0.25; 101–200 rows = $0.50; 1,000 rows = $2.50. These are custom processing charges; always check the live price breakdown before running. The entirely synthetic 50-row demo emits no custom processing event. Invalid or duplicate source rows still count toward batch size.

Apify may also charge for platform usage or other automatically enabled events depending on the actual listing setup. Always check the price breakdown and max charge on the Actor page before running. Failed/missing rows still count toward input-size batches, but the quality report explains exclusions.

### Limits and important compatibility notes

- Max 3 MB uploaded file; 10,000 source rows; 50 fitments per SKU. UTF-8 CSV / JSON only.
- No ACES 5.0/PIES 8.0 XML parser, no licensed VCdb/TecDoc part fitment database, no VIN validation.
- Shopify product-level metafields may be imported through supported CSV headers; **variant-level metafields cannot** be imported using the product CSV.
- Import formats vary between YMM apps and often require a Shopify **Product ID** allocated after product import; SKU is not a Shopify Product ID. Vendor-neutral `vehicle_fitments.csv` is provided for a later approved adapter, not as a finished Globo/Shopify Searchanise import.
- Input files and results live in your Apify run's storage subject to its retention/privacy and permissions. This Actor does not send input to third-party services.
- The tool is a **pre-import cleaning and mapping product**, not an OEM compatibility certification or a guarantee of successful Shopify/plugin import. Test on a draft/sandbox store first.

### Who can use it

Shopify auto-parts merchants, catalog import consultants, B2B suppliers and operations teams preparing their first Shopify product import. No proxy or anti-bot configuration needed.

Documentation:

- [Shopify official product CSV fields](https://help.shopify.com/en/manual/products/import-export/using-csv)
- [Auto Care Data Standards](https://www.autocare.org/data-standards)
- [Apify pricing and costs](https://docs.apify.com/actors/publishing/monetize/pricing-and-costs)

### Before choosing a YMM app

Use this tool to clean an auto-parts catalog before a Shopify import. The product CSV and the vehicle fitment CSV are separate exports. EasySearch, Convermax, and other Year Make Model search apps have their own import requirements; a separate mapping step may be needed. This Actor does not provide a ready-made importer for those apps.

For eBay Motors, SEMA, or ACES/PIES source feeds, first export the relevant fields to supported CSV/JSON. This Actor does not parse ACES/PIES XML or validate fitment against a licensed vehicle database.

### Need a larger migration?

Have 50,000+ SKUs, custom supplier feeds, or complex ACES/PIES files? Contact **heihaha001@gmail.com** for custom data cleaning, feed normalization, or a full Shopify catalog migration. This Actor is a pre-import cleaner; it does not certify OEM compatibility or replace licensed ACES/PIES data services.

# Actor input Schema

## `file_url` (type: `string`):

Upload authorized supplier CSV/JSON into an Apify key-value store. Only Apify KVS record URLs are accepted. The file is never sent to third-party supplier sites.

## `csv_text` (type: `string`):

Advanced input: paste CSV text instead of uploading a file. For example, Item_Number,Manufacturer,Item_Description,Unit_Price,Money_Ccy,YMM_Compatibility. Leave blank when uploading a file.

## `records` (type: `array`):

Alternative to CSV. Array of objects; nested fitment arrays supported.

## `field_mapping` (type: `object`):

Canonical key to supplier CSV column, e.g. {"sku":"Item_Number","fitment":"YMM_Compatibility"}.

## `target_currency` (type: `string`):

Rows with mismatched currencies are excluded; no FX conversion.

## `allow_image_urls` (type: `boolean`):

Disabled by default. URLs are not fetched or verified for rights.

## `demo_only` (type: `boolean`):

Run the included fabricated sample with no paid processing event. Uncheck to convert your own uploaded data. Supplier fitments are not verified OEM data.

## `make_aliases` (type: `object`):

Explicit, user-controlled brand name normalization. Example: {"Merc-Benz":"Mercedes-Benz"}. Not an authoritative compatibility check.

## Actor input object example

```json
{
  "field_mapping": {},
  "target_currency": "USD",
  "allow_image_urls": false,
  "demo_only": false,
  "make_aliases": {}
}
```

# Actor output Schema

## `downloadZip` (type: `string`):

Five files containing Shopify draft import, YMM relations and validation report.

## `shopifyCsv` (type: `string`):

No description

## `fitmentsCsv` (type: `string`):

No description

## `issuesCsv` (type: `string`):

No description

## `conversionSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("heihaha/automotive-fitment-shopify-mapper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("heihaha/automotive-fitment-shopify-mapper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call heihaha/automotive-fitment-shopify-mapper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,heihaha/automotive-fitment-shopify-mapper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WCnFIn5MFdQq065Ra/builds/mhdWh0Ee9EBrEzHjj/openapi.json