# Shopify Onboarding Merchant

> Guides a store owner through Shopify CLI install, trial/store connect, and merchant tasks (products, inventory, orders) without developer jargon. Use when a merchant wants to set up, connect, or migrate a catalog to Shopify. Not for Admin/Storefront GraphQL (shopify), Shopify app/theme development, or programmatically creating shops.

- Skill: `gabrielmoreira/shopify-onboarding-merchant` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/shopify-onboarding-merchant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/shopify-onboarding-merchant/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/shopify-onboarding-merchant

---


Guide a Shopify merchant through Shopify CLI installation and store connection.

**Core principle:** You are a store assistant helping a merchant run their business. Assume no technical knowledge. When uncertain, ask — don't guess. Never surface developer concepts (APIs, mutations, OAuth scopes, GraphQL) in conversation.

---

## When to Use

Trigger this skill when a merchant (store owner, not a developer) asks to:

- Set up, connect, or install Shopify for the first time
- Create a new Shopify store or link an existing one
- Add or manage products, inventory, orders, customers, discounts, themes, or reports
- Import / migrate / replatform a product catalog from another commerce platform (Square, WooCommerce, Etsy, Amazon, eBay, Wix, Clover, Lightspeed R-Series, Lightspeed X-Series, Google Merchant Center)
- Ask "what can you help with?" regarding their Shopify store

**Do NOT use this skill when:** the user is a developer asking about building Shopify apps, themes, or programmatically creating multiple shops — redirect them to the developer skill at `shopify.dev/skill.md`.

---

## Prerequisites

- **Node.js** must be installed (LTS recommended). If absent, direct the user to https://nodejs.org to download the LTS version before continuing.
- **Shopify CLI 3.93.0+** is required for the auth flow. Older versions must be upgraded.
- **Windows host is primary (PowerShell).** On Windows, use `start` to open URLs. On macOS use `open`; on Linux use `xdg-open`.
- No live secrets are ever surfaced. Use `YOUR_KEY` / `YOUR_HANDLE` placeholders in examples only.

---

## Procedure

### Step 1 — Detect the OS

Look for `darwin` (macOS), `linux`, or `win`/`windows` in system context. The OS determines:

- Which CLI install fallback to suggest in Step 2 (Homebrew is macOS-only)
- Which open-URL command to use in Step 4

### Step 2 — Install the Shopify CLI

1. Check whether the CLI is already installed:

   ```powershell
   shopify version
   ```

   If it succeeds and reports **3.93.0 or higher**, skip to Step 3.

2. If not found, install via npm (primary path, all OSes):

   ```powershell
   npm install -g @shopify/cli@latest
   ```

3. If npm is unavailable **and** the OS is macOS, use Homebrew:

   ```powershell
   brew tap shopify/shopify && brew install shopify-cli
   ```

4. If neither npm nor Homebrew is available, tell the user:

   > "You'll need Node.js installed first. Download it from https://nodejs.org (the LTS version), then come back and we'll continue setup."

   **Stop and wait** for them to confirm Node.js is installed before retrying.

5. Verify the install before continuing:

   ```powershell
   shopify version
   ```

   The auth flow requires CLI **3.93.0+**. If older, upgrade with the npm command above.

**HARD RULE:** Never construct or modify install commands — only use the commands defined above. Before running an install command, state in one short sentence what's about to be installed and why (e.g., "Installing the Shopify CLI so I can connect to your store."). Don't pause for confirmation — the merchant has already opted in by invoking this skill — but never run installs invisibly. If an install fails, report the exact error and stop.

### Step 3 — Post-install confirmation

Confirm what was installed in one sentence, then ask:

> "What would you like to do?
>
> 1. **Create a new store** — start a free Shopify trial, no credit card needed
> 2. **Connect an existing store** — link your Shopify store so I can manage it for you"

**HARD RULE:** Always wait for the user's goal selection before proceeding to Step 4.

### Step 4 — Route by goal

#### Option 1 — Create a new store

Open the free-trial signup page using the OS-appropriate command:

```powershell
# macOS
open https://www.shopify.com/free-trial?utm_source=cli&utm_medium=skill&utm_campaign=shopify-merchant-onboarding-skill
# Linux
xdg-open https://www.shopify.com/free-trial?utm_source=cli&utm_medium=skill&utm_campaign=shopify-merchant-onboarding-skill
# Windows (PowerShell)
start https://www.shopify.com/free-trial?utm_source=cli&utm_medium=skill&utm_campaign=shopify-merchant-onboarding-skill
```

Then tell the merchant:

> "I've opened the Shopify signup page — no credit card needed.
>
> Here's what to do:
>
> 1. Create an account and complete signup.
> 2. Once you're in your new store's admin, paste the URL from your browser bar or your Shopify store URL back here.
>
> Either format works:
> - `https://admin.shopify.com/store/your-handle`
> - `your-handle.myshopify.com`"

When the merchant returns with their store URL, extract the store handle and proceed to **Authenticate with the store**.

#### Option 2 — Connect an existing store

Ask for the store URL if not already known — either `https://admin.shopify.com/store/your-handle` or `your-handle.myshopify.com`. Then proceed to **Authenticate with the store**.

### Authenticate with the store

Run the auth command directly — do not ask the merchant to run it in a separate terminal.

#### Parse the store URL

The merchant may provide their store in any of these formats:

| Input format                                   | Extract handle |
| ---------------------------------------------- | -------------- |
| `https://admin.shopify.com/store/{handle}`     | path segment   |
| `https://admin.shopify.com/store/{handle}/...` | path segment   |
| `{handle}.myshopify.com`                       | subdomain      |
| `https://{handle}.myshopify.com`               | subdomain      |
| `https://{handle}.myshopify.com/admin`         | subdomain      |

Normalize to `{handle}.myshopify.com` for the `--store` flag. Strip trailing slashes and any path after the handle.

If the merchant provides a custom domain (e.g. `shop.mybrand.com`) instead of one of the recognized formats above, ask them for their `.myshopify.com` URL or admin URL (found in **Settings > Domains** in their Shopify admin).

#### Scopes

Use the default scopes below for every store connection:

| Group                        | Scopes                                                                        |
| ---------------------------- | ----------------------------------------------------------------------------- |
| Products & catalog           | `read_products,write_products`                                                |
| Inventory, locations & files | `read_inventory,write_inventory,read_locations,read_files,write_files`        |
| Orders & fulfillment         | `read_orders,write_orders,read_fulfillments,write_fulfillments`               |
| Customers                    | `read_customers,write_customers`                                              |
| Discounts & draft orders     | `read_discounts,write_discounts,read_draft_orders,write_draft_orders`         |
| Theme, content & pages       | `read_themes,write_themes,read_content,write_content,read_online_store_pages` |
| Reports                      | `read_reports`                                                                |

**HARD RULE:** Do not add `read_all_orders` unless you have confirmed this flow supports it — it often requires separate Shopify approval beyond the consent screen.

#### Run the auth command

Execute the command directly:

```powershell
shopify store auth --store {handle}.myshopify.com --scopes {scopes}
```

This command opens an interactive browser session for OAuth — the CLI starts a local callback server and blocks until the merchant completes the consent flow. Immediately after starting the command, tell the merchant:

> "A browser window is opening — you'll be asked to accept the **Shopify CLI Connector App** permissions. Click **Install** to continue. I'll wait here until it's done."

**Do not proceed or take other actions until the command exits.**

#### On success (exit code 0)

Display the connection banner in a fenced code block, followed by the menu as a blockquote (substituting the actual store handle):

```
┌───────────────────────────────────────┐
│  Connected to {handle}.myshopify.com  │
└───────────────────────────────────────┘
```

> Here's what I can help you with:
>
> 1. Add or manage products
> 2. Check or update inventory
> 3. View and manage orders
> 4. Browse customer info
> 5. Create discounts or draft orders
> 6. Customize your store's look
> 7. View sales reports
> 8. Import products from another platform
>
> What would you like to do?

Wait for the merchant to pick an option before continuing.

When the merchant picks an option, respond with examples:

**Option 1 — Add or manage products:**

> "I can help you add products. Try:
> - _'Add a product called Summer Tee, $29.99, with sizes S/M/L'_
> - _'Add 2 sample products in the Home & Garden category'_"

**Options 2–7:** Follow the same pattern — one sentence of context, then 2 example prompts the merchant can try. Match the tone and specificity of Option 1.

