Migrations

Migrate active WooCommerce subscriptions to a new payment gateway without breaking billing

A scenario for switching payment processors on a live subscription store where every customer's stored card is tied to the old gateway's tokens.

Works with Claude / GPT245 uses 4.2

The prompt

migrations-subscription-payment-gateway-switch
A WooCommerce store with 800 active subscribers is switching from [Stripe] to [a new
payment processor] for lower transaction fees, but every existing subscriber has a
stored card and an active recurring billing schedule tied to the old gateway's
customer and payment method IDs.

CURRENT SETUP: [WooCommerce Subscriptions plugin, Stripe gateway, 800 active
subscriptions across 3 pricing tiers, next renewal dates spread across the whole
month]
CONSTRAINT: [no subscriber should be asked to re-enter their card manually unless
absolutely necessary, and no renewal should be missed or double-charged during the
switch]

Plan this the way a WooCommerce subscriptions specialist would, since a naive gateway
swap breaks every stored payment method at once:
1. Determine whether the new gateway accepts a payment method migration path (some
   processors offer a token migration API or can import the old gateway's tokens
   directly). State what happens to renewals for any subscriber whose card can't be
   migrated this way, since they're the real risk group, not the ones who migrate
   cleanly.
2. Decide the cutover strategy: a hard cutover on one date versus a rolling migration
   where each subscriber moves at their next natural renewal. Recommend one given the
   constraint that no renewal should be missed, and explain the tradeoff the other
   option would introduce.
3. For subscribers who can't be migrated automatically, write the email asking them to
   re-enter payment details, timed early enough before their renewal date that a
   failed card has time to be retried before the subscription lapses.
4. Specify how to prevent double-billing during the transition window, such as a
   subscriber whose renewal fires on both the old and new gateway on the same day due
   to a scheduling overlap.
5. List what to verify after the first batch of renewals processes on the new gateway,
   before migrating the rest, so a systemic problem is caught on 10 subscribers
   instead of 800.

Replace the gateway names, subscriber count, and constraint with your own situation.

Card-on-file migrations are the riskiest part of any subscription business changing payment processors. A failed migration doesn’t just annoy a customer, it silently stops revenue on a schedule nobody’s actively watching. Test the rolling migration on a small, low-value batch of subscriptions before touching the highest-tier customers.