The SaaS Integration Migration Playbook & CS Decision Matrix

Migrating enterprise customers off legacy integration tools to new infrastructure is one of the highest-risk operations a B2B SaaS company can undertake. Whether you are moving users from a brittle visual workflow builder, swapping out an older unified API provider, or deprecating an in-house connector, the implicit requirement is always the same: do not break the customer's workflow, and absolutely do not force them to re-authenticate their third-party accounts.

When a SaaS platform switches backend integration providers, the default path usually involves emailing customers and asking them to click a "Reconnect" button. For enterprise accounts, this is a catastrophic failure of customer experience. It triggers security reviews, breaks automated syncs mid-quarter, hands procurement a reason to revisit your contract, and opens the door for churn.

Much like our integration rollout playbook for product managers, this playbook provides a highly structured operational framework for Customer Success (CS) and Product Management (PM) teams to safely migrate enterprise customers to native integrations. We will cover how to audit existing setups, categorize migration paths using a decision matrix, map data schemas without writing custom code, and execute a zero-downtime cutover.

The Hidden Churn Risk of Integration Migrations

Migrations look like an engineering project on paper. In reality, they are a retention exercise dressed up in YAML. Integration readiness is a primary driver of net revenue retention (NRR), and forcing customers to rebuild workflows actively destroys that retention.

The data behind onboarding friction is brutal. Industry research on SaaS churn consistently shows that the first 90 days after any major workflow change behave like a second onboarding. Roughly 70% of users who churn early do so because of broken setup flows or workflow mismatches. A re-authentication prompt sent to a customer's IT admin in week one of a migration is functionally identical to a failed onboarding. The integration was working on Friday. On Monday it asks for credentials. The customer's trust budget gets spent before you have done anything useful.

The stakes scale with deal size. Enterprise SaaS contracts sit at roughly 1-2% annual churn, while SMB tiers regularly burn through 3-7% monthly. That gap is the entire business case for a careful migration. A single Fortune 500 logo lost to a botched Salesforce re-auth can wipe out a quarter's worth of new SMB bookings.

Migration friction also kills expansion deals at the procurement stage. Jason Lemkin of SaaStr famously noted a scenario where a $7,500 migration fee stopped an $80,000 per year deal cold. The cost wasn't just financial; it was the operational tax placed on the buyer's internal IT team to facilitate the move. Buyers do not separate "the integration vendor's migration" from "your product's migration."

Conversely, top B2B SaaS firms achieve NRR above 120% by ensuring smooth transitions and driving deep product adoption. Integrations are the stickiest feature in the product. When you switch backend integration providers without causing customer downtime, you protect your NRR while upgrading your infrastructure. A well-run migration is not damage control. It is a wedge to deepen the relationship.

If your platform currently relies on visual workflow builders for multi-tenant data sync, you are sitting on a technical liability. Migrating from Make.com prototypes to native SaaS integrations requires extracting those workflows into a controlled, code-thin integration layer inside your product. To do this safely, CS teams need a rigid evaluation framework.

How to Avoid Vendor Lock-In with Unified API Providers

Every integration migration exists because of a prior lock-in failure. You picked a provider, built on their abstractions, and now switching costs more than staying. The next provider you choose should not repeat that pattern.

Vendor lock-in with unified API providers is not a hypothetical risk. It is the structural default. Most providers are designed so that leaving is painful, even if that design is not intentional. The lock-in happens through three specific vectors, and each one is preventable if you catch it before signing.

1. OAuth App Ownership Lock-In

When your integration provider forces customers to authenticate through the provider's shared OAuth application, every refresh token is cryptographically tied to their client ID. Switching providers means asking every customer to re-authenticate - the exact churn event described above.

The fix: own your OAuth applications. Register your own OAuth client IDs with Salesforce, HubSpot, and every other provider you integrate with. When you control the OAuth app, refresh tokens belong to you. Any backend provider can use them. This single decision determines whether your migration is invisible or catastrophic.

