Troubleshooting EDD 3.x Migration Issues

Although most stores will migrate from EDD 2.11 to 3.x without issue, if you migrate your data and discover that some orders appear to be missing, there are tools to help with trouble shooting.

Before running any migration, make sure that your store data is backed up. It’s strongly recommended that you test the migration on a local or staging copy of your site before doing it in production.

If you conclude that some orders are missing from the new tables, the first step is to figure out which. You’ll need to be able to look directly at your database tables using PHPMyAdmin or a similar tool. Hopefully you have an idea of what orders might be missing, either by knowing the specific ID or by knowing an approximate date range.

The first step is to look in your wp_posts table for the missing payments (in EDD 2.x, we use payments terminology; in EDD 3.x, they’re now orders). The post_type will be edd_payment and you need to find the ID(s) for the payment(s) which did not successfully migrate.

Once you’ve noted a payment ID, the next step is to look in the wp_edd_orders table for an order with that same ID. If it doesn’t exist, then migrating the missing order is fairly straightforward; if it does exist, you may have a conflict. You’ll want to look carefully at the order and see what the type is. Usually, what will have happened is that a refund record will have been created with the next available ID and that prevented the original payment from being able to migrate. If the order type is refund then this is very manageable, because the ID of the refund doesn’t actually matter.

Migrating Orders with CLI

Once you know the ID for a missing order, you’ll need to run a partial order migration. It’s helpful to start with making sure you know what all of the original payment data is. You can use this CLI command to view it:

wp edd display_legacy_payment_data 1234

Replace 1234 with the original payment ID that you found in the posts table. This will display everything that EDD knows about the original payment. This can be helpful because the data is stored differently in EDD 3.x.

The default order migration command is just this:

wp edd migrate_payments

With no options, it will run through every payment object and migrate it, finishing with marking the order migration complete and then recalculating the sales/earnings for all downloads in the store. Once EDD has marked the order migration complete, you need to add some flags to run another migration; otherwise, EDD will not do it.

This command accepts multiple flags which will change the behavior:

• --force: This will force the migration to run again, even if it’s already been run. Existing orders will not be overwritten. A confirmation is required.
• --destroy: This will force the migration to run again, even if it’s already been run. Existing orders/order meta/order items/etc which match a payment ID will be deleted and the payment will be migrated again. A confirmation is required, because this is a destructive action.
  • This option is helpful when refund orders have been inserted into the orders table in the place of an existing payment ID. Refunds will automatically be regenerated with the next available ID in the orders table.
  • If the existing order is not a refund and appears to be a different order entirely from the one you are trying to migrate, an additional confirmation is required, as that’s likely destroying data which will not be able to be recovered.
• --id: This will run a partial migration on a specific payment ID (the ID in the WP posts table, which may be different from the displayed order number).
  • This flag cannot be used with the start/end flags.
  • It can be combined with force/destroy.
  • The order migration will not be marked complete.
• --start: This will run a partial migration beginning with (and including) a specific payment ID.
  • This flag can be used with or without the end flag.
  • This flag cannot be used with the id flag.
  • It can be combined with force/destroy.
  • The order migration will not be marked complete.
• --end: This will run a partial migration ending with (and including) a specific payment ID.
  • This flag can be used with or without the start flag.
  • This flag cannot be used with the id flag.
  • It can be combined with force/destroy.
  • The order migration will not be marked complete.

So if you want to test re-migrating an order, if you have confirmed that (this is most likely) the original payment has been “replaced” in the orders table by a refund, you can run this command:

wp edd migrate_payments --force --destroy --id=1234

Running this command will forcibly delete the order with an ID of 1234. Then it will migrate payment 1234 in its place. If the order 1234 was a refund, it will find the original order for that (let’s say it was order/payment 123), and then delete order 123 and run the migration for payment 123 again, which will regenerate the refund order object. The actual ID for any refund doesn’t mean anything so regenerating refunds is no big deal. Refunds are located by the parent column.

If You Downgraded to EDD 2.11 and Are Running the Migration Again

Because we can’t anticipate every scenario with integrations, EDD does allow stores to downgrade to EDD 2.11 and then come back to 3.x when ready. In these cases, we suggest that you empty the newly created tables and then run the migration as if it were the first time. You will likely need to use the CLI command to run the migration using --force since EDD may have already marked the migration complete.

Before emptying or deleting any database tables, make sure you have a full backup of your database. Practice a migration on a staging site before committing in production.

Here’s a list of tables that are newly created for EDD 3.x:

wp_customer_addresses
wp_customer_email_addresses
wp_adjustments
wp_adjustmentmeta
wp_notes
wp_notemeta
wp_orders
wp_ordermeta
wp_order_items
wp_order_itemmeta
wp_order_adjustments
wp_order_adjustmentmeta
wp_order_addresses
wp_order_transactions
wp_logs
wp_logmeta
wp_logs_api_requests
wp_logs_api_requestmeta
wp_logs_file_downloads
wp_logs_file_downloadmeta

The customers, customermeta, and notifications tables existed in EDD 2.x. Do not empty those. If you use an extension such as Commissions, Recurring Payments, or Software Licensing, those extensions also register custom tables with edd in the name and should not be emptied.

To migrate all store data, use this command (you may need to use the --force flag to allow it to run again):

wp edd v30_migration