Integration acceptance criteria: defining done for partner builds

Two engineers, one on each side of a partner integration, both believe they are finished. One says the contact sync works: he created a contact and it appeared in the other system. The other says it does not: she updated a contact and nothing happened, then deleted one and it stayed. Both are describing the same integration, and both are telling the truth about what they tested. The disagreement is not about the code. It is that nobody wrote down what "done" means for this integration, so each engineer filled the gap with their own definition, and the two definitions do not match.

Integration acceptance criteria are the written definition of done that prevents exactly this. They are the specific, testable conditions that have to be true before an integration counts as complete, agreed by both sides before the build starts rather than argued about after it ships. Where a user story says who the integration is for and why, acceptance criteria say precisely what has to work, including all the cases the happy-path demo quietly skips: updates, deletes, errors, empty states, and the volume a real customer will actually push through it.

This guide is about writing those criteria well for a partner build, where "done" is harder because two teams have to agree on it. We cover what acceptance criteria are and how they differ from a user story, the anatomy of a good criterion, the edge cases teams reliably forget, how to handle the fact that both sides have to accept, and a reusable checklist you can apply to any integration. At the end you get a criteria checklist you can adapt to your next build.

The 60-second version

If you only read one section, read this one:

• Acceptance criteria are the written, testable definition of done. They list the specific conditions that must be true for the integration to count as complete, so "done" is a fact both sides checked, not an opinion.
• They are not the user story. The story says who and why; the criteria say exactly what has to work. The story is human and readable; the criteria are precise and verifiable.
• A good criterion is testable and unambiguous. "Contacts sync reliably" is not a criterion; "a contact created in A appears in B within 60 seconds" is, because you can run it and get a yes or no.
• The edge cases are where integrations break. Updates, deletes, duplicates, errors, empty states, and volume are the cases the happy-path demo skips and the customer hits in week one.
• Both sides have to accept. An integration is done only when both teams verify their half against the agreed criteria, which is why the criteria have to be written and shared, not held in one team's head.
• Write the criteria before the build, not after. Criteria agreed up front are a spec; criteria invented after a demo are a fight about whether the work is finished.

What acceptance criteria are, and how they differ from a user story

Acceptance criteria are the set of conditions a piece of work must satisfy to be accepted as complete. They translate a user story's intent into specific, checkable statements, so that "done" stops being a judgment call and becomes a test anyone can run. The concept comes straight from acceptance testing in software: before you can say a feature works, you need a written standard of what "works" means, and acceptance criteria are that standard expressed as conditions the build either meets or does not.

The distinction from a user story is worth stating plainly, because teams that blur it get burned. A user story is the human, readable description of who wants what and why: "as a sales rep, I want new contacts to sync to my CRM, so that I can follow up quickly." That story is essential for keeping the work customer-focused, and we cover writing them in integration user stories. But it is not testable on its own. What does "sync" mean? In which direction? How fast? What about updates? The acceptance criteria answer all of that, turning the story's intent into conditions QA can verify one by one.

The mental model is that the story and the criteria are two layers of the same requirement. The story keeps everyone anchored to the customer's goal; the criteria make that goal verifiable. You need both, and you need to keep them separate: a story overloaded with technical conditions becomes unreadable for the partner conversation, and criteria written without a story lose the thread of why any of it matters. Write the story first to establish the who and why, then decompose it into criteria that pin down the what.

The anatomy of a good acceptance criterion

Not every sentence that sounds like a requirement is a usable acceptance criterion. The two properties that separate a real criterion from a vague aspiration are that it is testable and that it is unambiguous. Testable means you can run a check and get a clear yes or no. Unambiguous means two people reading it will run the same check and agree on the result. "The sync should be reliable" fails both: you cannot test "reliable" directly, and two engineers will disagree about whether a given behavior counts. "A contact created in system A appears in system B within 60 seconds, with name, email, and company populated" passes both: it is a specific, runnable test with one correct answer.