2. Proprietary Configuration Lock-In

Some providers encode integration logic in proprietary formats, internal DSLs, or vendor-specific configuration schemas that have no export path. If you cannot export your field mappings, transformation rules, and sync configurations in a standard, portable format - JSON, YAML, JSONata expressions - you are building on sand.

The fix: use providers whose integration configurations are declarative and exportable. JSON-based API configs and standard mapping expressions are portable by definition. If your provider uses a proprietary visual builder with no export path, treat that as a lock-in risk equal to a long-term contract.

3. Data and Credential Export Lock-In

Can you bulk-export your active OAuth tokens, refresh tokens, connected account metadata, and sync state at any time? If the answer is no, or if the provider's terms of service restrict data portability, you are locked in regardless of the technical architecture.

The fix: before signing with any integration provider, get written confirmation that you can bulk-export all connection metadata, tokens, and configuration. This should be a contractual guarantee, not a feature request. As data portability experts recommend, your vendor contract should explicitly "define the format in which the vendor must provide your data" and "define timelines and costs for data export."

The Vendor Lock-In Evaluation Checklist

Before selecting or renewing with a unified API provider, score them against these criteria:

If your current provider scores "High Lock-In Risk" on three or more criteria, this playbook is your exit plan. If you are evaluating new providers, use this checklist as a procurement gate before signing.

The Customer Success Integration Decision Matrix

Not all customers require the same level of hand-holding during an integration migration. Treating a 12-seat SMB account syncing three standard fields the same as a 4,000-seat enterprise account syncing 40 custom objects wastes engineering cycles and delays the rollout.

To standardize the process, PMs and CS leaders must use an Integration Decision Matrix. This framework evaluates accounts on two axes: Technical Complexity (number of custom fields, endpoint variations, bidirectional sync requirements) and Business Value (ARR, MRR, expansion potential, strategic logo status).

The CS Integration Decision Matrix Tiers:

• Tier 1: Automated Cutover (Low Value, Low Complexity) - Standard data models. No custom objects. One-way sync. The migration happens entirely in the background via infrastructure routing. Self-serve automated email sequence.
• Tier 2: Guided Migration (Medium Value, Medium Complexity) - Minor custom field mapping required (5-15 custom fields), light bidirectional sync. CS provides a pre-configured mapping template for the customer to approve before the backend cutover.
• Tier 3: White-Glove Migration (High Value, High Complexity) - Heavy reliance on custom objects, multi-system sync, compliance scope, non-standard API endpoints, or massive historical data backfills. Requires an executive sponsor, dedicated CSM, and Sales Engineering resources.

Mapping the Matrix to Action

flowchart TD
    A[Customer flagged for migration] --> B{ARR tier?}
    B -->|< $25K| C{Complexity?}
    B -->|$25K - $100K| D{Complexity?}
    B -->|$100K+| E[Assign migration squad]
    C -->|Low| F[Automated self-serve<br>email sequence]
    C -->|Med/High| G[Templated guided flow<br>CSM async support]
    D -->|Low| H[CSM-led<br>30-min cutover call]
    D -->|Med/High| I[Solutions engineer<br>+ schema review]
    E --> J[Pre-migration audit<br>+ dual-run cutover]
    J --> K[Post-cutover monitoring<br>14-day stabilization]

The matrix gives CS leaders a defensible way to allocate scarce specialist hours. It also forces an honest conversation with sales: not every customer earns a dedicated migration engineer, and that is fine as long as the self-serve path actually works.

A quick gut check on which bucket a customer falls into: open their existing Zapier or legacy unified API account and count the active scenarios, the custom field mappings, and the number of distinct endpoints touched. If any of those numbers exceeds 10, treat it as Medium complexity at minimum.

Migration Artifacts: Templates, Checklists, and Runbooks

