Import produktów do WooCommerce z pliku CSV i XML - poradnik krok po kroku

Importowanie kilku tysięcy produktów ręcznie to strata czasu, którego nie ma żaden właściciel sklepu. W praktyce różnica między dobrze przygotowanym plikiem CSV a źle zmapowanym importem to kilka godzin naprawiania bałaganu w bazie danych - albo przekazanie klientowi gotowego, działającego sklepu w dniu otwarcia.

W tym poradniku pokazuję cały proces: od przygotowania pliku, przez mapowanie kolumn, import wariantów i zdjęć, aż po masowe aktualizacje cen i stanów magazynowych. Bazuję na wbudowanym importerze WooCommerce i na WP All Import, który jest moim podstawowym narzędziem przy projektach z setkami lub tysiącami SKU.

Kiedy wystarczy wbudowany importer, a kiedy potrzebujesz WP All Import

WooCommerce ma własny importer CSV dostępny od razu po instalacji: Produkty > Import. Jest prosty, działa bez dodatkowych wtyczek i obsługuje produkty proste oraz zmienne z ich wariantami. Przy jednorazowym załadowaniu katalogu do 300-500 produktów bez skomplikowanych pól niestandardowych - spokojnie wystarczy.

Problemy zaczynają się, gdy:

• Masz plik XML z hurtowni z własną strukturą tagów
• Chcesz aktualizować tylko wybrane pola (np. cenę) bez nadpisywania opisu
• Import ma się powtarzać automatycznie co noc
• Produkty mają pola ACF, atrybuty własne lub meta niestandardowe
• Baza liczy ponad 2000 wierszy i shared hosting blokuje timeout

W tych przypadkach WP All Import Pro z WooCommerce Add-On to jedyne sensowne narzędzie, które nie zmusza do pisania własnego skryptu.

Przygotowanie pliku CSV - co musi się zgadzać

Plik CSV dla WooCommerce to nie jest dowolna tabela. Musi spełniać konkretne wymagania, bo importer nie zguadnie intencji - odczyta to, co znajdzie w nagłówku.

Obowiązkowe zasady techniczne:

• Kodowanie: UTF-8 bez BOM. Jeśli eksportujesz z Excela, wybierz "CSV UTF-8 (z BOM)" i następnie usuń BOM w Notepad++ (Encoding > Convert to UTF-8 without BOM). BOM w pliku CSV powoduje błąd importu lub znak  na początku pierwszej kolumny.
• Separator: przecinek. Jeśli tworzysz plik Excelem ze środowiska polskiego, domyślnie zapisuje średnik - zmień przed importem.
• Nagłówki w pierwszej linii, bez spacji na początku i końcu nazwy kolumny.

Najważniejsze kolumny standardu WooCommerce:

Najczęstszy błąd, który widzę w plikach od klientów: kolumna Named zamiast Name, albo Regular Price z wielką literą P - importer traktuje to jak pole niestandardowe i nic nie mapuje.

Import produktów prostych krok po kroku

Produkt prosty to jeden wiersz w CSV. Konfiguracja wbudowanego importera:

1. Wejdź w Produkty > Import > Wybierz plik CSV > Continue
2. WooCommerce wyświetli panel mapowania kolumn. Jeśli używasz szablonu WC, większość jest już automatycznie zmapowana.
3. Sprawdź, czy kolumny: Name, SKU, Regular price, Categories, Images wskazują na prawidłowe pola.
4. Zaznacz opcję "Zaktualizuj istniejące produkty" tylko jeśli reimportujesz - bez tego WooCommerce tworzy duplikaty każdej SKU już istniejącej.
5. Kliknij "Uruchom importer" i poczekaj na ekran z podsumowaniem (X zaimportowanych, Y zaktualizowanych, Z błędów).

U klienta z branży meblowej miałem plik 4200 produktów prostych od polskiego dystrybutora. Shared hosting LH.pl, limit PHP 30 sekund. Podzieliłem na 9 plików po 470 wierszy i importowałem jeden po drugim - łącznie 45 minut zamiast jednego importu kończącego się błędem 504.

Produkty wariantowe - najczęstsze miejsce, gdzie coś idzie nie tak

Warianty to miejsce, gdzie wbudowany importer WooCommerce potrafi zachować się nieprzewidywalnie, jeśli struktura CSV nie jest dokładna.

Zasada jest prosta: jeden wiersz = jeden wariant, plus jeden wiersz rodzic. Rodzic ma typ variable, wariant ma typ variation. W kolumnie Parent wariantu wpisujesz SKU rodzica.

Przykładowa struktura dla koszulki w dwóch rozmiarach:

Type,SKU,Name,Parent,Attribute 1 name,Attribute 1 value(s),Regular price
variable,SHIRT-001,Koszulka bawełniana,,Rozmiar,"S,M",
variation,SHIRT-001-S,,SHIRT-001,Rozmiar,S,49.00
variation,SHIRT-001-M,,SHIRT-001,Rozmiar,M,49.00

Jeśli importer tworzy produkty proste zamiast zmiennych - sprawdź, czy w kolumnie Type masz dokładnie variable (małe litery, bez spacji). Jeden błąd w tym polu i cały import trafia do kosza.

Przy WP All Import mapowanie wariantów wygląda inaczej: tworzysz jeden import dla produktów-rodziców i osobny dla wariantów, albo używasz trybu "grouped import" z funkcją wykrywania rodzica po SKU. WP All Import pozwala też pisać proste wyrażenia PHP w polach mapowania, np. {price[1]} * 1.23 żeby od razu przeliczyć cenę netto na brutto.

Import zdjęć - URL, FTP i co naprawdę spowalnia serwer

Zdjęcia to najcięższa część importu. WooCommerce pobiera każde zdjęcie przez HTTP i zapisuje je w bibliotece mediów - to oznacza osobne żądanie sieciowe dla każdego pliku.

Masz trzy opcje:

1. Zdjęcia przez URL - najprostsze, ale najwolniejsze. W kolumnie Images wpisujesz adres https do pliku. Importer pobiera go i zapisuje. Przy 1000 produktów z jednym zdjęciem każdy to realnie 30-60 minut dodatkowego czasu importu na typowym hostingu.

2. Zdjęcia wgrane wcześniej przez FTP - szybsze, ale wymaga przygotowania. Wgrywasz wszystkie pliki JPG do katalogu /wp-content/uploads/produkty/ przez FTP, a w CSV wpisujesz ścieżkę względną lub URL. WooCommerce importuje metadane, a pliki są już na miejscu.

3. Narzędzie Add From Server - wtyczka, która pozwala zarejestrować istniejące pliki z serwera jako pozycje biblioteki mediów. Używam jej razem z WP All Import przy migracjach sklepów, gdzie zdjęcia są już na hostingu.

U klienta z branży odzieżowej (sklep DE) miałem 3200 produktów, każdy z 4 zdjęciami. Łącznie 12 800 plików JPG od hurtowni na ich serwerze. Import przez URL trwał ponad 8 godzin i kilka razy się urywał przez timeout FTP. Rozwiązanie: wget do lokalnego pobrania wszystkich zdjęć, upload na hosting przez FTP, import ze ścieżek lokalnych. Czas importu: 40 minut.

WP All Import: mapowanie kolumn i transformacje danych

WP All Import to de facto standard w projektach, gdzie dane źródłowe nie pasują 1:1 do pól WooCommerce. Interfejs drag & drop pozwala mapować kolumny CSV lub tagi XML na pola produktu bez pisania kodu.

Kluczowe funkcje, których nie ma wbudowany importer:

W praktyce: klient z branży elektroniki miał plik XML od hurtowni z tagami <cena_katalogowa> i <cena_hurt>. Chciał sprzedawać po cenie katalogowej pomniejszonej o 3%, z ceną promocyjną równą cenie hurt + 10%. W WP All Import to dwie formuły w dwóch polach - bez linii kodu PHP w plikach tematu.

Konfiguracja harmonogramu w WP All Import:

1. Zapisz import z mapowaniem (przyciski na dole kreatora).
2. Wejdź w All Import > Manage Imports > kliknij nazwę importu > Scheduling.
3. Wpisz URL do pliku źródłowego (musi być publicznie dostępny HTTPS lub dane FTP).
4. Ustaw częstotliwość: hourly, daily, weekly lub własny cron.
5. Na produkcji: wyłącz WP-Cron w wp-config.php i dodaj systemowy cron przez panel hostingu.

Import z pliku XML hurtowni - podejście xpath

XML z polskich hurtowni to temat osobny. Każda hurtownia ma własną strukturę, rzadko zgadzającą się ze standardem WooCommerce. Widziałem pliki, gdzie zdjęcia były zagnieżdżone 4 poziomy głębiej, ceny były atrybutem tagu a nie wartością, a opis był podzielony na 6 osobnych tagów.

WP All Import radzi sobie z tym przez xpath. Po wgraniu pliku XML narzędzie wyświetla jego strukturę jako drzewo. Przeciągasz tagi na pola WooCommerce. Jeśli potrzebujesz połączyć kilka tagów w jedno pole (np. <opis_krotki> + <opis_dlugi> w jedno Description), używasz funkcji {opis_krotki[1]}nn{opis_dlugi[1]}.

Do integracji z hurtownią i automatycznej synchronizacji stanów warto zajrzeć do artykułu o integracji sklepu z hurtownią i synchronizacji stanów magazynowych, gdzie opisuję cały przepływ od pobrania pliku po aktualizację dostępności.

