What integration handover documentation is actually for

Integration handover documentation is not written for the person who commissioned the project. It is written for a named individual inside the client business, at around seven in the morning, when the overnight order feed has not run and the warehouse team are asking what to pick. That reader has limited time, no memory of the design decisions taken nine months earlier, and no appetite for a forty-page architectural narrative. Everything in the pack should be judged against whether it helps that person decide what has happened and what to do next.

There is a second reader, and the two are often confused. The first reader is restoring service. The second reader is changing behaviour: a new VAT rate takes effect, a courier is added, the finance team want a different nominal code for carriage, or a new sales channel is onboarded. That reader needs to understand why the interface does what it does, which fields are derived rather than copied, and what will break if they alter a mapping. Documentation that serves only the first reader produces an interface nobody dares modify. Documentation that serves only the second produces an interface nobody can fix.

It is worth being explicit about what handover documentation is not. It is not an export of an API reference from the vendor. It is not a generated schema dump with no commentary. It is not a set of screenshots of an administration console that will be redesigned within eighteen months. Those artefacts have their place, but they describe the platforms, not your interface. The value lies in the decisions: the rounding rule you chose, the customer matching logic you settled on, the three order types you agreed to exclude and the reason you excluded them.

We treat the pack as a deliverable with its own acceptance criteria, agreed during the fixed scope stage alongside the functional scope. If it is not in the scope document, it will be written in a rush during the final week, and it will read like it.

The six documents that make up a usable pack

Most handovers fail because the material exists but is scattered across emails, tickets, code comments and the memory of one developer. A usable pack is a small number of named documents, each with an owner and a revision date, stored somewhere the client controls rather than somewhere the integrator controls. Six documents cover almost every mid-sized integration we deliver.

The proportions matter. For a typical order and invoice flow between Shopify and Sage 200, the interface specification might run to twelve pages, the field mapping register to a spreadsheet of eighty rows, and the runbook to six pages. The runbook is the shortest and the most used. If the runbook is longer than the specification, something in the design is probably too fragile to hand over.

  • Interface specification — What moves, in which direction, on what trigger, and under what conditions it does not move. Includes the agreed exclusions, the retry policy, and the definition of a successfully processed record.
  • Field mapping register — Source field, destination field, transformation rule, default value, and the owner of that rule. Derived fields are flagged separately, because those are the ones a future change will get wrong.
  • Operational runbook — Symptom-led procedures for the failures that are actually likely, with the exact steps to diagnose, the safe remediation, and the point at which to stop and escalate.
  • Environment and credentials register — Every endpoint, service account, key and certificate, with its owner, its expiry date and the procedure for rotating it without downtime.
  • Change history — A dated record of what changed and why, starting from go-live. Three entries a year is normal and sufficient; the absence of any entries usually means changes are being made outside the process.
  • Support and escalation map — Who to contact for the storefront, the ERP, the hosting, and the integration itself, with reference numbers and the scope of each support agreement.

Writing a runbook that a finance manager can follow

Runbooks fail when they are organised by component rather than by symptom. The person reading it does not know that the token refresh job has failed; they know that invoices stopped appearing yesterday afternoon. Structure every entry around the observable symptom, then work inwards. A good entry opens with how to confirm the symptom is real, because a surprising proportion of reported failures turn out to be a user looking at the wrong date range or a deliberate exclusion working as designed.

Take a concrete example from a Shopify to Sage 200 flow. The symptom is that orders placed after a certain time are not present in the sales ledger. The runbook entry should direct the reader to the integration log for that time window, explain what a queued record looks like compared with a failed one, state that records are retried on a defined schedule for a defined period, and give the specific error codes that indicate a Sage 200 service outage rather than a data problem. It should then say, in plain terms, what to do: wait, replay, or escalate. The judgement is written down once, by the people who built it, rather than improvised every time.

Replay procedures deserve particular care, because this is where well-meaning staff cause duplicates. If the interface uses idempotency keys, the runbook must say so, name the key, and state explicitly that replaying a batch twice is safe. If some operation is not safe to repeat — a stock adjustment in Mintsoft that posts a delta rather than an absolute figure, for instance — that must be flagged in bold at the top of the entry, together with the compensating action. Ambiguity here costs more than any other documentation failure we see.

Finally, every runbook entry needs a stop point. Something like: if the same error persists after two replays, or if more than fifty records are affected, do not continue; raise a ticket with the following information attached. Internal teams are generally willing to follow a procedure and generally reluctant to decide when they are out of their depth. Deciding that in advance, on paper, protects both the data and the person.

Credentials, access and the things that quietly expire