Operational detail only works when it lives in artifacts your team actually uses during execution. Below are the core migration documents every CS, PM, and engineering team needs before moving a single account. Copy them, adapt the fields to your product, and assign owners before kicking off Phase 1.

Two-Page Exit Migration Plan Template

This is the executive-facing document that gets sign-off from leadership before work begins. Keep it to two pages. Anything longer will not be read.

Page 1: Scope and Timeline

Page 2: Risk Register and Escalation Path

Pre-Migration Inventory Spreadsheet

Every account in scope needs a row in this spreadsheet before migration begins. Export the data from your legacy provider's admin console or API. This captures the output of the audit checklist in Phase 1 below - fill it in as you work through each account.

Sort by ARR descending. Start auditing from the top.

Token and Connection Metadata Export Checklist

This checklist covers every piece of data you need to extract from the legacy provider to achieve a zero-downtime cutover. Work through it per account.

• OAuth refresh token - The active refresh token for the connected account. Verify it has not expired.
• OAuth access token (if available) - The current access token. Useful for immediate validation but will expire.
• OAuth client ID - Confirm this matches your owned OAuth app, not the legacy vendor's app.
• OAuth scopes granted - The exact permission scopes the user authorized. The new platform must request the same set or a subset.
• Token expiry metadata - When the refresh token was last used, its TTL, and the provider's refresh token rotation policy.
• Connected account identifier - The external user/account ID in the third-party system (e.g., Salesforce Org ID, HubSpot Portal ID).
• Instance URL or tenant URL - For multi-tenant providers like Salesforce or ServiceNow, the specific instance URL.
• API version - Which API version the legacy integration was calling (e.g., Salesforce v58.0 vs v61.0).
• Webhook subscription IDs - Active webhook registrations with the third-party provider, including their callback URLs.
• Custom field mappings - Export the complete mapping configuration as JSON or CSV.
• Sync cursor or checkpoint - The last sync position (cursor, timestamp, or page token) to allow the new platform to resume without re-syncing all historical data.
• Rate limit baseline - Average and peak API calls per hour over the last 30 days.

Customer Communication Templates

Communication during a migration serves one purpose: prevent the customer from having to do anything. The best migration email is the one you never send because nothing changed from the customer's perspective. When you do need to communicate, use these templates.

Template 1: Pre-Migration Notification (Tier 2 and 3 only)

Subject: Upcoming infrastructure upgrade - no action required

Hi [Name],

We are upgrading the backend infrastructure for your [Salesforce/HubSpot/etc.] integration during the week of [date]. This is a behind-the-scenes change to improve reliability and performance.

No action is required from you or your team. Your existing connection, data mappings, and sync schedules will continue to work without interruption.

Your CSM [CSM Name] will confirm once the upgrade is complete. If you have questions, reply to this email.

Template 2: Post-Migration Confirmation

Subject: Infrastructure upgrade complete

Hi [Name],

The backend upgrade for your [integration] is now complete. All syncs are running normally.

We have been monitoring your integration closely over the past [X] days and everything is operating within expected parameters. No changes to your workflow or configuration were needed.

If you notice anything unexpected, reach out to [CSM Name] directly at [email].

Template 3: Re-Authentication Required (last resort)

Subject: Action required - please reconnect your [integration] by [date]

Hi [Name],

Due to a change in our integration infrastructure, we need you to reconnect your [Salesforce/HubSpot/etc.] account. This is a one-time action that takes approximately 2 minutes.

What to do:

1. Log into [Your Product] at [URL]
2. Navigate to Settings → Integrations → [Integration Name]
3. Click "Reconnect"
4. Authorize access when prompted by [Provider]

Deadline: Please complete this by [date]. Your sync will continue using cached credentials until then, but will stop functioning after this date.

If your organization requires IT approval for OAuth grants, please forward this email to your IT admin with the following details:

• OAuth App Name: [Your App Name]
• Client ID: [Your Client ID]
• Scopes requested: [List of scopes]

Your CSM [CSM Name] is available for a call if your team needs walkthrough support.

Cutover, Monitoring, and Rollback Runbook

This is the step-by-step runbook for execution day. Print it. Assign every step an owner. Do not improvise.

Pre-Cutover (T-24 hours)

Cutover (T-0)

Post-Cutover (T+1 to T+14)

Rollback Trigger Criteria

Initiate rollback if any of these conditions occur during cutover:

• Error rate exceeds 1% for any single provider for more than 10 minutes
• Any Tier 3 account reports data loss or duplicate records
• OAuth refresh failures affect more than 5 accounts simultaneously
• Webhook delivery success drops below 95% across all accounts

Rollback Procedure

Phase 1: Pre-Migration Audit and Schema Mapping

Before moving a single byte of data, CS and Sales Engineering must audit the customer's existing setup. This is where most migrations quietly fail. Teams assume the old system was doing what the contract said. It was not. If the customer is migrating off a legacy unified API or a visual workflow builder, you need a complete inventory of exactly what data shapes they expect your application to ingest.

The Audit Checklist for Every Account

The audit phase identifies the delta between the old integration's output and your new native integration's output.

1. Active scenarios or flows: Review flows in the legacy tool, with last-run timestamps. Anything that has not run in 60 days is dead weight - flag for archival, do not migrate.
2. Field-level mappings: Document the mappings between the third-party app (Salesforce, HubSpot, NetSuite) and your product. Export these as a CSV. You will reference it three times before cutover.
3. Custom objects and custom fields: Identify every non-standard field the customer added on their side. These are the migration killers.
4. Webhook subscriptions and downstream consumers: If a legacy flow fires a webhook to a Slack channel, that consumer must keep receiving events after cutover. Determine the frequency and payload size of incoming events to provision adequate rate limit handling.
5. OAuth scopes: Document scopes currently granted. The new system must request the same scope set or narrower. Asking for new scopes triggers a re-consent flow, which is the re-authentication event you are trying to avoid.
6. Rate limit headroom: Pull the customer's recent API call volume from the legacy tool's logs. A surprise migration that doubles call volume on the same API key gets you 429'd into the ground.

Declarative Schema Mapping (Zero Integration-Specific Code)

Historically, mapping old data structures to a new schema required writing brittle integration code. Engineers would write translation layers in Node.js or Python to morph the old payload into the new format.

Modern architectures eliminate this entirely through Zero Integration-Specific Code. Instead of writing runtime logic, migrations are handled via declarative JSON configurations and JSONata mappings. A field rename, a type coercion, or a nested object flattening becomes a one-line expression rather than a new backend deployment.

{
  "contact": {
    "first_name": "$.FirstName",
    "last_name": "$.LastName",
    "email": "$.Email",
    "custom_fields": {
      "customer_tier__c": "$.Customer_Tier__c",
      "renewal_date__c": "$.Renewal_Date__c ? $toMillis($.Renewal_Date__c) : null"
    }
  }
}

By defining the transformation in JSONata, the platform evaluates the mapping at runtime. This turns integration maintenance into a data-only operation. The goal is to produce an output payload that matches what your frontend and backend code already consume from the legacy provider. If your application code never has to change, the migration risk drops by an order of magnitude.

Phase 2: The Zero-Downtime Cutover Strategy

The most critical phase of the migration is the actual cutover. The goal is to switch the underlying integration infrastructure without the customer noticing. Two technical decisions determine whether it is invisible or catastrophic: who owns the OAuth application, and whether you can dual-run integrations during the transition.

The "Bring Your Own OAuth App" Requirement

The primary reason migrations cause churn is the "Re-Authentication Cliff." When a customer originally clicked "Connect to Salesforce" inside your product, they granted access to a specific OAuth client. Legacy unified API aggregators often force customers to authenticate through the vendor's shared OAuth application.