Masowe aktualizacje cen i stanów - bez nadpisywania opisów

To jest scenariusz, który pojawia się dosłownie u każdego klienta prowadzącego sklep WooCommerce z hurtownią: ceny i stany zmieniają się codziennie, ale opisy, zdjęcia i SEO były edytowane ręcznie przez miesiące i nie można ich nadpisać.

Wbudowany importer WooCommerce nie obsługuje tego scenariusza - nadpisuje każde pole, które znajdzie w pliku CSV. Jedyne wyjście to przygotowanie pliku tylko z kolumnami ID/SKU + Price + Stock i uruchomienie importu z opcją "Update existing products".

WP All Import rozwiązuje to elegancko: w ustawieniach importu wybierasz "Update existing records" i zaznaczasz dokładnie, które pola mają być aktualizowane. Pole Description pozostaje niezmienione nawet jeśli plik źródłowy je zawiera.

Przy konfiguracji sklepów wielokanałowych przez BaseLinker stany magazynowe synchronizują się przez API BaseLinker, ale ceny często trzeba wgrywać oddzielnym importem CSV od hurtowni - to typowe połączenie obu metod.

Najczęstsze błędy importu i jak je naprawić

Po dziesiątkach importów u klientów mam gotową listę problemów, które się powtarzają:

Błąd: "The file is empty or using a different encoding" - plik jest w kodowaniu ANSI lub ma BOM. Otwórz w Notepad++, sprawdź w dolnym pasku i zmień na UTF-8 bez BOM.

Błąd: Duplikaty produktów po imporcie - brak opcji "Update existing". WooCommerce tworzy nowy produkt dla każdego wiersza, jeśli nie znajdzie pasującego SKU. Przy reimporcie zawsze zaznacz "Zaktualizuj istniejące produkty".

Błąd: Warianty zaimportowane jako produkty proste - błąd w kolumnie Type lub brak kolumny Parent. Sprawdź małe litery w wartościach (variation, nie Variation).

Błąd: Zdjęcia się nie importują - serwer zablokował zewnętrzne żądania HTTP (firewall WAF). Sprawdź w logach lub tymczasowo wyłącz WAF podczas importu.

Błąd: Kategorie nie tworzą się jako hierarchia - separator musi być > z spacją po obu stronach: Odzież > Kurtki > Zimowe.

Bezpieczeństwo i backup przed masowym importem

Import masowy to operacja na bazie danych, której nie można cofnąć przyciskiem Ctrl+Z. Kilka zasad, których sam przestrzegam:

Before każdym importem na produkcji:

• Backup bazy: phpMyAdmin > Export lub wp db export backup-przed-importem.sql przez WP-CLI.
• Sprawdź, ile produktów jest w bazie przed importem (Produkty > widok listy, liczba w nagłówku).
• Zrób import testowy na 10 wierszach i ręcznie zweryfikuj 2-3 produkty po imporcie.
• Dopiero po weryfikacji uruchom pełny import.

Po imporcie:

• Sprawdź podsumowanie: X zaimportowanych, Y zaktualizowanych, Z błędów.
• Kliknij "Pokaż błędy" i zapisz log - każdy błąd to produkt, który nie trafił do sklepu.
• Zweryfikuj losowo 5-10 produktów różnych typów (prosty, wariantowy, z galerią).
• Sprawdź, czy liczba produktów w sklepie zgadza się z oczekiwaną.

Jeśli prowadzisz sklep WooCommerce na własną rękę i nie masz jeszcze doświadczenia z migracjami lub importami na żywo, przeczytaj kompletny przewodnik budowy sklepu WooCommerce - tam opisuję też kwestię środowisk dev/staging.

Przy większych projektach, gdzie import to stały element procesu operacyjnego, warto rozważyć profesjonalne wdrożenie sklepu z konfiguracją automatycznej synchronizacji od początku.

Co robi większość poradników źle

Prawie każdy tekst o imporcie CSV do WooCommerce skupia się na szczęśliwej ścieżce: plik jest czysty, kodowanie się zgadza, hurtownia daje dane w formacie WooCommerce. W praktyce tak nie jest nigdy.

Rzeczywiste wyzwania, które pomijają inne poradniki:

• Plik Excel od klienta z polskim systemem Windows ma separator średnikowy i kodowanie Windows-1250.
• Hurtownia daje PDF z cenami, a nie XML - trzeba wyciągnąć dane przez skrypt lub ręcznie.
• Jeden wariant ma dwie wartości atrybutu jednocześnie (rozmiar S + kolor czerwony jako jeden SKU) - to wymaga atrybutu wielowymiarowego.
• Ceny w pliku są z VAT, a WooCommerce jest ustawiony na ceny netto - każda cena wymaga przeliczenia.
• Import się udał, ale produkty nie pojawiają się w sklepie, bo status jest "draft" zamiast "publish" - w CSV musi być kolumna Published z wartością 1.

