Migrating subscribers to WooCommerce Subscriptions is not the same as importing customer accounts. An active subscription can depend on a customer, product, payment gateway, parent order and renewal orders, as well as a billing schedule and recurring totals. If only user records are moved, the destination store may lack the information needed to calculate or process future renewals correctly.
A controlled migration therefore starts with an inventory of linked data, continues through field mapping and staged testing, and ends with deliberate renewal verification. The choice between manual entry and CSV import depends on subscriber volume, data consistency and gateway requirements. Payment metadata is especially important: without valid gateway-specific references, automatic renewal continuity cannot be assumed.
Why WooCommerce Subscriptions Migration Is More Than a Customer Import
WooCommerce Subscriptions connects each subscription to several records. The migration plan must preserve the relationships between the customer, destination product, subscription, payment gateway and relevant orders. These links affect who is billed, what is charged, when the next payment is due and where the transaction should be processed.
The objects that must be mapped
Begin by creating an inventory of active subscribers and their associated records. For each subscription, identify the destination customer account, product and line items. Record the subscription status, recurring price, taxes and calculated totals. Also determine whether the parent order should be recreated and whether historical renewal orders are required for the store’s records or workflow.
Keep subscription information separate from payment credentials. A gateway may use a customer reference or payment token, but those values must be handled according to the destination gateway’s requirements. Do not assume that importing customer records alone preserves renewal behavior. Do not activate imported subscriptions until linked customers, products, schedules, totals and gateway metadata have been checked.
Pre-Migration Data Checklist
Prepare the source data before choosing an import method. The destination store needs matching customer identifiers, billing and shipping details, product associations, subscription status and recurring billing information. Each source record should be mapped to an exact destination user and product rather than matched informally during the live operation.
The preparation should cover:
- Customer identifiers, billing addresses and shipping addresses.
- Subscription status and the relevant parent-order information.
- Products, line items, quantities, recurring prices, shipping and fees.
- Recurring taxes and calculated totals.
- Billing interval and period, start date and next payment date.
- Optional trial dates and end dates.
- Historical renewal orders where they are needed.
- Gateway-specific customer references or payment tokens.
Create a complete backup and test the migration on a staging environment before changing production subscriptions. Do not export, paste or store raw card numbers, CVV values or other sensitive payment credentials in CSV files or WordPress tables.
Subscription schedule and commercial values
The billing schedule controls the timing and amount of future renewals. Check the recurring interval and period for every subscription. Compare the source start date with the destination start date, then verify the next payment date. Review any trial or end dates so that the imported schedule does not unintentionally charge too early, too late or beyond the intended subscription period.
Recurring commercial values also need an individual check. Compare line items, recurring prices, shipping, fees, recurring taxes and calculated totals with the source records. A subscription should remain inactive until these values have been reviewed and the destination product association has been confirmed.
Customer, product and order matching
Match customer identifiers and addresses to existing destination accounts. Then map every line item to the correct destination product and recurring pricing data. If products differ between the source and destination stores, document the mapping rather than relying on similar names.
Decide in advance whether the migration includes parent orders, historical renewal orders or both. The right scope depends on the store’s records and workflow, so it should be documented before import. This makes it easier to compare the imported result with the source inventory and identify incomplete rows.
Manual Import vs. CSV Import
Manual entry is often clearer when the migration is small, irregular or requires close inspection of every subscription. WooCommerce documentation recommends considering manual entry for fewer than 100 subscribers, but this is not a universal technical limit. Source-data quality and gateway complexity can matter more than the number of records.
When manual entry is the clearer option
For a smaller subscriber set, create each subscription individually and check the customer, billing schedule, line items, recurring taxes and calculated totals during the process. Manual entry also suits records that do not share a consistent structure or require decisions about missing information.
Record the outcome of each manually created subscription. Before activation, confirm the subscription status, next payment date, product association and gateway information. This approach takes more administrator time, but it provides a direct review point for every record and can expose mismatches before they affect renewals.
When a CSV workflow is appropriate
CSV import is more suitable for larger batches when the source data is consistently structured and can be mapped reliably to the importer’s documented fields. A batch workflow still requires test mode, live-import logging and row-by-row review. Passing a basic format check does not by itself make a CSV import safe.
Consider custom migration work when the source data is non-standard or the gateway requirements cannot be represented by the available importer workflow. For custom scripts or non-standard gateways, require specialist review and define the validation scope before production changes are made.
How to Build and Validate the Migration File
Build the migration file from a documented field-mapping plan. Use the importer’s documented column structure, field names and valid date formats. Map source customer identifiers, products, subscription status, billing data and gateway metadata to the exact destination records. Keep a separate mapping record so that each imported row can later be compared with its source.
From field mapping to test mode
Check identifiers, products, dates, statuses and recurring values before uploading the file. Confirm that date fields represent the intended start and next payment dates, and verify that optional trial or end dates are not missing or incorrectly formatted. Review recurring prices, taxes and totals against the source data.
Run the importer in test mode before creating production records. Test mode validates rows without creating users or subscriptions, which makes it useful for finding formatting and mapping issues early. However, test mode cannot detect every error that may occur during a live import, so it must not be presented as a guarantee.
Live-import review
After the live import, review the completion tables and error logs. Investigate failed or incomplete rows individually instead of assuming that a mostly successful batch is complete. Compare imported customers, products, schedules, statuses, dates, recurring values and gateway references with the source mapping.
Keep import files and logs controlled because they may contain customer and subscription information. Do not consider the migration complete until live-import results and logs have been reviewed. Imported subscriptions should remain inactive while this comparison is being performed.
Payment Gateway and Recurring Payment Risks
Payment gateway details determine whether an imported subscription can renew automatically. The destination gateway must support the relevant administrator payment-method change process, and the migration must provide valid gateway-specific metadata. This commonly means a customer reference or payment token rather than raw card details.
What must be confirmed with the destination gateway
Confirm whether the destination gateway supports administrator payment-method changes for subscriptions. Check the accepted format for customer references or payment tokens and verify how the destination extension expects that metadata to be associated with the subscription.
Gateway metadata names, storage locations and transfer procedures can differ between extensions. Changing merchant accounts or moving between gateway extensions may introduce additional requirements. Verify these details with the payment provider or extension vendor before production migration, rather than assuming that metadata from one system can be copied directly into another.
PayPal Standard subscriptions generally cannot be migrated into WooCommerce Subscriptions because of limitations involving recurring-payment notifications and IPN handling. PayPal Billing Agreements with Reference Transactions are a distinct case and should not be treated as equivalent to PayPal Standard. This is a gateway-specific limitation, not a universal rule for all PayPal products.
Fallbacks when payment metadata cannot move
If valid payment metadata is unavailable, automatic renewal continuity cannot be assumed. Possible operational alternatives include manual renewals, a customer-driven payment-method update where supported, or a carefully controlled failed-renewal workflow. Select the approach only after checking the destination gateway’s behavior and the store’s customer-communication process.
Never treat raw card details as a migration solution or place them in CSV files or WordPress tables. Do not promise uninterrupted automatic renewals when payment metadata cannot be transferred. A fallback plan should state who monitors renewals, how customers are contacted and how failed payments are handled.
Post-Migration Renewal Verification and Specialist Support
Go-live should be a documented release process rather than the moment a file finishes importing. Keep the imported subscriptions inactive until customer links, products, statuses, dates, recurring totals and gateway metadata have been checked. Then verify that next payment dates and renewal orders are scheduled as intended.
The go-live checklist
- Complete the migration on staging and compare the result with the source inventory.
- Review live-import tables and logs row by row.
- Check customer and product matches, subscription statuses, billing schedules, next payment dates and recurring totals.
- Confirm gateway references or payment tokens use the required destination format.
- Activate subscriptions only after the documented checks are complete.
- Monitor failed payments and customer notifications during the first renewal cycle.
Avoid running two systems that could both attempt to charge the same subscriber. Keep the old renewal system available only within a deliberately planned transition. Configure customer communication and retry behavior deliberately for failed renewals, and maintain a tested rollback or customer-remediation plan before production changes.
When specialist help is justified
Consider a qualified migration specialist when the source data is non-standard, custom scripts are required, the gateway is unsupported or merchant-account details are changing. Ask for a staging test and a defined validation scope. The person handling the work should understand the distinction between gateway metadata and raw payment credentials.
Specialist assistance is also appropriate when the migration involves complex subscriber sets or uncertain historical-order requirements. WooCommerce documentation identifies limitations around incorrectly formatted CSV migrations, broken renewals caused by importers and custom import scripts. Testing reduces operational risk, but it cannot guarantee that every renewal will succeed because gateway behavior and source data structures vary.
Subscriber migration is a linked-data and payment-gateway project, not a simple account import. Start with an inventory, map customers, products, schedules, orders and gateway references, then test on staging before making production changes. Choose manual entry for smaller or irregular migrations and CSV for structured batches that can be validated. Review logs and records row by row, activate only after checks are complete, and monitor the first renewal cycle deliberately. Where payment metadata cannot move, plan customer updates or manual renewals instead of assuming continuity. Explore our WordPress plugins, WooCommerce extensions, themes and membership plans to find the right tools for your website.