If that OAuth client belongs to your legacy integration vendor, switching to a new vendor means asking every customer to re-authenticate against the new vendor's OAuth app. There is no shortcut. The refresh token is cryptographically tied to the client ID that issued it. You lose the OAuth tokens, and your customers must log back in to grant access to your new infrastructure.

To achieve zero-downtime, you must own your OAuth clients. When you own your OAuth app, the authorization grant belongs to your company, not your integration vendor.

If you own the OAuth app, the cutover strategy is straightforward:

1. Export the active refresh tokens from your legacy provider.
2. Import the refresh tokens into your new integration platform.
3. The new platform uses the existing refresh token to generate a fresh access token.
4. The end-user remains completely unaware that the backend infrastructure changed.

When evaluating a new integration platform, the question to ask is direct: "Can I bring my own OAuth client ID and secret, and will you store and refresh my tokens against my app?" If the answer is no, the migration cost is the price of every enterprise customer's IT admin time.

The Dual-Run Architecture and Sequence

For Tier 3 (White-Glove) customers, engineering should implement a dual-run architecture during the cutover window. Dual-running means both the old and new integration backends are live for the same customer for a bounded window.

sequenceDiagram
    participant SaaS as Your SaaS App
    participant Old as Legacy Provider
    participant New as New Native Integration
    participant 3rdParty as 3rd Party API

    Note over SaaS,3rdParty: Phase 1: Dual Read, Single Write (Old)
    SaaS->>Old: Write Data
    SaaS->>New: Shadow Write (Log results, do not execute)
    Old->>3rdParty: Execute Write
    
    Note over SaaS,3rdParty: Phase 2: Cutover
    SaaS->>New: Write Data
    New->>3rdParty: Execute Write
    SaaS-->>Old: Deprecate

During the shadow phase, your application sends API requests to both the legacy provider and the new infrastructure. The new infrastructure logs the request and validates the JSONata mapping but does not actually execute the HTTP request against the third-party API. Once CS validates that the shadowed payloads match the expected schema, you flip the routing switch.

Concrete dual-run sequence:

1. T-14 days: Provision the customer in the new platform. Sync historical data and verify checksums against the legacy system.
2. T-7 days: Enable read traffic on the new platform behind a feature flag. Mirror the read response to a logging pipeline and diff it against legacy responses. Anything that differs is a mapping bug.
3. T-1 day: Notify the CSM and the customer's primary admin. Not an action item for them - just a heads-up.
4. T-0: Flip writes to the new platform. Keep the legacy system in read-only fallback mode.
5. T+7 days: Disable legacy reads.
6. T+14 days: Revoke legacy credentials.

Phase 3: Handling Custom Fields and Edge Cases

Standard data models handle 80% of integration use cases. The remaining 20% - custom fields, proprietary objects, and undocumented endpoints that the legacy tool was secretly supporting - are where migrations typically fail.

When migrating an enterprise customer, you will inevitably discover that their legacy setup relied on a highly specific custom object in Salesforce or a uniquely formatted custom field in NetSuite.

The 3-Level Config Override Hierarchy

To handle these edge cases without branching your codebase, your architecture must support a 3-Level Configuration Override Hierarchy. This allows CS teams to map custom fields at different granularities, in increasing specificity:

1. Platform Level Defaults: The baseline unified schema applied to all customers (e.g., a standard CRM Contact object).
2. Environment Level Overrides: Overrides applied to specific deployment environments (e.g., your staging product treats lead_source as a required field, while production does not).
3. Account Level Overrides: Highly specific per-customer mappings for a single enterprise tenant.

If "Enterprise Corp" needs their custom industry_vertical_c field mapped to your unified industry field, or they renamed Email to Primary_Contact_Email__c and added six custom fields nobody else has, CS applies an Account-Level JSONata override. This completely isolates the custom logic to that specific tenant. When the platform processes a request for Enterprise Corp, it merges the Account-Level config over the Platform-Level config at runtime.

