Help center

Everything you need to move your OpenCart store to Shopify with GSP OpenCart Migration: from installing the OpenCartextension to switching your domain.

Getting started

1. Install GSP OpenCart Migration from the Shopify App Store and open it in your Shopify admin.
2. Download the OpenCart extension for your version (shown at the bottom of every OpenCart admin page): OpenCart 3.0.x or OpenCart 4.x. Both are also on the app's home page and New migration page.
3. Install it from your OpenCart admin and copy its connection code (how: 3.0.x, 4.x). On OpenCart 1.5 or 2.x, upload the bridge file instead.
4. Paste the code and click Test connection. You'll see how many products, categories, customers, orders, coupons and information pages your store has.
5. Choose what to migrate. Everything is selected by default.
6. Run a free preview, or buy a plan and start the full migration.
7. Review the result and the report, keep Shopify up to date with Migrate changes, follow the go-live checklist, then uninstall the extension.

Before you start

• OpenCart 3.0.x and 4.x: you only need to log in to your OpenCart admin with a user that may install extensions. OpenCart 1.5 or 2.x: you upload one bridge file, which works on PHP 5.6 or newer.
• Bridge file only: access to your store's files, an FTP account (e.g. with FileZilla) or your hosting control panel's File Manager (cPanel, Plesk, DirectAdmin…).
• Store currency. Prices are copied as numbers, not converted. Set your Shopify store currency (Settings → Store details) to the same currency as OpenCart's default currency before migrating. Shopify only allows changing it before your first sale. The app warns you if the two differ.
• Shipping location. Stock is placed at a Shopify location that fulfils online orders and ships (is in a shipping profile, Settings → Shipping and delivery): your primary location if it qualifies. If no location does both, stock goes to one that fulfils online orders (or your primary location), and products can show as sold out until you add it to a shipping profile.
• Markets. Products are sold in your store's markets only (Settings → Markets). Visitors from a country that isn't in any market see products as unavailable: this is a store setting, so add the countries you sell to before going live. Migrated products are published to the Online Store and to every active market catalog that has its own product list.
• Images must be publicly reachable. Shopify downloads product and category images from your current site (the image/ folder). If your site blocks bots or hotlinking (some firewalls do), allow Shopify or pause the protection during the migration.
• Keep your Shopify store password-protected (Online Store → Preferences) until you go live, so customers don't see it half-finished.

Install the OpenCart 3.0.x extension

OpenCart has no built-in API that can read a whole store, so the app connects through a small, read-only OpenCartextension, installed from your OpenCart admin like any other module: no FTP needed. There is one package for OpenCart 3.0.x (below) and one for OpenCart 4.x. Both keep working while your store is in maintenance mode, and you uninstall them when you're done. OpenCart 1.5 and 2.x use the bridge file.

1. Download gsp-shopify-migration-oc3.ocmod.zip (download; it's also on the app's home page and New migration page). Don't unzip it.
2. In your OpenCart admin, go to Extensions → Installer, click Upload and choose the zip. Wait for the progress bar to finish.
3. Go to Extensions → Extensions, choose Modules in the filter, find GSP Shopify Migration and click Install (the green +). Then click Edit (the blue pencil).
4. The module's page shows a connection code starting with gspoc1.. Copy it, paste it into the app and click Test connection.

Install the OpenCart 4.x extension

For OpenCart 4.0.x and 4.1.x. It works like the 3.0.x extension, with one extra click in the Installer.

1. Download gsp_migration.ocmod.zip (download; it's also on the app's home page and New migration page). Don't unzip it and don't rename it: OpenCart 4 names the extension after the file, and it only works when the file is called exactly gsp_migration.ocmod.zip. If your browser saved it as gsp_migration (1).ocmod.zip, rename it back.
2. In your OpenCart admin, go to Extensions → Installer, click Upload (the blue button) and choose the zip. It appears in the list below as GSP Shopify Migration.
3. Click Install (the green +) on that row and wait for the progress bar to finish. This step doesn't exist in OpenCart 3.
4. Go to Extensions → Extensions, choose Modules in the filter, find GSP Shopify Migration and click Install (the green +). Then click Edit (the blue pencil).
5. Copy the connection code (it starts with gspoc1.), paste it into the app and click Test connection.

