DataFirefly Shopify Migrator: volledige gids

Overzicht

DataFirefly Shopify Migrator is een PrestaShop 8- en 9-module die een volledige catalogus naar Shopify exporteert, met twee modi naar keuze: CSV (generatie van bestanden die klaar zijn voor handmatige import via de Shopify-admin, zonder API-sleutel) of API (directe push naar een verbonden Shopify-winkel via de Admin REST API 2026-04).

De module beheert acht entiteiten, in de volgorde waarin ze doorgaans gemigreerd moeten worden:

• Producten: volledige productpagina’s, varianten tot 3 attribuutgroepen, afbeeldingen, voorraden, prijzen excl. of incl. btw, SEO-tags behouden via de globale metafields title_tag/description_tag
• Collecties: PrestaShop-categorieën omgezet in custom collections met afbeelding en beschrijving
• CMS-pagina’s: PrestaShop-pagina’s omgezet in Shopify-pagina’s met slug en SEO-meta
• Klanten: klantgegevens + standaardadres + bestelstatistieken, getagd imported-prestashop
• Bestellingen: uitsluitend consultatieve CSV-export (Shopify accepteert geen native orderimport via standaard-CSV)
• 301-redirects: correspondentietabel oude PrestaShop-URL’s → nieuwe Shopify-URL’s om de SEO te behouden
• Repair images en Variant images: twee reparatiejobs om afbeeldingen terug te halen die Shopify stilzwijgend heeft verloren tijdens de asynchrone fetch, en om elke Shopify-variant aan haar afbeelding te koppelen
• Features → Metafields: push van de PrestaShop-productkenmerken als Shopify-metafields, met automatische aanmaak van de Metafield Definitions via GraphQL

De architectuur is asynchroon per jobs: elke migratie maakt een job in de database aan, die daarna in instelbare batches wordt verwerkt door een door een token beschermde cron-worker. De rate limit van Shopify wordt automatisch gerespecteerd (1,8 req/s, retry bij 429), en een persistente mapping in de database koppelt de PrestaShop-identifiers aan de Shopify-identifiers, wat de redirects mogelijk maakt en duplicaten bij een herstart vermijdt.

Vereisten

• PrestaShop 8.0 tot 9.x
• PHP 7.4 tot 8.3
• Voor de API-modus: een Shopify-doelwinkel (Basic-abonnement volstaat), een Shopify Partners-account of toegang tot het Shopify Dev Dashboard
• Voor de cron-modus: de mogelijkheid om aan hostzijde een URL in te plannen (crontab, cron-as-a-service, of Plesk/cPanel)
• Aan serverzijde: PHP-extensies curl en iconv geactiveerd

Installatie

1. Download de ZIP vanuit uw DataFirefly-klantaccount (sectie Downloads van de productpagina).
2. Ga in de PrestaShop-backoffice naar Modules → Modulebeheer → Een module uploaden en upload de ZIP.
3. Klik op Installeren. De module maakt drie tabellen aan (jobs, mapping, log) en een eigen tabblad in Geavanceerde instellingen → Shopify Migrator.
4. Klik op Configureren om de hoofdinterface te openen.

Kiezen tussen CSV-modus en API-modus

CSV-modus

De module genereert CSV-bestanden in het native formaat dat Shopify Admin verwacht (Products Import, Customers Import, URL Redirects Import). U downloadt elk bestand vanuit het tabblad Jobs en importeert het daarna handmatig in Shopify.

Voordelen: geen enkele API-sleutel te configureren, mogelijkheid de bestanden vóór de import te inspecteren en aan te passen, zeer snelle verwerking aan PrestaShop-zijde.

Beperkingen: Shopify-collecties hebben geen native CSV-import (het gegenereerde bestand dient als referentie), en bestellingen zijn aan Shopify-zijde nooit importeerbaar via standaard-CSV.

API-modus

De module stuurt elke entiteit rechtstreeks naar uw Shopify-winkel via de Admin REST API 2026-04, met beheer van de rate limit, automatische retry bij fout 429 en persistente ID-mapping voor automatische redirects en idempotente herstarts.

