Migrate to Vortex
Coming from another payments stack — what maps to what, and in which order.
Migrate to Vortex
You almost certainly have a payments stack already. This page maps its concepts onto Vortex and gives the order that lets you migrate incrementally instead of big-bang.
Coming from Stripe? One command
npx @vortexnyc/payments-migrate # dry run: prints the full plan
npx @vortexnyc/payments-migrate --apply # executes itIt reads STRIPE_SECRET_KEY and VORTEX_API_KEY from the environment and
moves customers, products, prices (recurring and one-time), active
subscriptions, and
coupons — every write keyed on the Stripe id, so re-running upserts and never
duplicates. Anything it cannot move (unsupported currency, canceled
subscriptions) is listed in the plan with its reason. Payment
methods and historical invoices deliberately stay put — see below.
Concept map
| You have today | Vortex equivalent |
|---|---|
| API keys per mode (test/live) | One key kind; environment lives on the key (vp_test_ / vp_live_) |
| Customers | Customers (PUT /v1/customers/{id} is an upsert — bring your own ids) |
| Products & prices | Catalog (/v1/catalog, products and prices) |
| Subscriptions | Subscriptions, with previewable item changes |
| Invoices | Invoices — draft, finalize, collect, void, uncollectible |
| Checkout sessions | Hosted checkout sessions |
| Payment element / drop-in | vortex.js + <VortexPaymentElement> (card entry never touches your DOM) |
| Webhook endpoints + signing secret | Webhook endpoints with signatures, retries, redrive, and replay |
| Connected accounts / sub-merchants | Merchant accounts with onboarding, capabilities, and readiness state |
| Idempotency keys | Idempotency-Key header, same semantics |
The order that works
- Stand up sandbox first. Signup at dashboard.vortex.nyc gives you a sandbox key in minutes; the whole surface is available immediately.
- Mirror your catalog. Products and prices are cheap to recreate and easy to verify by listing.
- Upsert customers with your existing ids. Customer upsert is keyed on your identifier, so there is no id-mapping table to maintain during the transition.
- Point webhooks at a parallel handler. Run the Vortex handler alongside your current one; events are signed and replayable, so you can verify parity before anything depends on it.
- Move new activity before old. Route new signups/charges through Vortex while existing subscriptions drain on the old stack, then migrate the remainder in batches.
- Stored payment credentials move last. Card credentials live in PCI-scoped vaults; moving them between providers is a standard, provider-to-provider transfer process that we coordinate with you rather than something you script yourself. Plan for it — do not let it block steps 1–5.
What we will not pretend
- There is no magical importer today. The API is upsert-friendly by design so migration scripts are short, but you (or we, together) still write them.
- If your dependency is a feature we deliberately do not have — see How Vortex compares — migrating to Vortex is the wrong move, and we would rather tell you now.