Migrating card tokens to NEXT

How migration works

Migrating card-on-file subscribers is a two-step process. First, the saved cards move into NEXT's payment vault. Then each customer's subscription record is re-created on NEXT and linked to the right vaulted card. Both steps have to happen, and they have to happen in order.

Before you start

You must initiate the export from your old processor

The stored cards belong to your payment account. Your old processor, for example Stripe, will reject a migration request that doesn't come from the account owner, so the export has to start with you. NEXT supports you through it but cannot make the request on your behalf.

NEXT coordinates the vault import

NEXT uses Spreedly as the backend vault provider for this import. Your NEXT contact opens the provider request, supplies the internal target vault details, and arranges the secure file transfer.

Export your subscription data separately

The vault import moves the cards only. Export each customer's plan, amount, currency, interval, and next renewal date from your old platform separately. You'll use them in Step 2.

Have an Admin API token ready

Step 2 calls the NEXT Admin API. Make sure you (or your technical team) have a valid Admin API token for the store before you begin.

Step 1 · Import saved cards into the NEXT payment vault

The first step transfers your stored cards into NEXT's payment vault through a coordinated one-time bulk import. It is not a self-serve API call. NEXT handles the provider workflow through Spreedly's Importing Vaulted Payment Methods process.

Step 2 · Re-create each subscription on NEXT

With the cards imported into the NEXT payment vault, re-create each subscription on NEXT using the Admin API Create Subscription endpoint, matching what the customer had on the old platform.

POST /api/admin/subscriptions/

Set payment_method to "card_token" and put the customer's imported provider token, the spreedly_token from the Step 1 map, in payment_details.card_token. Replace every placeholder below, including the future renewal date, before sending the request.

{
  "payment_method": "card_token",
  "payment_details": {
    "card_token": "<spreedly_token from the import map>"
  },
  "user": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "use_default_billing_address": true,
  "use_default_shipping_address": true,
  "currency": "USD",
  "lines": [
    {
      "product_id": 12345,
      "quantity": 1,
      "price": "39.00"
    }
  ],
  "shipping_code": "standard",
  "shipping_price": "5.00",
  "interval": "day",
  "interval_count": 30,
  "next_renewal_date": "<future-YYYY-MM-DDTHH:MM:SSZ>"
}

Repeat for each subscriber, mapping each customer to their spreedly_token. Use NEXT product IDs in the lines array, not product IDs from the old platform. If you don't use stored default addresses, pass full billing and shipping address objects instead of the use_default_* flags.

Critical ordering rule

Field reference

The key fields on the Create Subscription request:

Gotchas & FAQ

"Can NEXT request the export from Stripe for me?"

No. Your old processor only accepts an export request from the account owner, so you have to initiate it. NEXT then coordinates the vault import once you have the export file.

"My Create Subscription call returns an error about the token"

This usually means the token hasn't finished importing into the NEXT payment vault. Confirm the card appears in the Step 1 token map, then retry. See Critical ordering rule.

"Do customers need to re-enter their cards?"

Usually no. The goal of the migration is to keep saved cards usable for renewals without asking customers to type card details again. If a processor refuses export for specific cards, or if a record fails import, those customers may need to add a new payment method.

"How do I avoid double-charging customers?"

Pause or stop the matching recurring charge on your old platform as each subscription goes live on NEXT. Don't disable old billing wholesale before NEXT subscriptions exist, or renewals could lapse.

"Will expired cards still work after migration?"

Imported cards are enrolled in the vault provider's card updater where supported (eligible_for_card_updater), which can refresh expiries automatically over time. The original CVV does not migrate, but it isn't needed for renewals.

"How long does the whole thing take?"

Budget around two weeks for the vault provider to process the import, then the time to re-create subscriptions. Plan the cutover with your NEXT contact so external billing is paused at the right moment.