Voordelen: migratie van begin tot eind in één beweging, redirects rechtstreeks gepusht, collecties automatisch aangemaakt met koppeling van de producten, perfect voor grote catalogi.

Beperkingen: vereist een Shopify-app met de juiste scopes, en sommige Shopify-organisaties die na april 2025 zijn aangemaakt zijn GraphQL-only (de module blijft REST-compatibel voor standaardorganisaties).

API-modus: de Shopify-app aanmaken

De app aanmaken in het Dev Dashboard

1. Log in op het Shopify Dev Dashboard (dev.shopify.com/dashboard) met uw Partners-account.
2. Klik op Create app, geef de app een naam (bijvoorbeeld “Migrator”) en bevestig.
3. In het configuratiescherm mag de App URL op eender welke geldige HTTPS-waarde blijven staan. Ze wordt alleen voor OAuth gebruikt, wat ons geval niet betreft.

Configuratie van de scopes

Activeer in Configuration → Admin API integration → Configure access scopes de volgende scopes:

• read_products, write_products
• read_customers, write_customers
• read_content, write_content
• read_inventory, write_inventory
• read_online_store_pages, write_online_store_pages
• read_online_store_navigation, write_online_store_navigation
• write_metaobject_definitions (alleen als u de entiteit Features → Metafields gebruikt)

Klik op Save.

Installatie op de doelwinkel

1. Kies in Distribution voor Custom distribution en voeg uw Shopify-doelwinkel toe.
2. Klik op de gegenereerde installatielink, die het merchant-toestemmingsscherm in Shopify Admin opent.
3. Bevestig de installatie: u krijgt het eindscherm van de app.

Ophalen van de Client ID en het Client Secret

Kopieer in Settings → Credentials van de app de Client ID, en klik daarna op het oogicoon naast Secret om het te onthullen en te kopiëren.

API-modus: configuratie van de credentials

Kies in het tabblad Settings van de module de modus Shopify Admin REST API en vul in:

• Shopify store domain: ofwel de korte naam (my-store), ofwel het volledige domein (my-store.myshopify.com).
• API version: standaard 2026-04, de huidige stabiele versie.
• Authentication method: twee keuzes zijn mogelijk:

Methode 1: Admin access token

Voor de zeldzame gevallen waarin u al over een geldig Admin API-token beschikt (legacy custom app of handmatig via OAuth verkregen token). Plak het token in het daarvoor bestemde veld en sla op.

Methode 2: Client Credentials Grant (aanbevolen)

De module wisselt uw Client ID + Client Secret in voor een Admin API access token via de OAuth Client Credentials Grant-flow. Het token wordt gecachet (24 u) en automatisch vernieuwd minder dan 5 minuten vóór het verlopen. Geen enkele handmatige ingreep tijdens de migratie.

Vul beide velden in en sla op. Klik op Test connection: de module toont de naam van uw Shopify-winkel en de resterende tijd tot het verlopen van het token.

Migratie van de producten

De productexport is de meest complexe. Hij beheert de producten, de varianten (tot 3 attribuutgroepen, zoals Shopify toestaat), de afbeeldingen (absolute URL vanaf uw PrestaShop), de voorraden, de prijzen, de fabrikanten gebruikt als vendor, de categorieën omgezet in tags en type, en de SEO-tags behouden via de metafields global.title_tag en global.description_tag.

De job starten

1. Selecteer in Run a migration de kaart Products.
2. Klik op Create export job. De job verschijnt in de lijst van het tabblad Jobs met de status pending.
3. Hebt u de cron geconfigureerd, dan pakt de worker hem binnen de minuut op. Anders klikt u op de knop Run now om hem synchroon te laten vorderen (beperkt door de PHP-timeout, ongeveer 30 seconden).

Voortgangsopvolging

Het tabblad Jobs ververst zichzelf elke 10 seconden. Elke regel toont de status (pending/running/done/failed/cancelled), het voortgangspercentage, het aantal successen en fouten, en een uitklapbare logknop die de laatste 30 regels van het journaal toont.