Update the extension

If we ask you to install a newer version:

• OpenCart 3.0.x: upload the new gsp-shopify-migration-oc3.ocmod.zip in Extensions → Installer. It replaces the old files, and your key and connection code stay the same.
• OpenCart 4.x:
  1. In Extensions → Extensions → Modules, click Uninstall (the red −) next to GSP Shopify Migration.
  2. In Extensions → Installer, click Uninstall and then Delete (the trash can) on the GSP Shopify Migration row.
  3. Upload the new gsp_migration.ocmod.zip and install it again (steps 2 to 4 of Install the OpenCart 4.x extension).
  4. Reinstalling creates a new key: copy the new connection code and paste it into the app, on the migration's page or on New migration.

OpenCart 1.5 and 2.x: the bridge file

For OpenCart 1.5 and 2.x, or if your store can't install extensions (see Troubleshooting), the app connects through a small PHP file you upload to your store instead: gsp-bridge.php. It reads your database settings from OpenCart's own config.php and answers the app's requests with your catalog, customers and orders.

1. In the app, click New migration, choose OpenCart 1.5 or 2.x as your version, then click Download bridge file. The file contains a secret key that is unique to your Shopify store, so only this app can use it. Don't share it.
2. Find your OpenCart folder: the one that contains config.php and the admin, catalog, image and system folders. On most hosts it's public_html (or public_html/shop if OpenCart is in a subfolder).
3. Upload gsp-bridge.php into that folder, next to config.php. Not into admin.
   • FileZilla / FTP: connect to your host, open the folder on the right-hand side and drag the file into it.
   • cPanel File Manager: open File Manager, go to the folder, click Upload and choose the file.
4. Upload it unchanged: don't rename it, and don't open and re-save it in an editor (some editors change it). To check, open https://your-store.com/gsp-bridge.php in your browser: it should show a short line of text starting with {"ok":true.

Connect your store

With the extension, paste the connection code from the module's page and click Test connection. Spaces or line breaks copied along with it don't matter.

