Migrating off a unified API provider

Teams move off a unified API provider for ordinary reasons: the provider deprecates the products they rely on, coverage stalls on the platforms that matter, pricing changes, or the product needs data the provider does not model. In 2026 many fintech and SaaS teams are revisiting the question after Codat announced a refocus on commercial banks and deprecated legacy products on 28 February 2026 (Codat docs, checked November 2026).

Whatever the reason, the risk is the same. Your customers connected their ledgers and stores once, and they expect them to keep working. A good migration is one they do not notice. This playbook covers how to get there.

The shape of a migration#

A safe migration runs in six phases:

1. Assess what you use today and what each platform allows.
2. Map every object and field to the new model.
3. Build the new integration path behind a switch.
4. Run in parallel and diff the results.
5. Cut over in batches, with rollback points.
6. Decommission the old provider.

Skipping the parallel run is the most common cause of migrations that go wrong. It is also the phase teams most want to skip.

Phase 1: assess#

Start with an inventory. You cannot plan a migration of things you have not listed.

What you use#

• Platforms and connections. Every platform, with the number of active customer connections on each.
• Objects and operations. Which objects you read, which you write, and which webhooks or change events you depend on.
• Fields. The fields your code actually reads. Search your codebase for the provider's field names; the list is usually shorter than the provider's schema.
• Behaviors. Sync frequency, how you detect changes, how you handle errors, and anything your product assumes about ordering or freshness.

Who owns the credentials#

This is the question that decides how painful the migration is. For each OAuth platform, find out whose app your customers authorized:

• You own the app (your client id and secret, registered with the platform under your company). The grants belong to your app. In many cases you can export the refresh tokens from the old provider and import them into the new one, and customers never see a thing. Confirm this is permitted by your contract and by the platform's terms.
• The provider owns the app. The grants belong to the provider's app. A new provider cannot use them. Customers will need to reconnect, and you should plan for it now.

API-key and credential-based platforms sit in between: the key may be portable if you can retrieve it, but many providers will not export secrets. Desktop and on-premise agents almost always need reinstallation or reconfiguration.

The output#

A short assessment document per platform: connections, objects, fields, credential ownership, reconnect requirement and risk. This is what you plan the rest of the migration from.

Phase 2: map#

Map every field your code uses to the new model. A spreadsheet is fine.

Three rules make mapping easier later:

1. Join on the platform's own id. Provider ids will differ. The platform's id (remote_id in many models) is the stable key that lets you match records across the two systems.
2. Write down every enum. Status values are where silent mismatches hide.
3. List the gaps. Any field with no target needs a decision: a custom field mapping, a raw record lookup, a passthrough call, or a product change.

Phase 3: build behind a switch#

Build the new path so that each connection can be pointed at either provider. A per-connection flag is ideal; a per-platform flag is acceptable.

const provider = flags.integrationProvider(connection.id); // "legacy" | "unify"

const invoices =
  provider === "unify"
    ? await unify.finance.invoices.list({ connectionId: connection.unifyId, status: "open" })
    : await legacy.listInvoices(connection.legacyId);

Keep the rest of your code talking to your own internal model, not to either provider's. That boundary is what lets you switch connections one at a time.

Phase 4: run in parallel and diff#

For a sample of real connections, run both providers side by side and compare the results.

What to compare#

• Record counts per object per connection.
• Field values for every mapped field, joined on the platform's own id.
• Totals, such as the sum of open invoice amounts per customer, compared as decimals.
• Change timing, the delay between a change in the platform and its arrival in each system.

How to read the diff#

Expect differences. Each one falls into one of four buckets:

1. Mapping error. Fix the mapping.
2. Freshness. One system synced later. Re-run the comparison after both have synced.
3. Model difference. The providers represent the same thing differently. Decide which your product needs.
4. Real data problem. Sometimes the old provider was wrong. Document it, because your customers may notice the fix.

Run the parallel phase until the diff for each platform is either empty or fully explained. Writes need extra care: never write through both providers to the same ledger. Test writes against sandbox companies, then switch writes over per connection at cutover.

Phase 5: cut over in batches#

Move connections in batches, smallest risk first.

• Batch 0: internal and test connections.
• Batch 1: a handful of friendly customers who have agreed to help.
• Batch 2 onward: the rest, by platform or by cohort, growing batch size as confidence grows.

For each batch, define:

• Entry criteria. Parallel-run diff clean for this platform.
• Success criteria. Error rates, sync delays and support tickets within agreed bounds for a set period.
• Rollback point. Flip the flag back to the old provider. Keep the old provider's connections live until the batch is confirmed, so rollback is a switch, not a reconnect.

Reconnects, when you need them#

Where customers must reconnect, make it easy and expected.

• Explain in-product, not only by email. A banner on the integrations screen with a single button works better than a link in an email.
• Give a reason and a date. "We're moving to a new integration provider to support more platforms. Please reconnect QuickBooks Online by 15 January."
• Keep the old connection working until they reconnect. Do not break data flow to force action.
• Track progress. A daily list of unreconnected connections for your success team.

Comms templates#

Advance notice (two to four weeks before):

We're upgrading how [Product] connects to [Platform]. On [date] we'll ask you to reconnect once. It takes about a minute, and nothing else changes.

Action required:

Please reconnect [Platform] to keep your data syncing. Your existing data is safe. [Reconnect now]

Completed:

Thanks. [Platform] is reconnected and syncing as before.

Adjust tone to your brand. Keep the messages short, specific and dated.

Phase 6: decommission#

When every connection has moved and the success period has passed:

1. Stop syncs on the old provider.
2. Revoke tokens held by the old provider where you can.
3. Ask the old provider to delete stored data, and get confirmation in writing.
4. Remove the old code path and the feature flag.
5. Update your sub-processor list and privacy documentation.

Decommissioning is where costs stop. It is also where data protection obligations are met, so do not leave it as a someday task.

Timeline and roles#

A migration touches engineering, support and customer success, so name an owner for each before the assessment starts.

• Engineering lead. Owns the mapping, the switch, the diff tooling and the cutover runbook.
• Support lead. Owns the reconnect playbook, the macros for common questions and the escalation path during each batch.
• Customer success or account owners. Own the messages to your largest customers and decide which accounts go in which batch.
• An executive sponsor. Holds the deadline, approves the rollback criteria and makes the call if a batch needs to pause.

As an illustration of how the phases stack up: an assessment in week one, mapping and building in weeks two to five, a parallel run over the following two weeks, then cutover batches spread across one to two more weeks. Treat that as a planning example rather than a promise; platform count, reconnect needs and your release cadence decide the real calendar.

Risks to plan for#

How Unify Int fits#

The Unify Technology Center runs this playbook as a migration service: assessment, mapping report, parallel run with diffs, cutover plan and reconnect strategy, with token transfer where the platform and your contract allow it. The new path lands on the Unify Graph, with raw records, custom fields and passthrough for anything the model does not cover. If you are moving off Codat specifically, our Codat comparison sets out the differences with dated sources. To start, plan a migration with an assessment of your platforms.