Het geval van de CSV-modus

Het bestand job_X_products.csv wordt gegenereerd in het Shopify Products Import-formaat. Download het vanuit de joblijst, ga daarna in Shopify Admin naar Products → Import en upload het bestand. Shopify verzorgt vervolgens de verwerking aan zijn kant, met een e-mailmelding aan het einde.

Migratie van de collecties

De PrestaShop-categorieën (behalve de root en categorie ID 1) worden Shopify-custom collections, met hun titel, beschrijving, afbeelding, SEO-tags en de opgeschoonde slug. In API-modus worden de al gemigreerde producten automatisch aan elke collectie gekoppeld via het endpoint /collects.json.

Migratie van de CMS-pagina’s

De actieve PrestaShop-pagina’s worden geëxporteerd als Shopify-pagina’s met hun titel, HTML-inhoud (relatieve afbeeldings-URL’s worden automatisch omgezet in absolute URL’s naar uw PrestaShop-domein), slug en SEO-tags.

Migratie van de klanten

Voor elke actieve, niet-verwijderde klant exporteert de module de naam, het e-mailadres, het standaardadres, het totaal bestede bedrag, het aantal geldige bestellingen en de nieuwsbrief-opt-in. Elke klant krijgt de tag imported-prestashop om het latere filteren te vergemakkelijken.

Migratie van de bestellingen (alleen CSV)

De orderexport is consultatief: Shopify biedt geen native orderimport via standaard-CSV. Het gegenereerde bestand bevat alle nuttige informatie voor archief of analyse: referentie, datum, status, klant, factuur- en leveringsadres, valuta, totalen excl. en incl. btw, vervoerder, tracking, en één regel per gekocht product.

U kunt op datumbereik filteren in het aanmaakformulier van de job (velden Orders from en Orders to).

Voor Shopify Plus-gebruikers accepteren tools van derden zoals Matrixify dit formaat als invoer voor een echte herimport.

Migratie van de 301-redirects

Dit is het sleutelelement om uw SEO te behouden op de dag van de domeinoverstap. De module leest de mappingtabel die door de eerdere exports is opgebouwd (producten, collecties, pagina’s) en genereert een CSV met twee kolommen in het native Shopify URL Redirects-formaat, met de oude PrestaShop-URL’s in de eerste kolom en de nieuwe Shopify-URL’s in de tweede.

In API-modus pusht de module elke redirect rechtstreeks via POST /redirects.json. In CSV-modus importeert u het bestand in Shopify Admin via Online Store → Navigation → URL Redirects → Import.

Uitsluitingsfilters (v1.1)

Twee optionele filters laten toe producten van de export uit te sluiten, instelbaar in Settings → Product filters (exclusions).

Categorieën uitsluiten

Tekstveld met een lijst PrestaShop-categorie-ID’s, gescheiden door komma’s. Een product dat tot minstens een van deze categorieën behoort, wordt van de Products-export uitgesloten. De categorieën zelf blijven gemigreerd door de entiteit Collections (nuttig als een technische categorie niet bedoeld is om getoond te worden maar wel producten kan bevatten).

Referentievoorvoegsels uitsluiten

Tekstveld met een lijst voorvoegsels, gescheiden door komma’s. Elk product waarvan de referentie met een van deze voorvoegsels begint, wordt uitgesloten. Nuttig om interne producten niet te migreren (NS voor niet-verkoopbaar, HB voor buiten business, OBSOLETE- voor gestopte assortimenten, enzovoort). De voorvoegsels zijn hoofdletterongevoelig.

Reparatie van de afbeeldingen (v1.3)

Shopify downloadt de afbeeldingen asynchroon na de aanmaak van een product: het fetcht de URL die u hebt aangeleverd, en mislukt dat stilzwijgend (timeout, geblokkeerde URL, te groot bestand, geweigerd formaat), dan geeft het geen enkele fout terug. Het product wordt aan API-zijde als “success” aangemaakt, maar zonder afbeelding.