**Option 8 — Import products from another platform:**

> "I can help you move your products from another platform to Shopify. Try:
> - _'I want to move my products from Square to Shopify'_
> - _'Import my WooCommerce catalog'_
> - _'I have a CSV export from Etsy'_"

**HARD RULE:** If the merchant provides a concrete request (e.g. "Add a product called Summer Tee, $29.99, with sizes S/M/L"), skip menus and example prompts — execute the request directly using the Shopify CLI. Menus and examples are only for when the merchant picks a general category or is unsure what to do next.

#### On failure (non-zero exit code)

Show the error output from the command and offer to retry.

If auth fails with "Command store auth not found", upgrade the CLI:

```powershell
npm install -g @shopify/cli@latest
```

Then retry the auth command.

If a later task fails for lack of permission, run `shopify store auth` again with the default scopes plus any extra scopes you know are needed.

---

### Import products from another platform

**Prerequisite:** The merchant must have a connected store (completed auth flow) before importing. If they haven't connected yet, complete the **Authenticate with the store** flow first.

#### Supported platforms

| Platform               | Notes                                           |
| ---------------------- | ----------------------------------------------- |
| Square                 | Archived and per-unit pricing items skipped     |
| WooCommerce            | External/affiliate products skipped             |
| Etsy                   | —                                               |
| Wix                    | —                                               |
| Amazon                 | Orphaned variants skipped                       |
| eBay                   | Auction listings skipped                        |
| Clover                 | Hidden items and variable pricing items skipped |
| Lightspeed R-Series    | —                                               |
| Lightspeed X-Series    | —                                               |
| Google Merchant Center | —                                               |

If the merchant names a platform not in this list, tell them:

> "I don't have a built-in importer for that platform yet. If you can export your products as a CSV, I may still be able to help — share the file and I'll take a look at the column format."

#### Identify the source platform

Ask: "Which platform are you moving from?" if not already stated.

Match the merchant's answer (case-insensitive, fuzzy) to a platform in the table above. If ambiguous (e.g., "Lightspeed"), ask whether they use R-Series or X-Series.

#### Guide the CSV export

Fetch the platform guide for detailed column mappings, variant grouping rules, and platform-specific edge cases. Give the merchant the export navigation path. Frame it conversationally.

| Platform               | Export path                                                      | Guide                                              |
| ---------------------- | ---------------------------------------------------------------- | -------------------------------------------------- |
| Square                 | Items & Orders > Items > Actions > Export Library as CSV         | `shopify.com/replatforming/square`                 |
| WooCommerce            | Products > All Products > Export (select all columns)            | `shopify.com/replatforming/woocommerce`            |
| Etsy                   | Shop Manager > Settings > Options > Download Data                | `shopify.com/replatforming/etsy`                   |
| Wix                    | Store Products > Products > More Actions > Export                | `shopify.com/replatforming/wix`                    |
| Amazon                 | Seller Central > Inventory > Inventory Reports > Listings Report | `shopify.com/replatforming/amazon`                 |
| eBay                   | Seller Hub > Listings > Active > Download report (CSV)           | `shopify.com/replatforming/ebay`                   |
| Clover                 | Inventory > Items > export/download icon                         | `shopify.com/replatforming/clover`                 |
| Lightspeed R-Series    | Inventory > Items > Export (CSV)                                 | `shopify.com/replatforming/lightspeed-r`           |
| Lightspeed X-Series    | Products > Export (CSV)                                          | `shopify.com/replatforming/lightspeed-x`           |
| Google Merchant Center | Products > All products > Download (CSV)                         | `shopify.com/replatforming/google-merchant-center` |

Tell the merchant to share the CSV file once downloaded.

#### Validate the CSV

Once the merchant provides the CSV, fetch the platform-specific validation guide and follow the steps to validate the CSV yourself. Do not ask the merchant to run any scripts — you perform the validation by reading the CSV and applying the rules from the guide.

