Skip to main content

Wishlist Import Guide

This guide explains how to import wishlist data into the system from a CSV file.

Overview​

The wishlist import feature allows you to bulk import customer wishlist data into the system through a CSV file. The system will automatically:

  • ✅ Analyze and validate data
  • ✅ Verify products and customers exist in Shopify
  • ✅ Automatically create wishlists for new customers
  • ✅ Add products to existing customer wishlists
  • ✅ Skip duplicate products

Import Process​

Wishlist import is performed in 2 steps:

Step 1: CSV Analysis (Analyze)​

  • Upload CSV file to the system
  • System validates and verifies each row of data
  • Receive a report on valid and invalid rows
  • View detailed errors for each invalid row

Step 2: Data Import (Import)​

  • After successful analysis, preview the data that will be imported
  • Confirm import to begin the data import process
  • Monitor progress and receive results report

CSV File Format​

Your CSV file needs to have the following columns:

Required Columns​

Each data row MUST HAVE at least one of the following pairs:

To identify Product:

  • product_id OR product_handle
    • product_id: Product ID in Shopify (can be GID: gid://shopify/Product/123456 or just number: 123456)
    • product_handle: Product handle (e.g., my-awesome-product)

To identify Customer:

  • customer_id OR customer_email
    • customer_id: Customer ID in Shopify (can be GID: gid://shopify/Customer/789012 or just number: 789012)
    • customer_email: Customer email (e.g., [email protected])

Optional Columns​

  • variant_id: Product variant ID (if not provided, system will automatically select the first variant)
  • added: Date added to wishlist (format: ISO 8601 or any valid date format. If not provided, system will use current date)

Accepted Column Names​

The system automatically recognizes the following column names (case-insensitive, allows spaces and special characters):

Product:

  • product_id, productid, Product ID, Product_ID
  • product_handle, producthandle, handle, Handle

Customer:

  • customer_id, customerid, user_id, Customer ID, Customer_ID
  • customer_email, customeremail, email, user_email, useremail, Email

Variant:

  • variant_id, variantid, Variant ID, Variant_ID

Date:

  • added, created, Added, Created, date_added, created_at

CSV File Examples​

Example 1: Using Product ID and Customer Email​

product_id,customer_email,variant_id,added
gid://shopify/Product/123456789,[email protected],gid://shopify/ProductVariant/987654321,2024-01-15
123456789,[email protected],,2024-01-16

Example 2: Using Product Handle and Customer ID​

product_handle,customer_id
my-awesome-product,gid://shopify/Customer/111222333
another-product,111222333

Example 3: Complete CSV File​

product_id,product_handle,customer_id,customer_email,variant_id,added
123456789,,gid://shopify/Customer/789012,[email protected],gid://shopify/ProductVariant/111,2024-01-15T10:30:00Z
,my-product,789012,,,2024-01-16

Validation Rules​

The system will check and reject invalid data rows with the following reasons:

❌ Missing Required Information​

  • "Missing product_id and product_handle": Both product_id and product_handle are missing
  • "Missing customer_id and customer_email": Both customer_id and customer_email are missing

❌ Product Not Found​

  • "Product not found in Shopify": Product does not exist in your store

❌ Invalid Variant​

  • "Product has no variants": Product has no variants (system will automatically use first variant if variant_id is invalid)

❌ Customer Not Found​

  • "Customer not found in Shopify": Customer does not exist in your store

Import Behavior​

New Customer​

  • Create new wishlist for customer
  • Add all products from CSV file to wishlist
  • Create new customer record in the system

Existing Customer​

  • Find existing customer wishlist
  • Only add products NOT ALREADY in wishlist (skip duplicates)
  • Keep existing products in wishlist unchanged

Variant Handling​

  • If variant_id is provided and valid: use that variant
  • If variant_id is invalid or not provided: automatically select first variant of the product
  • If product has no variants: row will be rejected

Added Date Handling​

  • If added is provided: use that date (system will parse and convert to ISO 8601)
  • If not provided: use current date/time when importing

Limitations and Notes​

⚠️ Important Notes​

  1. Rate Limiting: System processes data in batches to avoid exceeding Shopify API limits. For large files, the import process may take time.

  2. Duplicate Prevention: System automatically skips duplicate products when importing. If a product already exists in the wishlist, it will not be added again.

  3. Variant Selection: If you don't specify variant_id, the system will automatically select the first variant of the product. Ensure your products have at least one variant.

  4. Email vs ID: If you use email, the system will search for customers by email. Ensure the email is accurate and the customer has been created in Shopify.

  5. Encoding: CSV files should use UTF-8 encoding to avoid special character errors.

📊 Performance​

  • Batch Size: System processes 10 data rows in parallel each time
  • Delay: 150ms delay between batches to ensure rate limits are not exceeded
  • Import Speed: For a 100-row file, estimated import time is approximately 2-3 minutes

Error Handling​

Common Errors and Solutions​

1. "No file uploaded"​

  • Cause: No file was uploaded
  • Solution: Ensure you have selected a CSV file before submitting

2. "Missing product_id and product_handle"​

  • Cause: Data row is missing product information
  • Solution: Add at least one of: product_id or product_handle

3. "Product not found in Shopify"​

  • Cause: Product does not exist in store
  • Solution:
    • Verify product_id or product_handle is correct
    • Ensure product still exists and has not been deleted in Shopify

4. "Customer not found in Shopify"​

  • Cause: Customer does not exist in store
  • Solution:
    • Verify customer_id or customer_email is correct
    • Ensure customer has been created in Shopify Admin
    • For email, ensure email is accurate (case-sensitive, no spaces)

5. "Invalid JSON format in dataToImport"​

  • Cause: Import data is not in valid JSON format
  • Solution: This is a system error, please contact support

Real-World Examples​

Example 1: Import wishlist from old system​

You have a CSV file from an old wishlist system with format:

product_id,customer_email,added
123456789,[email protected],2024-01-15
123456789,[email protected],2024-01-16
987654321,[email protected],2024-01-17

Result:

Example 2: Add products to existing wishlist​

You have a CSV file with a customer who already has a wishlist:

product_id,customer_id
111222333,789012
444555666,789012

Result:

  • If products 111222333 and 444555666 are not in wishlist → Add them
  • If already exist → Skip (don't add duplicates)

Example 3: Import with Product Handle​

product_handle,customer_email
my-product-1,[email protected]
my-product-2,[email protected]

Result:

  • System will find products by handles my-product-1 and my-product-2
  • Create wishlist for customer and add both products

Best Practices​

✅ Recommendations​

  1. Always start with Analyze: Analyze CSV file before importing to catch errors early
  2. Verify data: Ensure all product_id/product_handle and customer_id/customer_email are valid
  3. Backup data: Before importing large files, backup current data
  4. Test with small file: Test with 5-10 rows before importing large files
  5. Use GID format: Use GID format (gid://shopify/Product/123) for IDs to ensure accuracy
  6. Date format: Use ISO 8601 format (2024-01-15T10:30:00Z) for added field

❌ Avoid​

  1. Don't import files that are too large (>1000 rows) at once - split them up
  2. Don't use email if customer doesn't exist in Shopify yet
  3. Don't leave both product_id and product_handle empty in the same row
  4. Don't leave both customer_id and customer_email empty in the same row

Support​

If you encounter issues when using the import feature:

  1. Review your CSV file according to the guidelines above
  2. Check detailed errors in the Analyze report to see which rows have issues
  3. Contact support: [email protected]

Note: This documentation is updated according to the latest version of the application. If you notice any discrepancies, please let us know.