A common and powerful format for writing criteria is Given-When-Then, borrowed from behavior-driven development. You state the starting context, the action, and the expected result: given a contact exists in system A, when its email is updated, then the change appears in system B within 60 seconds. The Given-When-Then structure is useful precisely because it forces you to name the precondition and the expected outcome, which is where vague criteria fall apart. Not every criterion needs this exact form, but every criterion needs its ingredients: a context, a trigger, and a specific, observable result.

There is one more layer many teams forget: the non-functional criteria. Beyond what the integration does, there are conditions on how well it does it, latency, throughput, security, and error handling, that the customer feels even though no single feature captures them. These non-functional requirements belong in the acceptance criteria too, because an integration that syncs correctly but takes ten minutes, or leaks data, or falls over at real volume, is not actually done. When the data being exchanged has a defined shape, encoding those field-level expectations, required versus optional, types, formats, is far easier if the integration is built against a schema; a standard like JSON Schema lets you turn "the payload must include a valid email" from a prose criterion into a machine-checkable one.

The edge cases teams reliably forget

The reason integrations pass their demo and fail in production is almost always the same: the demo shows the happy path, and the happy path is the one case that was always going to work. A customer creates a record, it appears on the other side, everyone claps. Then the customer does something the demo never covered, edits a field, deletes a record, imports ten thousand rows at once, and the integration does something wrong or nothing at all. The edge cases are not exotic; they are the ordinary things real users do that the happy-path demo skips, and they are exactly what acceptance criteria exist to force into the plan.

There is a recognizable set of edge cases that integration teams forget over and over, which means you can turn them into a standing checklist and stop rediscovering them the hard way. Each one is a question the criteria must answer before the build is accepted:

The discipline is to walk this list for every integration and write a criterion for each row that applies, even if the answer is "out of scope for v1." An explicit "deletes are not handled in v1, records must be removed manually" is a fine criterion; a silent gap where nobody decided is how a customer loses data. Deciding these in advance is also what keeps the build on schedule, because edge cases discovered late are the classic cause of integration overruns, which is why they get first-class treatment in integration project management. The error-handling row deserves special care, since a partner API can and will return failures you do not control; our guide to API error design covers what good error behavior looks like on both sides of that boundary.

Handling acceptance when both sides have to agree

An internal feature has one team that decides when it is done. A partner integration has two, and that changes acceptance from a checkpoint into a negotiation. The integration is not complete when your side works; it is complete when both sides work together against a shared definition, which means the acceptance criteria cannot live in one team's head or one team's ticketing system. They have to be a shared artifact both teams reviewed and agreed to before the build.

The failure mode is predictable. Your team builds to your understanding of done, their team builds to theirs, and the two meet at integration time to discover the definitions never matched. One side assumed real-time sync, the other built a nightly batch. One side handles deletes, the other does not. Neither team is wrong by its own criteria, because there were never shared criteria, only two private ones. Writing a single definition of done that both teams sign off on before the build is the cheap insurance against an expensive integration-week surprise.

Practically, this means three things. First, the criteria are drafted jointly, or drafted by one side and explicitly reviewed and accepted by the other, so both know what they are building toward. Second, each criterion has a clear owner: some are your side's responsibility, some are theirs, and a shared criterion like "a contact created in A appears in B within 60 seconds" needs both to make it true. Third, acceptance is a joint act: you test the criteria together, or each side tests its half and demonstrates it to the other, and only then is the integration done. This shared, written, jointly-accepted standard is the same discipline that makes the whole build predictable, which is why it sits inside the broader saas integration strategy rather than being an afterthought at the end.

Common mistakes, and the fix

Writing criteria that are not testable. The fix: replace every adjective with a measurement. "Reliable," "fast," and "graceful" are not criteria; "completes within 60 seconds," "retries five times with backoff," and "surfaces a specific error message" are. If you cannot run a check and get a yes or no, it is not yet a criterion.

Confusing the user story with the acceptance criteria. The fix: keep the story human and the criteria precise, as two separate documents. The story says who and why for the partner conversation; the criteria say exactly what for the engineer. Overload the story and it becomes unreadable; skip the criteria and it becomes unbuildable.

Only specifying the happy path. The fix: walk the standing edge-case list, updates, deletes, duplicates, errors, empty data, volume, auth expiry, and write a criterion for each, even if the criterion is an explicit "out of scope for v1." The happy path always works in the demo; the edge cases are what the customer hits in week one.