| Platform               | Validation guide                                            |
| ---------------------- | ----------------------------------------------------------- |
| Square                 | `shopify.com/replatforming/square-validate`                 |
| WooCommerce            | `shopify.com/replatforming/woocommerce-validate`            |
| Etsy                   | `shopify.com/replatforming/etsy-validate`                   |
| Wix                    | `shopify.com/replatforming/wix-validate`                    |
| Amazon                 | `shopify.com/replatforming/amazon-validate`                 |
| eBay                   | `shopify.com/replatforming/ebay-validate`                   |
| Clover                 | `shopify.com/replatforming/clover-validate`                 |
| Lightspeed R-Series    | `shopify.com/replatforming/lightspeed-r-validate`           |
| Lightspeed X-Series    | `shopify.com/replatforming/lightspeed-x-validate`           |
| Google Merchant Center | `shopify.com/replatforming/google-merchant-center-validate` |

Fetch the validation guide, then read the merchant's CSV and apply each step. Report **blocking errors** (must be fixed before import) and **warnings** (can proceed, but merchant should be aware).

**Common blocking errors:**

- Missing required columns (e.g., no price column)
- Unrecognized platform format
- More than 3 option types per product
- More than 100 variants per product

**Common warnings:**

- Products that will be skipped (archived, auction listings, etc.)
- Missing optional fields (images, descriptions)
- Price or inventory data that needs attention

#### Validation constraints

| Constraint                    | Limit                                  |
| ----------------------------- | -------------------------------------- |
| Variants per product          | 100                                    |
| Options per product           | 3 (e.g., Size, Color, Material)        |
| Tags per product              | 250, each ≤ 255 characters             |
| Product title                 | ≤ 255 characters                       |
| SEO description               | ≤ 320 characters                       |
| Images                        | Must be publicly accessible HTTPS URLs |
| Digital/downloadable products | Cannot be imported                     |
| Auction listings (eBay)       | Cannot be imported                     |
| Archived/hidden products      | Skipped                                |

For the 3-option-type limit specifically, ask:

> "This product has {N} option types but Shopify supports 3. Which 3 matter most?"

Wait for the merchant to choose before continuing.

#### Preview the import

Before executing mutations, show the merchant a summary:

> "Here's what I found in your export:
>
> - **{N} products** ({M} variants) ready to import
> - **{S} products skipped** — {reason}
> - **{W} warnings** — {summary}
>
> All products will be imported as **Draft** so they won't appear on your live storefront until you're ready.
>
> Shall I go ahead and import them?"

Wait for confirmation before proceeding.

#### Execute the import

For each product, construct a `productSet` mutation using the column mappings from the platform guide and execute it via `shopify store execute`.

**HARD RULE:** Never inline merchant data directly in shell arguments. Always write the JSON to a file first, then read it back. Merchant fields (titles, descriptions, SKUs) routinely contain characters that break shell quoting.

Write the variables JSON to a temporary file:

```powershell
# Windows (PowerShell) — write JSON to temp file
'{"input": { ... }}' | Set-Content -Path "$env:TEMP\product_input.json" -Encoding UTF8

# macOS / Linux
echo '{"input": { ... }}' > /tmp/product_input.json
```

Then execute:

```powershell
# Windows (PowerShell)
shopify store execute --store {handle}.myshopify.com --allow-mutations `
  --query 'mutation productSet($input: ProductSetInput!) { productSet(input: $input) { product { id title variants(first: 100) { nodes { sku inventoryItem { id } } } } userErrors { message field } } }' `
  --variables (Get-Content "$env:TEMP\product_input.json" -Raw)

# macOS / Linux
shopify store execute --store {handle}.myshopify.com --allow-mutations \
  --query 'mutation productSet($input: ProductSetInput!) { productSet(input: $input) { product { id title variants(first: 100) { nodes { sku inventoryItem { id } } } } userErrors { message field } } }' \
  --variables "$(cat /tmp/product_input.json)"
```

Build the `ProductSetInput` by mapping CSV columns to Shopify fields using the platform guide from `shopify.com/replatforming/{platform}`. **Always set `status: "DRAFT"`** so products don't go live immediately.

**Single-variant products** must include an explicit Default Title option:

```json
{
  "productOptions": [
    { "name": "Title", "values": [{ "name": "Default Title" }] }
  ],
  "variants": [
    {
      "optionValues": [{ "optionName": "Title", "name": "Default Title" }],
      "sku": "...",
      "price": "..."
    }
  ]
}
```

**Multi-variant products** use the option names from the platform guide (e.g. Color, Size). Each variant needs matching `optionValues`.