Proxy API Fallback for Undocumented Endpoints

Sometimes, a customer's legacy workflow relies on an obscure third-party endpoint, a custom Apex endpoint, a legacy SOAP envelope, or a private beta API that does not fit into any unified data model.

Instead of blocking the migration or forcing engineering to build a custom connector, use a Proxy API Fallback. A Proxy API provides raw, authenticated passthrough access to the underlying provider. Your application makes a request to the Proxy API, which injects the correct OAuth access token and forwards the exact request to the third-party system.

# Proxy passthrough to a custom Salesforce endpoint
curl -X GET "https://api.example.com/proxy/salesforce/services/apexrest/CustomRenewalCheck" \
  -H "Authorization: Bearer $TRUTO_TOKEN" \
  -H "x-integrated-account-id: $ACCOUNT_ID"

This guarantees that you never have to say "no" to a migration because of a missing endpoint in the unified schema. You map 95% of the surface to the unified schema and use proxy passthrough for the rest, all under the same auth and observability layer.

Example End-to-End Migration Timeline: 200 and 1,000 Accounts

The phases above describe what to do. This section shows when to do it and who owns each step, applied to two common migration scales. Adjust durations based on your team size and the ratio of Tier 1 to Tier 3 accounts.

200 Accounts (~8 Weeks)

Assumptions: 150 Tier 1, 40 Tier 2, 10 Tier 3. Migration team of 1 PM, 2 CSMs, 2 engineers, 1 solutions engineer.

gantt
    title 200-Account Migration Timeline
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Planning
    Audit and inventory all accounts       :a1, 2026-07-06, 7d
    Build pre-migration spreadsheet        :a2, after a1, 5d
    Vendor lock-in evaluation              :a3, 2026-07-06, 5d

    section Token Export
    Export tokens and connection metadata   :b1, after a2, 5d
    Import tokens to new platform           :b2, after b1, 3d
    Validate token refresh per provider     :b3, after b2, 3d

    section Schema Mapping
    Map Tier 1 standard schemas             :c1, after a2, 5d
    Map Tier 2 custom fields                :c2, after c1, 7d
    Map Tier 3 custom objects and overrides  :c3, after c2, 7d

    section Cutover
    Shadow and dual-run all tiers            :d1, after b3, 7d
    Cutover Tier 1 automated                :d2, after d1, 3d
    Cutover Tier 2 guided                   :d3, after d2, 5d
    Cutover Tier 3 white-glove              :d4, after d3, 5d

    section Stabilization
    14-day monitoring window                :e1, after d4, 14d
    Legacy decommission                     :e2, after e1, 3d

1,000 Accounts (~14 Weeks)

Assumptions: 800 Tier 1, 160 Tier 2, 40 Tier 3. Migration team of 1 PM, 4 CSMs, 3 engineers, 2 solutions engineers. Tier 1 accounts migrated in 4 cohorts of 200 to limit blast radius.

gantt
    title 1000-Account Migration Timeline
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Planning
    Audit and inventory all accounts       :a1, 2026-07-06, 14d
    Build pre-migration spreadsheet        :a2, after a1, 7d
    Vendor lock-in evaluation              :a3, 2026-07-06, 5d

    section Token Export
    Export tokens batch 1 of 500            :b1, after a2, 5d
    Export tokens batch 2 of 500            :b2, after b1, 5d
    Import and validate all tokens          :b3, after b2, 5d

    section Schema Mapping
    Map standard schemas all providers      :c1, after a2, 7d
    Map Tier 2 custom fields                :c2, after c1, 10d
    Map Tier 3 custom objects and overrides  :c3, after c2, 10d

    section Cutover Tier 1
    Shadow run Cohort 1 of 200              :d1, after b3, 5d
    Cutover Cohort 1                        :d2, after d1, 3d
    Cutover Cohort 2 of 200                 :d3, after d2, 3d
    Cutover Cohort 3 of 200                 :d4, after d3, 3d
    Cutover Cohort 4 of 200                 :d5, after d4, 3d

    section Cutover Tier 2 and 3
    Guided migration Tier 2 of 160          :e1, after d3, 14d
    White-glove Tier 3 of 40                :e2, after d3, 21d

    section Stabilization
    14-day monitoring window                :f1, after e2, 14d
    Legacy decommission                     :f2, after f1, 5d