A large share of post-handover incidents are not code failures at all. They are expired credentials, rotated passwords, revoked application grants, a certificate that lapsed, or a service account disabled by a routine security sweep because nobody recognised the name. These are entirely predictable and entirely preventable, and they are the first thing that goes wrong once the original developers have moved on.

The rule we apply is that every credential the integration uses must be owned by the client, created in the client's tenancy, and documented by name and purpose. A Shopify custom app token issued under a developer's personal account is a liability from the day it is created. A Sage 200 API user named after the integrator's company tells a future administrator nothing about what will break if they disable it. Name service accounts after the function they perform, record them in the register, and note the business impact of disabling each one.

The register should carry expiry dates and rotation procedures, not just values. OAuth refresh tokens that are invalidated after a period of inactivity, API keys with a fixed lifetime, TLS certificates on a self-hosted endpoint, and password policies that force a change every ninety days all need a dated entry and a named owner. Where rotation requires downtime or a specific order of operations, write the steps out and rehearse them once before handover rather than discovering the sequence during an outage.

Access to the surrounding estate matters as much as the credentials themselves. Source control repositories, the build pipeline, the hosting account, the DNS records, the logging platform and any scheduled task configuration should all transfer to accounts the client controls, with at least two named administrators. We transfer code and documentation on completion as a matter of course, but transfer is only meaningful if the receiving organisation can actually sign in after the final invoice is paid.

Treat handover as a rehearsal, not a document drop

The most reliable test of a handover pack is to make the receiving team use it while the original engineers are still available, and to say nothing while they do. Pick a quiet period, create a controlled failure in the staging environment, and ask the client's nominated person to work through it using only the runbook. The gaps appear within minutes, and they are almost always the small things: a log location that assumes knowledge, a menu path that changed, an abbreviation nobody outside the project understands.

Three rehearsals cover most of the ground. First, a failed batch recovered by replay, confirming that the reader can find the log, identify the failed records, and replay them safely. Second, a credential rotation performed end to end, including the brief period where the interface is unauthenticated. Third, a mapping change — adding a nominal code, say — taken from request through to staging deployment and verification. That third rehearsal is the one most often skipped and the one that determines whether the interface can evolve without external help.

Rehearsal also establishes an honest picture of what the client's team can realistically own. Some operations teams will comfortably take on replays and credential rotations but will never deploy code. That is a perfectly reasonable position, and it should be recorded in the support map rather than discovered later. The documentation then tells the reader exactly where their responsibility ends and the external support arrangement begins, which prevents both unnecessary escalation and the far worse alternative of someone attempting a change they do not understand.

We recommend a defined transition period after go-live, typically thirty to sixty days, during which the client's team handles incidents first and the original engineers observe rather than intervene. Every question raised during that period is a documentation defect, and the pack is amended before the period closes. Handover is complete when a full month passes without the client needing to ask a question that the pack should have answered.

Keeping the pack true after go-live

Documentation decays faster than code, because code that does not compile makes itself known and a stale mapping register does not. The decay usually starts with a change made under time pressure — a new product type, an urgent nominal code correction — deployed correctly but never recorded. Six months later a second change is made on the basis of a register that no longer reflects reality, and the interface starts producing results nobody can explain.

The defence is procedural and should be agreed at handover. No change is deployed without a corresponding entry in the change history and an update to any affected mapping row. In practice that adds perhaps fifteen minutes to a small change. Where the client retains an external integrator for ongoing work, make the documentation update a line item on every quotation, so that it is visibly priced rather than quietly dropped.

An annual review is worth scheduling, ideally before the financial year end, when finance are already examining how transactions post. The review should confirm that the credentials register is current, that the exclusions still reflect commercial reality, that volumes have not drifted beyond the rate limits the design assumed, and that the named contacts in the escalation map still work for the organisations concerned. An hour spent on this each year removes most of the uncertainty that otherwise makes a replacement project look more attractive than it needs to be.

Done properly, the pack becomes an asset rather than a compliance exercise. It shortens the diagnosis of every future incident, it gives a new finance system project a factual starting point rather than a reverse-engineering exercise, and it means the business is not dependent on a single supplier's continued availability. That independence is the point of a handover, and it is measurable: either someone in the building can run the interface, or they cannot.

Key points

  • Write the pack for two readers: the person restoring service at seven in the morning, and the person changing a mapping nine months later.
  • Every credential must be owned by the client, named after its function, and recorded with an expiry date and a rehearsed rotation procedure.
  • Handover is complete when the client's team has worked through controlled failures using only the documentation, and a full month passes without a question the pack should have answered.