Notes
Replacing an existing integration without stopping orders
Run the new integration next to the old one with writes disabled, compare what each would put in the ERP, and switch over one data stream at a time. The boundary for orders during the switch and the condition for rolling back are written down before anything is switched.
Updated
The short answer
An integration that is running is not replaced in one go. The new one first runs next to the old one, receives the same data and writes nothing. It records what it would have written, and that is compared with what the old integration actually wrote. A stream moves over only when the two match, or every difference is explained.
| Step | Old integration | New integration | Done when |
|---|---|---|---|
| 1. Parallel run | Writes everything | Reads, writes nothing, logs | Unexplained differences are 0 |
| 2. Cutover per stream | Writes the streams not yet moved | Writes the streams that moved | Each stream has had its own day |
| 3. Old route off | On standby, writes nothing | Writes everything | The agreed period has passed |
The days in the diagram are an example to calculate with. The length of the parallel run follows from whether every kind of order has come through, not from a calendar. The method is the same as a dry run before go-live, with one difference: there is an old integration to compare against.
What the parallel run shows
A store with 30 orders a day produces 420 orders in 14 days. Each order has two outcomes side by side: what the old integration put in the ERP, and what the new one would have put there.
| Outcome | Orders | Cause |
|---|---|---|
| Identical | 398 | |
| Sales tax 1 cent apart | 12 | Old rounds per line, new per order |
| Shipping booked differently | 5 | Old as a line with item SHIPPING, new as the shipping cost field |
| Missing in old | 3 | Ship-to in Canada; the old script skips them |
| Address line shorter in old | 2 | The old script cuts addr1 at 30 characters |
| Total | 420 |
398 of 420 is 94.8%. The other 22 are not errors in the new integration. They are four rules the old script applied that were written down nowhere.
The first is arithmetic. An order with 2 lines of $10.50 at a sales tax rate of 8.25%: per line the tax is $0.86625, rounded to $0.87, so $1.74 for both. Per order it is 8.25% of $21.00, $1.7325, rounded to $1.73. The ERP holds two years of invoices made the first way, so the new integration keeps that method: a one-cent gap with the captured payment stops automatic matching. More on this in money, tax and rounding.
The third is the kind of rule that breaks a replacement done without a parallel run. Somewhere in the script it says:
if order.shipping_address.country_code != "US": skip order
Someone in accounts receivable has keyed the Canadian orders by hand for years without knowing why. Without the parallel run the new integration creates those 3 orders, and accounts receivable keys them again: 6 sales orders for 3 purchases.
Every difference ends in a decision: keep the old behavior, or improve it and tell the people who work around it. One run of the comparison report looks like this:
order field old integration new integration decision
1391 tax amount 1.74 1.73 keep old
1391 shipping line SHIPPING shipping cost keep old
1397 order (CA) not created created new, manual entry stops
1402 addr1 30 characters 41 characters new, field holds 50
NetSuite's addr1 takes up to 50 characters, so the old cut at 30 was a choice of the script, not a limit of the ERP.
The parallel run costs API capacity
Reading in parallel puts requests on the same systems. On NetSuite the concurrency limit is per account: 5 requests at the same time on the Standard tier, shared by every integration on it. If the old integration uses up to 3 at its peak and the new one reads the same orders with the same pattern, the two together ask for 6. The sixth request is rejected, a REST call with 429 and CONCURRENCY_LIMIT_EXCEEDED, and it can be the old integration that loses it. The new one therefore runs at 1 concurrent request during the parallel run, outside the peak hours. The numbers per tier are in NetSuite concurrency and governance limits.
Business Central counts per user: 6,000 OData requests per 5-minute window and 5 at the same time. A new integration that signs in as its own user has its own window and does not slow the old one down. One that reuses the old integration's user shares it.
Cutover per stream, in a fixed order
Switching everything in one night means a stock problem and an order problem show up at the same moment. Switching per stream keeps each cause separate. The order runs from easy to roll back to hard to roll back.
| Order | Stream | Direction | Rolling back |
|---|---|---|---|
| 1 | Stock and availability | ERP to store | The old integration's next run overwrites everything |
| 2 | Prices | ERP to store | The same, per price list |
| 3 | Product data | ERP or PIM to store | The same, per item |
| 4 | Orders and customers | Store to ERP | What is in the ERP stays there |
| 5 | Fulfillments and tracking | ERP or 3PL to store | Resent per order |
One rule applies to every stream: one writer at a time. Two integrations that both write stock to the store overwrite each other on every run, and after a difference nobody can tell which one set the number. On cutover day the old stream goes off first and the new one on second, never the other way round.
Orders are the last writing stream to move. A sales order created in the ERP has a number, committed stock and sometimes a pick ticket. Switching an integration off does not remove it.
Orders during the switch
Between the moment the old order stream stops and the new one starts, orders keep coming in. Who handles them is decided beforehand.
An example. The old integration polls for new orders every 15 minutes and runs for the last time at 5:45 am. The new one starts at 6:00 am. Order 1482 comes in at 5:52 am: after the old one's last run and before the new one's start. If the new integration starts with orders from 6:00 am, nobody handles order 1482.
Three rules close that gap:
- The boundary is an order number. The old integration handles up to and including 1481, the new one from 1482. The clocks of a store and a server can differ by minutes; an order number cannot.
- The old integration's queue is emptied first. Orders it had fetched and was still retrying are finished or handed over by name, for example 2 orders in retry, both delivered at 5:58 am.
- The new integration checks whether the order exists. It looks up the store order number as the external ID of the sales order before it creates anything. An order that both integrations saw becomes one sales order. How that check works is in duplicate customers and duplicate orders.
Orders from before the boundary that are still open need tracking and a status change later. That list is made on the day itself, say 37 orders, and goes into the new integration as its starting file.
The rollback rule
Rolling back is a decision that is made badly under pressure. So it is written down before the first stream moves, with four parts:
| Part | Example |
|---|---|
| The threshold | More than 3 of the first 150 orders (2%) on the exception list, or more than 50 items with a stock difference in the daily comparison |
| Who decides | One named person, and a deputy |
| What rolling back means | Per stream: new off, old on, the order-number boundary moves |
| Until when it is possible | 14 days: credentials valid, server on, scheduled jobs disabled and not deleted |
The numbers are examples. The form is the point: a threshold that can be counted, a name, and an end date after which the old route is gone. In the first days after each cutover, someone with access to both the store and the ERP is reachable. A stream that runs once a month, such as an export at month-end close, keeps the old route available until it has run once on the new integration.
What this means for your integration
We build the new integration next to the existing one, run it in parallel with writes disabled and deliver the comparison report per run: which records match, which differ and why. You approve the differences before a stream moves. Exclusions and rules the old script applied silently become settings you can see in the dashboard. If the old system has no API, reading runs through one of the routes in integrating a system without an API.
After the cutover we host and run the integration, with a queue and retries so an order does not disappear silently. The flows we build are on integrations. Tell us what runs today and between which systems, with or without documentation.
Frequently asked questions
Can the store keep running while the integration is replaced?
Yes. During the parallel run nothing changes: the old integration does the work and the new one only reads. At cutover the old one stops and the new one starts, per stream. The store keeps taking orders; an order placed in those minutes falls under the boundary that decides which integration handles it.
How long should the new integration run in parallel?
Until every kind of order and every exception has come through at least once: a discount, a ship-to outside the US, a return, a credit memo, a partial shipment. The measure is the number of unexplained differences, and it has to be zero.
What happens to orders placed during the cutover?
They fall under a boundary set in advance, by order number and not by time. The old integration handles everything up to and including, for example, order 1481, the new one everything from 1482. A lookup on the store order number in the ERP stops an order that both integrations saw from being created twice.
Our integration was built by someone who left, and there is no documentation. Can it be replaced?
Yes. The code, the scheduled jobs on the server and the audit trail in both systems show what the script reads and writes. What they do not show comes out in the parallel run: every difference between old and new is a rule the old script applied. That is how the documentation gets written after all.
What if the new integration makes mistakes after go-live?
Then the rollback rule that was written down beforehand applies: the threshold that turns the old route back on, who makes that call, and until when the old route stays available. For stock, rolling back is one run of work. For orders, what is already in the ERP stays, and the order-number boundary moves.
Tell us what you need
Tell us which systems you use and what needs to work better. We reply personally within one working day. We help you define the work, then agree the price and timing before you commit.
- You know the price and the timeline before you commit to anything
- We work out the connection that takes the work off your hands
- We handle the build, hosting, monitoring and maintenance
- Your team has less information to retype and fewer discrepancies to chase