With the bridge file, enter your store URL (e.g. https://your-store.com, including the folder if OpenCart is installed in one, e.g. https://your-store.com/shop), then click Test connection. The app looks for the bridge file at your store URL + /gsp-bridge.php. If you uploaded it somewhere else, click Bridge file is somewhere else? and enter its full address.

You'll see a summary of your store and can choose what to migrate: products, categories, customers, coupons, information pages and orders. Categories are always included with products, so products land in the right collections.

Free preview

Before buying, run a free preview: 10 products (plus all categories, and up to 10 customers, orders, coupons and information pages) are imported so you can check how your data looks in Shopify. Preview products and pages are hidden drafts and no redirects are created. When you run the full migration, the preview records are updated and published, never duplicated. Previews can be deleted from your migration history.

Plans and pricing

One-time payments, billed through Shopify on your Shopify invoice. No subscription.

• Each store is fully migrated once. To bring over later changes from the same store, use the Migration Update add-on.
• Basic covers one OpenCart store. Need more? Upgrade to Advanced for the difference ( $50) from the Pricing page in the app.
• If a migration is interrupted or you cancel it, Resume continues it at no extra cost.

What's migrated

How your data is mapped

If your store has several languages, the default language is migrated. In a multi-store setup, OpenCart keeps one shared catalog, customer list and order history, so all of them are migrated; SEO keywords and store settings (currency, weight unit, order statuses) come from the default store. Country and region names are read in the default language too (on OpenCart 4.1 they're stored per language) and matched to Shopify's countries and provinces; a region Shopify doesn't know is left out of the address and reported.

Re-runs update the app's own records. Every product, collection, customer, page and order the app creates carries a hidden opencart.source_ref metafield that identifies its OpenCart record. You may see it in a record's Metafields, as an unstructured metafield. Don't delete it if you plan to run Migrate changes or resume a migration: it's how the app recognises what it created.

Orders

Each OpenCart order becomes a Shopify order with the same number (#1234), its original date and its OpenCart totals. The order's OpenCart ID, invoice number, payment method and (in multi-store setups) store name are added as order attributes, the customer's comment becomes the order note, and order custom fields become order metafields. Orders with status 0 (“missing orders”: checkouts that were never completed) aren't migrated.

Order statuses

Every migrated order is tagged opencart-migration and opencart-<status> (e.g. opencart-complete), so the original status is kept. Shopify can't create an order as cancelled, so canceled, denied, expired, failed and voided orders are imported with a voided payment and archived. Refunded orders also get a Refunded in OpenCart attribute with the amount.

Archived orders: where to find them

Orders that are finished in OpenCart (complete, refunded, cancelled and the other statuses marked “Yes” above) are created archived, as Shopify itself does with orders that are paid and fulfilled (“Automatically archive the order”, Shopify's default). Archived orders don't appear under Orders → All: open Orders and choose the Archived view. The migration page shows how many orders were archived, with a button that opens that list. To move an order back to your open orders, select it and choose Unarchive orders.

Currency

OpenCart records order amounts in your store's default currency, so orders are imported in that currency. When the customer paid in another currency, a Customer currency attribute shows that currency, the exchange rate and the total the customer saw, and the order is reported. If Shopify refuses the order's currency, the amounts are imported in your Shopify store currency without conversion, and reported.

Taxes, shipping and discounts

• Line prices exclude tax, as in OpenCart. Taxes come from the order's tax totals, with their names and rates; when an order had several taxes, each line's tax is split between them proportionally (reported). Tax on shipping goes on the shipping line.
• Shipping becomes a shipping line with the OpenCart shipping method's name, code and price.
• A coupon becomes the order's discount code, with the amount it took off. Gift vouchers and reward points are imported as a discount too (reported). Positive extras, such as a handling or low-order fee, become custom line items.
• If the lines don't add up to the OpenCart total, the order is reported so you can check it.

Customers and guest orders

• An order from a registered customer is linked to that migrated customer.
• Guest orders (and orders whose customer wasn't migrated) are linked by email: to the Shopify customer with that email if there is one, otherwise a customer is created with the order's name and email (tagged opencart-migration). Orders without an email have no customer.
• If Shopify refuses to link the customer, for example because the email or phone number already belongs to another Shopify customer, the order is still imported with its email but without a customer link, and reported. That way the order isn't lost and no duplicate customer is created.

Line items

• Lines are linked to the migrated product and variant, so migrate products first. A line whose product wasn't migrated (or was deleted in OpenCart) becomes a custom item with the same title, SKU and price (reported).
• The options the customer chose (size, colour, text they typed…) are shown on the line as properties and in the variant title.

Good to know

• No emails are sent to customers: no order confirmations, shipping notifications or account invites.
• Stock levels aren't changed by migrated orders.
• Orders are created once. Later runs leave them as they are (“Already migrated”); Migrate changes only syncs their status (paid, fulfilled, cancelled, refunded), because Shopify doesn't allow an order's lines to be rewritten.
• On Shopify development and trial stores, Shopify allows 5 new orders per minute, so the app creates orders at that pace there. Paid stores aren't limited.

Product options

Shopify builds product choices from up to 3 options and their variants. OpenCart has more option types, so each type is migrated like this:

• Prices exclude tax, like in OpenCart admin (OpenCart's storefront may show them with tax).
• Optional options become required choices: a Shopify variant always needs a value.
• Stock per combination = the lowest stock of its option values.

The metafield. opencart.custom_options is a JSON product metafield in a stable, documented format (gsp.custom_options, version 1) that any product options app or developer can import. For each option it records the name, OpenCart type, whether it's required, its sort order, why it isn't a variant (its type, or Shopify's 3-option limit), the default value of text and date options, and each value with its price change (excluding tax, in your store currency), weight change and stock. To see it, open a product in Shopify admin and scroll to Metafields (or go to Settings → Custom data → Products). Each affected product is also listed in the migration report.

Show specifications on your product page

Shopify themes don't show everything OpenCart showed on a product page. The app includes a theme app block, OpenCart product details, that displays the migrated data:

• a Specifications table with your OpenCart attributes (e.g. Material: Cotton);
• Model and MPN;
• quantity discounts (e.g. 10+ for $8.00 each);
• optionally, a read-only list of the extra options saved in the metafield (to let customers choose them, use LivePrice Variants).

To add it (Online Store 2.0 themes, such as Dawn):

1. In Shopify admin, go to Online Store → Themes and click Customize.
2. In the page picker at the top, choose Products → Default product.
3. In the product information section, click Add block, open the Apps tab and choose OpenCart product details. Drag it where you want it, turn parts on or off in its settings, and click Save.

What isn't migrated

• Customer passwords (Shopify doesn't accept them; customers set a new one through an account invite)
• Saved payment methods and card details
• Product reviews
• Checkbox, text, file and date/time options as Shopify variants (Shopify doesn't support them; they're saved in a metafield and can be shown with LivePrice Variants)
• Quantity discounts and customer-group prices as working prices (they're saved in metafields; the theme block displays quantity discounts)
• Your OpenCart theme, design and extension features

Checkbox, text, file and date/time options, and options beyond Shopify's 3, aren't lost: they're saved in a metafield (see Product options).

Customer passwords can't be migrated: OpenCart stores them as one-way hashes that Shopify can't accept (and the bridge never reads them). To let customers log in, invite them from Shopify (Customers → select → Send account invite), or turn on Shopify's passwordless customer accounts.

During the migration

• The migration runs on our servers: you can close the page and come back any time.
• The progress page shows each data type with processed, created, updated, already-migrated and failed counts.
• Cancel stops after the current batch; Resume continues where it stopped. Interrupted migrations resume automatically.
• The report lists every warning (data that couldn't map 1:1) and error (record not migrated) with its OpenCart ID.
• Keep the extension installed (or the bridge file on your server) until the migration and any Migrate changes runs are finished.
• Orders on Shopify development and trial stores are limited by Shopify to 5 per minute, so they migrate slowly there. Paid stores aren't limited.
• Shopify's temporary errors (server errors, timeouts) are retried automatically. When Shopify's answer to a create is lost, the app checks whether the record was created before trying again, so records are never duplicated. A record that still fails is reported; Resume or Migrate changes tries it again.
• Finished orders are archived: find them under Orders → Archived.

Migrate changes (updates)

Your OpenCart store keeps taking orders while you set up Shopify. With the Migration Update add-on, click Migrate changes on a completed migration to bring over what changed since the last run. Only changes are read, so it's fast even for large stores. The extension must still be installed (or the bridge file on your server). If you clicked Generate new key in OpenCart, paste the new connection code on the migration's page first; with the bridge file, upload the newly downloaded file if you regenerated its key.

• New orders, plus the current status of existing orders: marked paid, fulfilled, cancelled (without restocking) or refunded.
• New and edited products, and products whose stock changed through sales.
• Newly registered customers.
• Information pages, coupons and categories.

Nothing is duplicated, customers are never emailed, and inventory isn't restocked when an order is cancelled. Records you deleted in Shopify are not brought back for orders.

Go-live checklist

1. Review products (variants, prices, images, stock), collections, customers and a few orders.
2. Set up shipping rates, taxes and payment providers in Shopify Settings.
3. Choose and customise your theme; add menus (Online Store → Navigation).
4. Place a test order.
5. Shortly before switching, run Migrate changes to bring over the latest orders and customers.
6. Point your domain to Shopify (Settings → Domains). The 301 redirects created by the migration (Online Store → Navigation → URL redirects) start working once your domain points to Shopify.
7. Remove the store password, then invite customers to activate their accounts.
8. Uninstall the extension (or delete the bridge file) from your OpenCart store.

After migrating: uninstall the extension

Once you no longer need Migrate changes, remove the app's access to your OpenCart store:

1. In your OpenCart admin, go to Extensions → Extensions, choose Modules, and click Uninstall (the red −) next to GSP Shopify Migration. This deletes its key, so the connection code stops working immediately.
2. Optional: in Extensions → Installer, remove the files. On OpenCart 3.0.x, delete gsp-shopify-migration-oc3.ocmod.zip from the upload history; on OpenCart 4.x, click Uninstall and then Delete on the GSP Shopify Migration row. If you need the app again later, upload and install it again and paste the new code.

Bridge file: delete gsp-bridge.php from your OpenCart folder (FileZilla: right-click → Delete; cPanel File Manager: select → Delete). The app can then no longer read your store. If you need it again later, download a fresh copy from the app and upload it again.

Uninstalling the Shopify app also deletes your stored connection and key from our servers right away, so an old extension or bridge file left on your store stops working with the app. Removing it is still the safest option.

Troubleshooting

The Installer shows a permission error (directory not writable, or asks for FTP)

OpenCart's Installer needs to write to its system/storage folder (in particular system/storage/upload and system/storage/modification). Ask your host to make it writable by the web server (usually permissions 755 for folders and 644 for files, owned by the web user), or, if OpenCart asks for FTP details, enter them under System → Settings → Option → FTP and enable FTP. On OpenCart 4.x, system/storage/marketplace and the extension folder must be writable. If your host doesn't allow either, use the bridge file instead.

The upload worked, but GSP Shopify Migration isn't in the list

Uploaded extensions don't appear on the Installer page itself. Go to Extensions → Extensions and choose Modules in the “Choose the extension type” filter: it's listed there as GSP Shopify Migration. Click Install (the green +), then Edit. On OpenCart 4.x, first click Install (the green +) on its row in Extensions → Installer: until then it isn't listed under Modules. On OpenCart 3.0.x, if it's still missing, refresh the cache under Extensions → Modifications (the blue refresh button) and upload the zip again.

The module's page says “Permission Denied” (OpenCart 4.x)

The zip was renamed before uploading (for example to gsp_migration (1).ocmod.zip), and OpenCart 4 names the extension after the file. Uninstall the module in Extensions → Extensions → Modules, then uninstall and delete it in Extensions → Installer, and upload gsp_migration.ocmod.zip with its original name, then install it again.

“The connection code changed in OpenCart — paste the new code”

Someone clicked Generate new key on the module's page, or the extension was uninstalled and installed again, so the code saved in the app no longer works. Open Extensions → Extensions → Modules → GSP Shopify Migration → Edit, copy the current code, paste it under Connection code on the migration's page in the app (or on New migration), then click Resume.

“The GSP Shopify Migration extension is uploaded but not installed”

The zip was uploaded but the module wasn't installed, or it was uninstalled (which deletes its key). Install it under Extensions → Extensions → Modules, open Edit and paste the new code.

“Your store didn't answer like the GSP Shopify Migration extension”

Check that the module is installed, copy the whole connection code again, and make sure your store isn't behind a login or password protection. Firewalls can also block our requests (see the next item).

“We couldn't reach your-store.com”

Check the URL (with https://, and the folder if OpenCart isn't at the root) and that your store opens in a browser. Firewalls (e.g. Cloudflare bot protection, Imunify360, ModSecurity) can block our requests: allow-list the app or pause the protection while migrating.

“We couldn't find gsp-bridge.php at …”

The file isn't at that address. Upload it to the folder that contains OpenCart's config.php, then open the address shown in the message in your browser to check. If you put it elsewhere, enter its full address under Bridge file is somewhere else?.

“… didn't answer like the GSP bridge file”

Something else answered at that address: a “page not found” page, a redirect, a maintenance page or a login page. Check the bridge file URL, make sure the file still ends in .php (not .php.txt), and that your host runs PHP files in that folder.

“The bridge file on your server doesn't match this app”

The key in the uploaded file isn't your current key: the file came from a different download (another Shopify store, or before you clicked Regenerate key), or it was edited. Download it again, upload it to replace the old one, and test again.

“The bridge file on your server has no security key”

The file wasn't downloaded from the app (for example it was copied from somewhere else). Download it from step 1 of New migration and upload it again.

“… can't find OpenCart's config.php next to it”

The file was uploaded to the wrong folder. Move it to the folder that contains config.php (not the admin folder, and not a folder above your store), then update the bridge file URL if it changed.

“The bridge file couldn't read your OpenCart database”

The bridge found config.php but the database connection or a query failed. Check that your store itself works (open a product page), then try again. If it keeps happening, email us: the database may be overloaded or a table may be damaged.

“Your host is limiting requests right now”

Your hosting provider is rate-limiting requests. Wait a minute and try again; the migration retries by itself.

“Your store returned an error”

Your server answered with an unexpected error (for example a 500 or 503 page). Try again in a few minutes; if it persists, email us the message shown.

The migration stopped after it was working

With the extension: it was uninstalled or its key was regenerated. Install it again if needed, paste the current connection code on the migration's page and click Resume. With the bridge file: it was deleted or replaced, or your key was regenerated. Upload the current file from the app and click Resume.

Products show “Sold out”

The stock is at a location that doesn't fulfil online orders or isn't in a shipping profile. Check the location in Settings → Locations and add it in Settings → Shipping and delivery. If products are unavailable only to visitors from some countries, those countries aren't in any of your markets: add them in Settings → Markets.

Orders seem to be missing

Finished orders (complete, refunded, cancelled…) are archived, so they aren't under Orders → All: look in Orders → Archived. Orders with status 0 (“missing orders” in OpenCart) aren't migrated. On development stores, orders are created at 5 per minute, so they arrive slowly.

Prices are in the wrong currency

Prices are copied as numbers. Set your Shopify store currency to match OpenCart, then run the migration again.

Images are missing

Shopify couldn't download them from your site: check they open in a private browser window, and that hotlink or bot protection isn't blocking them. Then run Migrate changes or Resume.

“Phone … not accepted by Shopify”

The phone number isn't valid for Shopify. The customer is still migrated; the number is kept on the address.

FAQ

Will my OpenCart store be changed or go offline?

No. The extension (or bridge file) only reads from your database, and your store keeps working normally. The extension adds a module entry and one setting (its key), both removed when you uninstall it.

Which OpenCart versions are supported?

OpenCart 1.5, 2.x, 3.x and 4.x, including stores on older PHP versions: OpenCart 3.0.x and 4.x (4.0.x and 4.1.x) with our extension, 1.5 and 2.x with the bridge file. Popular forks that keep OpenCart's database layout usually work too; run a free preview to check.

Is it safe to install the extension (or upload the bridge file)?

Both are read-only, answers only requests signed with your secret key, and never reads passwords or payment settings. Uninstall the extension (or delete the file) when you're done.

Can I run the migration more than once?

Each store is fully migrated once. Use Migrate changes to bring over later updates; existing records are updated, never duplicated.

How long does it take?

It depends on store size and how fast your host responds: small stores take minutes, stores with tens of thousands of orders can take a few hours. You can close the page while it runs.

Will I lose my Google rankings?

No: meta titles and descriptions are migrated, SEO keywords become URL handles, and 301 redirects send old product, category and page URLs to the new ones.

Are customers emailed during the migration?

No. No order confirmations, shipping notifications or account invites are sent by the migration.

Why aren't my old orders under Orders → All?

Orders that are finished in OpenCart are archived, as Shopify does with finished orders. Find them under Orders → Archived (see Archived orders).

What happens to my data if I uninstall?

Everything migrated stays in your Shopify store. The app deletes your bridge key and store connection right away, and its migration history 48 hours after uninstall.

Privacy and security

A read-only extension or bridge file that never reads passwords or payment settings, requests signed with a key unique to your store, encrypted storage of your connection, and customer and order details transferred straight to Shopify without being stored by us. Read the full privacy policy and terms of service.

Contact support

Email contact@gsptechnologies.com with your Shopify store address and, if possible, a screenshot of the migration report. We reply within 2 business days.