Ignoring non-functional criteria. The fix: add conditions on latency, throughput, security, and error handling, because an integration that is functionally correct but slow, insecure, or fragile at volume is not done. The customer experiences these even though no single feature names them.

Letting each side define done privately. The fix: write one shared definition of done both teams review and accept before the build, with a clear owner per criterion. Two private definitions guarantee a mismatch at integration time; one shared, jointly-accepted definition is what makes both sides build the same thing.

FAQ

What are integration acceptance criteria? They are the specific, testable conditions that must be true for an integration to count as done, agreed by both sides before the build. They translate a user story's intent, "contacts should sync", into checkable statements like "a contact created in A appears in B within 60 seconds with name, email, and company populated," so acceptance is a test anyone can run rather than an opinion.

How are acceptance criteria different from a user story? The user story says who wants the integration and why, in a readable human sentence. The acceptance criteria say exactly what has to work, as a checklist of testable conditions. The story is for the partner and customer conversation; the criteria are what the engineer and QA verify against. You need both, kept as separate documents doing separate jobs.

What makes a criterion good? It is testable and unambiguous: you can run a check and get a clear yes or no, and two people reading it will agree on the result. Replace vague adjectives like "reliable" or "fast" with measurements like "completes within 60 seconds." A useful format is Given-When-Then, which forces you to state the context, the trigger, and the expected observable result.

What edge cases should integration criteria cover? The ones the happy-path demo skips and the customer hits fast: updates, deletes, duplicates, errors and retries, empty or partial data, real volume, and auth or token expiry. Walk that list for every integration and write a criterion for each row that applies, even if the criterion is an explicit "not handled in v1." A silent gap is how customers lose data.

Why do both sides have to accept an integration? Because an integration connects two products, and it is not done when only your half works. If each team builds to its own private definition of done, the definitions meet at integration time and turn out not to match, one side assumed real-time, the other built nightly batch. A single shared, written definition both teams accept before the build prevents that expensive surprise.

Should acceptance criteria include non-functional requirements? Yes. Beyond what the integration does, the criteria should cover how well it does it: latency, throughput, security, and error handling. An integration that syncs the right data but takes ten minutes, leaks information, or collapses at real volume is not actually done, even though every functional criterion passes. The customer feels these conditions directly.

When should acceptance criteria be written? Before the build, not after. Criteria agreed up front are a specification both teams build toward; criteria invented after a demo are an argument about whether the work is finished. Writing them first also surfaces the edge cases and the direction-and-timing questions early, when they are cheap to resolve rather than expensive to retrofit.

Further reading

• Wikipedia, acceptance testing, on the written standard that defines whether a build meets its requirements.
• Wikipedia, Given-When-Then, on a structure for writing criteria that name the context, trigger, and expected result.
• Wikipedia, definition of done, on a shared, explicit standard for when work is complete.
• Wikipedia, non-functional requirement, on conditions of quality like latency and security that criteria should include.
• JSON Schema, json-schema.org, on turning field-level payload expectations into machine-checkable conditions.

The short version

Integration acceptance criteria are the written, testable definition of done that keeps two teams from finishing an integration with two different ideas of what finished means. Where a user story says who the integration is for and why, the criteria say exactly what has to work, as conditions anyone can run and get a yes or no on. A criterion that is not testable and unambiguous is not a criterion; replace every "reliable" and "fast" with a measurement.

The cases that break integrations are the ones the happy-path demo skips: updates, deletes, duplicates, errors, empty data, volume, and auth expiry. Walk that list for every build and write a criterion for each, plus the non-functional conditions like latency and security that the customer feels. And because a partner integration has two sides, write one shared definition of done both teams accept before the build, with a clear owner per criterion, so acceptance is a joint test against an agreed standard rather than a fight after the demo.

If you want the whole path handled, from partner strategy and a partner-ready API through scoped, criteria-driven integration work to launch and adoption, that is exactly what a Partner Audit is for. We review your product, API, and partner potential, then define what to build, what done means, and how to ship and prove it together.