De entiteit Repair images repareert deze gevallen. Voor elk product van de mapping:

1. GET /products/{shopify_id}/images.json om de huidige afbeeldingen aan Shopify-zijde te tellen.
2. Lezen van de bijbehorende afbeeldingen in PrestaShop.
3. Heeft Shopify al evenveel afbeeldingen als PS → het product wordt overgeslagen.
4. Anders: verwijderen van de gedeeltelijke Shopify-afbeeldingen, daarna upload van elke PS-afbeelding via base64 attachment (synchrone modus, Shopify bevestigt de aanmaak onmiddellijk), met URL-fallback voor bestanden groter dan 3 MB.

API-modus verplicht. Idempotent: u kunt de job zo vaak herstarten als nodig.

Variant images (v1.4)

Zodra de hoofdafbeeldingen op hun plek staan, moet elke Shopify-variant nog aan haar bijbehorende afbeelding worden gekoppeld. De entiteit Variant images neemt dat op zich: voor elk product van de mapping bevraagt ze de lijst met Shopify-varianten en -afbeeldingen, en kruist die met de product_attribute_image-relaties van PrestaShop.

De match PS-variant → Shopify-variant gebruikt eerst de SKU (referentie van de variant), met een fallback op het optietupel (option1/option2/option3 in kleine letters) als de referentie leeg is.

De match PS-afbeelding → Shopify-afbeelding gebeurt op positie-uitlijning: de N-de PS-afbeelding komt overeen met de N-de Shopify-afbeelding. Dat geldt zolang u de afbeeldingen niet handmatig hebt herschikt in de Shopify-admin.

Idempotent: een variant die al op de juiste image_id staat, wordt overgeslagen (gelogd als already_ok). Het journaal telt per product: assigned / already_ok / missing_image / missing_variant.

Features → Metafields (v1.5)

De PrestaShop-productkenmerken (Catalogus → Attributen en Kenmerken → Kenmerken) worden als Shopify-metafields gepusht onder de namespace custom, met automatische aanmaak van de Metafield Definitions zodat ze vanuit de Shopify-admin bewerkbaar zijn.

Fase A: aanmaak van de Definitions (eerste batch)

Bij de eerste batch van de job somt de module alle verschillende features van de winkel op en maakt voor elk een Metafield Definition aan via de GraphQL-mutatie metafieldDefinitionCreate. Al bestaande definitions (code TAKEN of DUPLICATE_KEY) worden stilzwijgend genegeerd.

Fase B: push van de waarden (elke batch)

Voor elk product van de mapping somt de module de bestaande custom.*-metafields op, en voert daarna voor elke PS-feature een upsert uit: PUT als de sleutel bestaat met een andere waarde, POST als de sleutel niet bestaat. Al identieke waarden worden overgeslagen.

Conversie naam → sleutel

De naam van het PrestaShop-kenmerk wordt omgezet in een Shopify-metafieldsleutel via ASCII-transliteratie, omzetting naar kleine letters, vervanging van niet-alfanumerieke tekens door underscores en afkapping op 30 tekens. Voorbeelden:

• Matière principale wordt matiere_principale
• Poids (kg) wordt poids_kg
• Couleur wordt couleur

Cron-worker

De module stelt een door een token beschermd front-endpoint beschikbaar dat één job per tick verwerkt, met 20 batches per tick. De volledige URL met token wordt getoond in het tabblad Run a migration, met een kopieerknop.

Voorbeeld van een crontab-regel voor één tick per minuut:

* * * * * curl -s "https://uw-prestashop.com/index.php?fc=module&module=dfshopifymigrator&controller=cron&token=UW_TOKEN" > /dev/null

Zonder geconfigureerde cron kunt u een job altijd handmatig laten vorderen met de knop Run now van de joblijst (synchrone voortgang, beperkt door de PHP-timeout van de backoffice, ongeveer 30 seconden).

Aanbevolen volgorde van de jobs

Start voor een volledige migratie zonder verrassingen de jobs in deze volgorde:

1. Products: maakt de mapping PS→Shopify voor de producten aan, gebruikt door alle volgende stappen.
2. Collections: maakt de mapping voor de categorieën aan en koppelt de producten automatisch.
3. Pages: maakt de mapping voor de CMS-pagina’s aan.
4. Customers: onafhankelijk van de rest.
5. Orders: alleen consultatieve CSV, start op uw eigen tempo.
6. Repair images (indien nodig): repareert de afbeeldingen die tijdens de asynchrone Shopify-fetch verloren gingen.
7. Variant images: koppelt elke variant weer aan haar afbeelding.
8. Features → Metafields: pusht de productkenmerken als zichtbare metafields.
9. Redirects: als laatste, verbruikt de volledige hierboven opgebouwde mapping.

Bekende beperkingen (v1)

• Per migratie wordt één taal geëxporteerd (de in Settings geselecteerde taal). V2 voegt de mapping van de PrestaShop-talen naar Shopify Markets en Translate & Adapt toe.
• De bestellingen worden uitsluitend als consultatieve CSV geëxporteerd.
• De klantwachtwoorden worden niet gemigreerd.
• De varianten zijn beperkt tot 3 attribuutgroepen (Shopify-limiet Option1/Option2/Option3).
• De afbeeldingen worden geserveerd vanaf de publieke URL van uw PrestaShop: houd uw PS online tijdens de Shopify-import, en minstens tijdens de eventuele Repair images-job.

Probleemoplossing

Shopify API error: Not Found

Controleer eerst het veld API version in Settings: het moet 2026-04 zijn (oude versies zoals 2024-10 zijn ingetrokken). Controleer ook of uw app daadwerkelijk op de doelwinkel is geïnstalleerd in Distribution.

Shopify API error: Invalid API key or access token

Het token is verlopen (CCG: levensduur 24 u, automatisch ververst) of de app is gede-installeerd. Klik op Test connection om een vernieuwing van het CCG-token af te dwingen. Blijft de fout aanhouden, ga dan naar Shopify Admin → Apps and sales channels en controleer of de Migrator-app in de lijst met geïnstalleerde applicaties staat.

This action requires merchant approval for write_X scope

U hebt de scopes gewijzigd na de initiële installatie van de app, en de merchant heeft ze niet kunnen goedkeuren. De-installeer de app in Shopify Admin en herinstalleer ze via de Distribution-link van het Dev Dashboard. Het merchant-toestemmingsscherm verschijnt opnieuw met de nieuwe scopes.

shop_not_permitted bij de CCG-inwisseling

Uw Shopify-winkel zit niet in dezelfde organization als uw Dev Dashboard-app. Koppel ofwel de winkel aan uw Partners-organisatie, ofwel gebruik een handmatig verkregen Admin-token (Authorization Code Grant OAuth, buiten het bereik van de module).

Cardinality violation: Subquery returns more than 1 row

Bug verholpen in v1.2.1. Werk bij naar de laatste versie van de module.

Veel Shopify-producten zijn zonder afbeelding aangekomen

Dat is het gedocumenteerde Shopify-gedrag voor afbeeldingen die via URL worden gepusht. Start de job Repair images in API-modus: hij detecteert de producten met minder afbeeldingen dan PS en publiceert alles opnieuw in base64 (synchrone modus, garandeert de aankomst).

Veel “missing_variant” in de logs van Variant images

De SKU van de Shopify-variant komt niet overeen met de referentie van het PrestaShop-product_attribute, en de fallback op het optietupel heeft evenmin gematcht. Controleer of uw PS-varianten daadwerkelijk referenties hebben, of neem contact op met de DataFirefly-support voor een aangepaste afstemming van de matching.

Bronnen

• Productpagina DataFirefly Shopify Migrator (downloads, aankoop, licentie)
• Officiële documentatie Shopify Admin REST API: shopify.dev/docs/api/admin-rest
• Documentatie Shopify Client Credentials Grant: shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
• DataFirefly-support: hello@datafirefly.com