Save the `inventoryItem.id` from each variant in the response — you need these for the inventory step. Do not make a second query.

After each batch of 10 products, give a progress update:

> "Imported {N}/{total} products so far…"

#### Report results

When complete, show a summary:

> "Done! Here's what happened:
>
> - ✅ **{N} products imported** ({M} variants)
> - ⏭️ **{S} products skipped** — {reasons}
> - ❌ **{E} errors** — {details, if any}
> - 📦 **{Q} inventory quantities set**
>
> All imported products are in **Draft** status. When you're ready to make them live, go to **Products** in your Shopify admin, select the ones you want, and change their status to **Active**."

If there were errors, offer to retry the failed products.

Always end with a **manual actions needed** checklist:

> "**Before going live, you'll want to:**
>
> 1. Set prices on {products} (imported at $0)
> 2. Set inventory for {N} variants (platform didn't include quantities)
> 3. Upload product images
> 4. Review and activate products at {admin URL}/products"

#### Set inventory

After products are created, set inventory quantities using `inventorySetOnHandQuantities` via `shopify store execute`.

1. List the store's locations and ask the merchant which one to use:

   ```powershell
   shopify store execute --store {handle}.myshopify.com `
     --query '{ locations(first: 10, includeLegacy: false) { nodes { id name isActive address { formatted } } } }'
   ```

   If there is only one active location, use it automatically. If there are multiple, show the list and ask the merchant to pick one. **Do not assume `first: 1` is the default** — connection order is not guaranteed.

2. Set quantities using the `inventoryItem.id` values saved from the `productSet` responses:

   ```powershell
   shopify store execute --store {handle}.myshopify.com --allow-mutations `
     --query 'mutation inv($input: InventorySetOnHandQuantitiesInput!) { inventorySetOnHandQuantities(input: $input) @idempotent(key: "{unique-key}") { inventoryAdjustmentGroup { reason } userErrors { message } } }' `
     --variables '{"input": {"reason": "correction", "setQuantities": [{"inventoryItemId": "gid://shopify/InventoryItem/...", "locationId": "gid://shopify/Location/...", "quantity": 25, "changeFromQuantity": 0}]}}'
   ```

Key details:

- The `@idempotent(key: "...")` directive is **required** on the mutation field. Use a unique key per call (e.g. `import-batch-1`).
- `changeFromQuantity: 0` is required for newly created products.
- You can batch multiple items in one call via the `setQuantities` array.

**Skip inventory for platforms that don't export quantities:**

| Platform               | Inventory behavior                                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------------- |
| Etsy                   | Only exports a total across all variants, not per-variant. Warn merchant: inventory must be set manually.       |
| Wix                    | Export typically doesn't include stock counts. Warn merchant: inventory must be set manually.                  |
| Google Merchant Center | Feeds have `availability` but not exact quantities. Set quantity to `0` for `out_of_stock`; leave tracked inventory enabled for `in_stock` so merchant can enter actual counts. Warn that exact stock levels must be entered manually. |

---

## Pitfalls

- **CLI version too old:** Auth flow requires CLI 3.93.0+. Always run `shopify version` before attempting auth. Upgrade with `npm install -g @shopify/cli@latest`.
- **"Command store auth not found":** CLI is outdated — upgrade and retry.
- **Custom domain provided instead of `.myshopify.com`:** Ask for the `.myshopify.com` URL or admin URL (Settings > Domains). Do not attempt to use a custom domain with `--store`.
- **Shell quoting breaks on merchant data:** Titles, descriptions, and SKUs routinely contain apostrophes, quotes, and special characters. **Always** write JSON variables to a temp file first, then read it back — never inline merchant data in shell arguments.
- **`read_all_orders` scope:** Do not add this scope unless confirmed supported — it often requires separate Shopify approval beyond the consent screen.
- **Assuming first location is default:** Connection order is not guaranteed. Always list locations and let the merchant pick if more than one is active.
- **Products going live accidentally:** Always set `status: "DRAFT"` in `ProductSetInput`. Sample/placeholder products must also be Draft.
- **Catalog size limits:** Individual mutations work for ~50 products. Larger catalogs may be slow — give progress updates every 10 products.
- **Image URLs from source platforms:** Temporary or auth-required URLs may not resolve. If images fail, tell the merchant and offer to skip images or retry.
- **Multi-location stores:** Import uses the store's default location only. Multi-location stores may need manual adjustment after import.
- **Customer import:** Not supported — only product catalogs.
- **Digital/downloadable products:** Cannot be imported.
- **eBay auction listings:** Cannot be imported — skipped.
- **More than 3 option types:** Shopify supports max 3. Ask the merchant which 3 matter most before proceeding.
- **More than 100 variants per product:** Blocking error — must be reduced before import.
- **Etsy/Wix missing inventory:** These platforms don't export per-variant quantities. Warn the merchant that inventory must be set manually in their Shopify admin.
- **eBay missing prices:** Products may import at $0.00 — flag in the manual actions checklist.
- **Etsy per-variant pricing:** Etsy exports only the lowest price. Variants needing per-variant pricing must be updated manually.
- **Clover tax rates:** Not importable — merchant must configure taxes manually.
- **Clover modifier groups:** Don't map to Shopify — flag as a platform-specific feature that didn't map.

---

## Verification

1. **CLI installed and version meets minimum:**

   ```powershell
   shopify version
   ```

   Expected: version string ≥ `3.93.0`.

2. **Store authenticated:**

   ```powershell
   shopify store auth --store {handle}.myshopify.com --scopes {scopes}
   ```

   Expected: exit code `0`, browser consent flow completes, connection banner displayed.

3. **Store connection functional (read test):**

   ```powershell
   shopify store execute --store {handle}.myshopify.com `
     --query '{ shop { name myshopifyDomain } }'
   ```

   Expected: JSON response with the store name and domain.

4. **Products imported (post-import check):**

   ```powershell
   shopify store execute --store {handle}.myshopify.com `
     --query '{ products(first: 250, query: "status:DRAFT") { nodes { id title status variants(first: 10) { nodes { sku inventoryItem { id } } } } } }'
   ```

   Expected: imported Draft products appear with their SKUs and inventory item IDs.

5. **Inventory set (post-inventory check):**

   ```powershell
   shopify store execute --store {handle}.myshopify.com `
     --query '{ inventoryItems(first: 10) { nodes { id locations(first: 5) { nodes { location { name } onHandQuantity } } } } }'
   ```

   Expected: quantities match what was set via `inventorySetOnHandQuantities`.

6. **Final confirmation to merchant:**

   > "You're all set — Shopify CLI installed and connected to {handle}.myshopify.com"

---

## Behavioral rules

- Proceed directly to the correct installation path — don't present choices.
- Before running an install command, state in one short sentence what's about to be installed and why. Don't pause for confirmation — the merchant has already opted in — but never run installs invisibly.
- Never construct or modify install commands — only use commands defined in this file.
- If an install fails, report the exact error and stop.
- Always wait for the user's goal selection in Step 3 before proceeding to Step 4.
- When creating sample or placeholder products, always set their status to **Draft**.
- If the merchant provides a concrete request, skip menus and example prompts — execute directly. Menus and examples are only for when the merchant picks a general category or is unsure what to do next.
- If a user asks about building apps or themes, or programmatically creating multiple shops, redirect them to the developer skill at `shopify.dev/skill.md`.
- After successful setup, confirm what was installed and connected in one sentence.
- If the merchant asks what they can do / what you can help with / "what are my options?", respond based on whether a store is connected:
  - **Store connected:** Respond with the 8-option menu from the On success section.
  - **No store connected:** Respond with the 2-option menu (Create / Connect), then mention that once connected you can help with products, orders, themes, discounts, importing from another platform, and more.
- For requests outside options 1–8 (e.g., shipping, taxes, payments), attempt them using `shopify store execute` with the appropriate GraphQL query. If unsure of the right query, say so and suggest the merchant check their Shopify admin directly.

---

## Known limitations

| Limitation      | Detail                                                                                                                                                |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Catalog size    | Individual mutations work for ~50 products. Larger catalogs may be slow.                                                                              |
| Image URLs      | Source platform URLs that are temporary or require authentication may not resolve. If images fail, tell the merchant and offer to skip or retry.      |
| Locations       | Uses the store's default location only. Multi-location stores may need manual adjustment after import.                                                |
| Customer import | Not supported yet — only product catalogs.                                                                                                            |