To scope an API integration, name the workflows rather than the systems, map every field with its direction and owner, write the failure cases before anyone quotes, confirm sandbox access and test data, and agree acceptance tests in advance. Do that for a payment gateway, a CRM or a shipping provider and the quote prices the real work — duplicates, outages and partial failures included, instead of returning mid-project as variations.
The short answer: the six artefacts a real scope contains
A real scope is six documents, not one sentence. One, a workflow list: each business workflow. Two, an endpoint and event inventory: which API operations and webhooks each workflow uses. Three, a data map: every field, its direction, and which system owns the record. Four, a failure-case list: what happens on duplicates, outages, rejections and partial success, and who is alerted. Five, an access checklist: accounts, credentials, sandbox and test data, each with an owner and a date. Six, acceptance gates: the tests, with evidence, that define "finished". If a proposal cannot point at all six, it has priced a guess.
| Artefact | What it settles |
|---|---|
| Workflow list | The work itself — priced per workflow, not per system |
| Endpoint and event inventory | Which API calls and webhooks each workflow depends on |
| Data map | Fields, direction, and who owns each record |
| Failure-case list | Duplicates, outages, partial success — and who is alerted |
| Access checklist | Credentials, sandbox and test data, each with an owner |
| Acceptance gates | The test evidence that defines "finished" |
The problem: "connect X to Y" is not a scope
"Connect our website to the payment gateway" sounds like one job. Inside it sit at least six: take the payment, confirm it by webhook, handle a failed or abandoned payment, refund in full and in part, reconcile the gateway's record against your orders, and cope when the webhook arrives twice or not at all. A one-line quote prices the first and discovers the rest later — which is why two quotes for "the same integration" differ wildly: one priced the happy path, the other priced the workflows. Scoping tells you which before signing.
Step 1 — Name the workflows, not the systems
Write each workflow as a sentence with a trigger, an action and an outcome: "When an order is paid, create the invoice and mark the order paid." Count them. Workflows are the true cost driver — not the number of systems — because each carries its own rules, failure cases and tests. Ten workflows between two systems is a bigger project than two workflows between four.
For each workflow, record who approves its behaviour: an operations manager signs off shipping rules, a finance owner signs off refunds. A workflow with no approver stalls the project, waiting for a decision nobody knew was theirs.
Step 2 — Map the data: fields, direction, and who owns each record
For every workflow, list the fields that move: source, destination, direction, format, and what happens when the value is missing. Then settle ownership: for each record — customer, order, payment, shipment — one system is the source of truth, and the other side never overwrites it. Two-way synchronisation is not the same work running backwards: if both systems can edit the same record, the scope states which edit wins, or you have designed a conflict.
Use sample records, including ugly ones: the customer with no email, the order with a manual discount. Clean samples hide decisions that cost money. If customer messages run through the WhatsApp Business API, the scope states whether message history joins the customer record or stays in the messaging tool.
Step 3 — Write the failure cases before anyone quotes (duplicates, outages, partial success)
Enumerate what can go wrong, workflow by workflow, and write the behaviour next to each case. The recurring four: the same event arrives twice; the other system is down; a record is rejected for invalid data; and half the work succeeds — the payment is taken but the order is not updated. For each, the scope states whether the integration retries, queues, alerts, or hands the case to a person, and how a repeated request is made safe — idempotency, in the developer's term — so a retry never charges, ships or creates twice.
Payment webhooks show why this cannot be an afterthought: Stripe's documentation states that it retries event delivery for up to three days with exponential backoff, does not guarantee events arrive in order, and advises tracking event IDs to spot duplicates. Duplicate and out-of-order events are normal. A quote written before this list exists prices a system that has never met reality.
Step 4 — Access and sandbox readiness: credentials, test data, approvals
More integration timelines die waiting for access than writing code. Before a fixed quote, confirm: an account with the right permissions on each platform; API credentials issued and stored; a sandbox with test data resembling real data; and any vendor approvals required before live use. Test the operation your workflow needs — reading a record is not proof the account may update one.
Give every item an owner and a date — "client to provide credentials" with no name beside it is a delay scheduled. If middleware will carry any workflow, name it and its limits now; our comparison of n8n, Zapier and Make shows how differently those tools behave.
The payments scope: webhooks, refunds and reconciliation
Scope payments around money states, not button clicks. Which events confirm a payment — and is the webhook, not the customer's return to your site, the source of truth? How are failed and abandoned payments represented in orders? Do refunds start in your system or the gateway's, and do partial refunds work? Who reconciles settlements against orders, and what happens when they disagree?
Our guide to the payment gateway integration steps covers the build sequence; the scoping point is narrower — if refunds, reconciliation and duplicate webhooks are not in the document, they are not in the price. Gateway fees are the provider's published on its official pages, and belong in the scope as a separate line.
The CRM scope: dedupe, routing and what "synced" actually means
"Sync the CRM" hides the same traps. Scope which objects move — leads, contacts, companies, deals — in which direction, and on what trigger. Name the deduplication key and the update-versus-create rule for repeat enquiries. State the routing outcome wanted: an owner assigned, a task created, an alert sent — or merely a record existing, which helps nobody.
Ban the word "synced" unless it is defined: which fields, how quickly, and what proves it. The build that follows a CRM scope is covered in our guide to building a form-to-CRM lead pipeline; this method stops at the decisions that build depends on.
The shipping scope: rates, labels, tracking and the exceptions
Shipping scopes fail on exceptions, not labels. Beyond rate quotes, label creation and tracking updates, enumerate: partial shipments and split parcels; address problems and failed deliveries; returns and who creates the return label; and what the customer is shown when no rate returns. Each exception is a workflow, and belongs in the Step 1 count.
Scope the data your store must hand over — weights, dimensions, declared contents — and who fixes it when missing, because carriers reject incomplete parcels regardless of API quality. This sits alongside the wider ecommerce web development decisions about checkout and fulfilment.
Acceptance gates: how you will know it works (test evidence, not demos)
Define acceptance per workflow: named tests, run on the sandbox and verified on live transactions, with evidence kept — records created, webhook log, reconciliation count. Include at least one failure test per workflow: kill the connection, send the event twice, submit the bad record.
A demonstration of one order is not acceptance. The gate passes when the Step 3 failure cases behave as written and your side signs that they do. Put that gate in the contract, and the final payment buys proof, not confidence.
Common mistakes (happy-path quotes; nobody owns the errors)
Quoting "connect X to Y" and pricing one workflow out of six. Mapping field names without agreeing what each field means or who owns the record. Leaving duplicates and retries to be "handled in testing". Demanding a fixed price before credentials, sandbox and approvals exist. Letting a demo stand in for acceptance. Structurally: nobody named as owner when the integration fails in production, so the first outage becomes an argument about whose problem it is.
FAQ
What should an integration scope document include?
Six artefacts: a workflow list, an endpoint and event inventory, a data map with field ownership, a failure-case list with agreed behaviour for each case, an access and sandbox checklist with owners, and acceptance gates defining "finished" as test evidence. If any is missing, the quote is partly a guess.
Why do integration quotes vary so much for the same job?
Because "the same job" usually is not the same job. One quote prices the happy path — the successful request — while another includes duplicate handling, retries, reconciliation, failure testing and handover. Compare quotes workflow by workflow against one scope document, and the difference becomes a list of included and excluded work.
Do we need sandbox access before getting a fixed quote?
Yes, for any quote you intend to hold the developer to. Without testing the actual operations your workflows need — with real permissions and representative data — neither side knows whether the platform allows the workflow as described. Estimates can precede access; a fixed price signed before access is verified rests on assumptions.
Who owns each piece of data in an integration?
One system owns each record, and the scope names it: the gateway owns payment state, the store owns the order, the CRM owns the customer record. Ownership means that system is the source of truth, its edits win, and the integration updates other systems from it — never the reverse without an explicit rule. Most "sync problems" are undecided ownership.
How do we accept an integration as finished?
Against the acceptance gates in the scope: named tests for every workflow, including at least one failure test each — duplicate event, outage, rejected record — with evidence kept and a person on your side signing that the behaviour matches the scope. A demo of one successful transaction proves the happy path only.
Scope it properly, then build it once (CTA)
A scoped integration can be quoted honestly; an unscoped one can only be quoted hopefully. WebStackRank scopes and builds integrations within custom web application development — where a build starts from a web application, our Basic Business Web App starter package is AED 4,990 with a fixed scope, stated as that entry point and not as an integration price, because integrations are priced from the scope. Bring us your workflow list, or start with web development consulting and we will build the scope with you; either way you receive an itemised proposal within 24 business hours.
