Migration and rollout

Use this guide when customers already connect through another proxy stack and you need to move products, entitlements, and delivery to ProxyRequest. The goal is a controlled rollout, not a single irreversible cutover.

Prepare the migration inventory

Record the current state before changing customer traffic:

upstream contracts, endpoint formats, protocols, locations, and restrictions;
gateway hosts, ports, DNS, certificates, network limits, and capacity;
products, provider allocation, targeting, sessions, prices, expiry, and limits;
customers, usernames, active orders, remaining allowances, and account status;
integrations that create users, update balances, issue credentials, or consume usage data;
customer applications that contain the current proxy host, port, username, or password.

Do not copy provider passwords, API keys, proxy passwords, or webhook secrets into a migration document. Keep secrets in the system used to provision the corresponding ProxyRequest resources.

Define acceptance first

Decide which protocols, locations, session behavior, limits, analytics, and error cases must pass before a customer moves.

Keep a rollback path

Do not disable the old credentials or gateway until the migrated batch is stable and its usage has been reconciled.

Migration sequence

Connect supply and gateway capacity without changing customer traffic. Register the intended gateway footprint, add upstream providers, and validate each route independently. This step is non-disruptive because existing customers still use the old system. Follow infrastructure and launch for node, DNS, capacity, and production-readiness checks.
Recreate and test the products customers already use. Mirror the required provider allocation, targeting, protocols, session behavior, expiry, and limits. Product names do not prove equivalence: complete the package acceptance test for every product that will receive migrated traffic.
Create customers and transfer remaining allowances. Create the user and order records through the admin panel or API. At an agreed snapshot time, export the remaining allowance from the old system and write the equivalent integer-byte value to ProxyRequest. Preserve an existing username only when it satisfies the deployment’s username rules; issue a new proxy secret and store it securely. Review customers and accounting before transferring balances.
Move a small representative pilot. Start with customers that collectively exercise the protocols, locations, session patterns, traffic volume, and integrations used in production. A group of 5–10 customers is often enough for the first pass, but coverage matters more than the number. Update only their proxy host and credentials, then compare request results, analytics, and balance movement with the recorded baseline.
Roll out the remaining customers in controlled batches. Announce the credential change, define a support window, and move one labelled batch at a time. Keep the old path available until the batch passes connectivity, targeting, session, usage, and support checks. For a headless deployment, update the mapped customer and entitlement records before issuing access from your existing product.
Decommission the old system only after reconciliation. Confirm that every active customer has moved, no old credentials are still in use, transferred balances match the agreed snapshot, and the new dashboards and alerts cover normal operations. Revoke old secrets and remove old infrastructure through the former platform’s normal shutdown process.

Transfer balances without creating ambiguity

Choose and record a balance snapshot timestamp for each batch.
Stop purchases or balance changes on the old system for that customer during the transfer window.
Export the remaining allowance and its unit.
Convert it once to integer bytes using the deployment’s agreed decimal GB or binary GiB convention.
Create or update the ProxyRequest order, then record both resource IDs in the migration log.
Send a controlled request and confirm that the first aggregated debit appears against the expected customer and order.

Usage is recorded in batches, so the visible balance does not change after every packet and a final batch can cross the exact byte boundary. Reconcile with closed analytics windows instead of treating an open interval as final. See usage accounting for the ledger model.

Acceptance and rollback checklist

Area	Accept the batch when	Roll back or pause when
Connectivity	Required HTTP or SOCKS behavior succeeds through the new gateway	A required protocol or customer network cannot connect
Targeting	Requested locations resolve within the package’s configured scope	Results broaden or fail outside the documented package behavior
Sessions	Sticky and rotating behavior matches the tested product configuration	Session continuity changes for a customer-critical workflow
Accounting	Requests appear under the expected user, order, package, and allowance	Usage is unattributed, duplicated, or mapped to the wrong ledger
Capacity	Gateway and provider health remain within the deployment’s operating thresholds	Error rate, latency, connection count, or egress approaches an unsafe limit
Support	Customers can apply the credential change and reproduce the validated request	The batch generates unresolved configuration or product-compatibility issues

Rollback means directing the affected customer back to the still-live old host and credentials, preserving evidence from the failed attempt, and correcting the ProxyRequest configuration before retrying. Do not delete the new records: keep their identifiers for audit and reconciliation.

Common migration questions

Will customers experience downtime?

A parallel rollout does not require a platform-wide outage. Each customer must still apply the new host or credentials, so schedule that configuration change and keep the previous path available until the new request succeeds.

Can existing usernames be preserved?

Often, but only if they satisfy the destination deployment’s validation and do not conflict with another account. Proxy secrets should be newly issued rather than copied from the old platform.

What happens to remaining customer balances?

Transfer the remaining allowance from an agreed snapshot, record the source and destination values, and reconcile the first usage interval. Do not infer the balance from an open analytics window.

What changes in a headless deployment?

Your customer, payment, and subscription records remain authoritative. Create and store the corresponding ProxyRequest user, package, and order mappings, then provision access through those IDs. Follow the hybrid and headless guide for the complete mapping model.

If you want to review the rollout sequence with the team maintaining the routing and infrastructure stack, book a technical demo.