The key difference between the two scales is not just duration - it is cohort management. At 200 accounts, you can migrate Tier 1 in a single batch. At 1,000, you need cohorts to contain blast radius. If Cohort 1 surfaces a mapping bug, you fix it before Cohort 2 goes live. This phased approach is safer for complex B2B migrations with many customers because it lets you validate assumptions on a small group before committing the full population.

Owner Responsibility Matrix

Post-Migration: Monitoring and Rate Limit Management

The migration is not done when writes flip. It is done after a 14-day stabilization window where you actively monitor for the failure modes that only show up under production load. Once the cutover is complete, the operational burden shifts from migration to monitoring, which redefines how Customer Success teams handle integration issues going forward.

CS Monitoring Playbook

The post-cutover monitoring stack should track the following metrics for the first 14 days:

• Error rate per endpoint, per customer: Alert on anomalies versus the 7-day baseline.
• Sync latency: Measure the time from a source event to your product reflecting the change.
• Webhook delivery success: Track retries and final-failure counts.
• OAuth refresh failures: Break this down by provider. A spike here is usually a sign that token TTLs were not honored during the cutover.
• Rate limit consumption: Surface this through standardized headers to catch usage spikes early.
• Mapping Failures: Monitor logs for JSONata evaluation errors, which indicate a schema drift in the third-party system.

Handling Upstream Rate Limits

When moving off visual workflow builders, teams often misunderstand how modern declarative API platforms handle rate limits.

A critical architectural reality: Modern declarative integration platforms typically do not retry, throttle, or absorb rate limit errors on your behalf. When the upstream provider returns an HTTP 429 (Too Many Requests), the platform passes that error straight through to your application.

What the platform does provide is normalization. Rate limit metadata is exposed via standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset), regardless of which provider returned the response.

This is a deliberate design choice, not a gap. The platform cannot know your business priorities. A background sync should back off aggressively. A user-initiated action should fail fast with a clear error. Centralizing retry logic in the integration layer forces a one-size-fits-all behavior that breaks one of those cases. Your application's backend is entirely responsible for implementing retry logic and exponential backoff.

If your existing legacy provider was silently swallowing 429s and burying them in retry loops, the new architecture will feel noisier at first. That noise is actually visibility you did not have before. Wire it into your observability stack and your incident response gets sharper, not worse.

Strategic Wrap-Up: Treating Migrations as a Product Capability

The teams that win at enterprise SaaS treat migration as a permanent product capability, not a one-time project. Build the decision matrix. Run the audit checklist on every account, not just the ones you are actively migrating. Own your OAuth applications. Use declarative config and JSONata mappings to keep custom-field handling out of your engineering backlog. Push retry logic into your application code where it belongs.

The payoff compounds. Every customer migrated cleanly is a customer who will not hesitate when you sunset the next integration vendor in three years. Every Fortune 500 logo that never saw a reconnect prompt becomes a reference for the next deal.

The alternative - bespoke migrations, per-customer engineering tickets, silent re-authentication events - is the slow path to integration paralysis. At some point, the cost of keeping the legacy system exceeds the cost of moving, and you migrate under duress instead of on your own terms. By treating the migration as a structured operational process rather than an ad-hoc engineering task, you protect your NRR, eliminate downtime, and successfully transition enterprise accounts to scalable native infrastructure ahead of the curve.