Jeśli budujesz sklep i planujesz regularną synchronizację z hurtownią, pomyśl o tym już na etapie wyboru rozwiązania. Kontakt - chętnie ocenię, które podejście będzie sensowne przy Twoim katalogu i częstotliwości aktualizacji.

Najczęstsze pytania

Czy WooCommerce ma wbudowany importer CSV bez dodatkowych wtyczek?

Tak, WooCommerce od wersji 3.1 ma wbudowany importer CSV dostępny w Produkty > Import. Obsługuje produkty proste, zmienne i ich warianty w standardowym formacie WooCommerce. Ograniczeniem jest brak obsługi produktów subskrypcyjnych, złożonych (composite) oraz zaawansowanego mapowania pól niestandardowych - tam potrzebny jest WP All Import lub podobne narzędzie.

Jaki format musi mieć plik CSV do importu WooCommerce?

Plik musi być zakodowany w UTF-8 bez BOM, z przecinkiem jako separatorem kolumn i nagłówkami w pierwszej linii. Obowiązkowe kolumny to Type (simple/variable/variation) i Name dla produktów prostych oraz Type, Name i Parent (SKU rodzica) dla wariantów. Resztę kolumn WooCommerce mapuje podczas importu. Dobrą praktyką jest eksportowanie pustego produktu testowego i użycie otrzymanego pliku jako szablonu.

Jak importować produkty wariantowe z wielu wariantów do WooCommerce?

Każdy wariant to osobny wiersz w CSV. Rodzic ma typ 'variable', warianty mają typ 'variation' i w kolumnie Parent wpisany SKU rodzica. Atrybuty definiujesz w kolumnach Attribute 1 name, Attribute 1 value(s) - dla rodzica wszystkie wartości oddzielone przecinkiem, dla wariantu konkretna jedna wartość. Meta:attribute_1 uzupełniasz tylko dla wierszy wariantów.

Czy mogę importować zdjęcia produktów z zewnętrznych URL-ów?

Tak, zarówno wbudowany importer WooCommerce, jak i WP All Import obsługują pobieranie zdjęć z URL. W kolumnie Images (lub Images w WP All Import) wpisujesz adres https do pliku graficznego. Zdjęcia są pobierane i zapisywane w bibliotece mediów WordPress. Pamiętaj, że pobieranie zdjęć znacząco wydłuża czas importu - przy 1000 produktów może to dodać 30-60 minut do całego procesu.

Ile produktów można zaimportować jednorazowo do WooCommerce?

Wbudowany importer nie ma twardego limitu, ale przy bazach powyżej 2000 wierszy pojawiają się problemy z timeoutem serwera (limit 30-60 sekund na shared hosting). WP All Import przetwarza dane partiami po 20-50 wierszy na żądanie HTTP, co omija timeout. Dla bezpieczeństwa dzielę pliki na partie po 500-1000 wierszy i importuję sekwencyjnie, szczególnie gdy import obejmuje pobieranie zdjęć.

Jak zaktualizować ceny i stany magazynowe bez nadpisywania opisów?

WP All Import pozwala wybrać, które pola są aktualizowane podczas reimportu. W ustawieniach importu w sekcji 'What to do with existing records' można zaznaczyć tylko kolumny Price i Stock i pozostawić opis oraz zdjęcia bez zmian. Wbudowany importer WooCommerce przy reimporcie nadpisuje wszystkie pola, które znajdzie w pliku - dlatego do częstych aktualizacji cen wolę WP All Import.

Czy WP All Import Pro obsługuje automatyczny harmonogram importu?

Tak, WP All Import Pro umożliwia ustawienie automatycznego importu przez WP-Cron lub systemowy cron serwera. Plik źródłowy może być pobierany z URL (https), FTP lub SFTP. Harmonogram konfiguruje się w ustawieniach importu po zapisaniu definicji mapowania. Na produkcyjnych serwerach LH.pl polecam zastąpienie WP-Cron systemowym cronem - jest bardziej niezawodny i nie wymaga ruchu na stronie do uruchomienia.

Jak importować produkty z pliku XML hurtowni, który ma inną strukturę?

WP All Import obsługuje dowolne pliki XML przez mapper xpath. Po wgraniu pliku narzędzie parsuje strukturę i pozwala przeciągać tagi XML na pola WooCommerce. Jeśli hurtownia daje np. tag , mapujesz go na pole Regular Price i możesz od razu dodać formułę matematyczną (np. pomnożenie przez 1.23 dla VAT). To jest główny powód, dla którego przy integracjach z hurtowniami polecam WP All Import zamiast narzędzi natywnych.