Playbook
How to Mock Up a SaaS Integration Before Anyone Builds It
Short answer: take screenshots of the host product's real screens (from a demo account), and build a clickable mock-up of that product with the partner's capability drawn in, using fictional data and no real API calls. Draw what the partner cannot do and the friction in the flow, not just the happy path, and label on each screen what is real and what is invented. Then run the scoping meeting from a numbered list of questions ordered by dependency, with the technical evidence underneath for when someone pushes back.
Integration scoping usually goes like this. Both sides describe their systems, someone writes a doc, and the hardest question, what should this actually look like?, gets settled in a meeting, in words. Everyone leaves with a different picture in their head. The first time anyone sees the integration is after it has been built, which is the most expensive possible moment to discover the button was in the wrong place.
A mock-up moves that moment to the front. "Where does the partner's feature go" stops being a discussion and becomes a thing people point at. Ambiguity that survives a conversation does not survive a picture. These rules come from building one by hand for a real integration between two products, and from the revisions it needed.
What you need before you start
- One to three screenshots of the host surface. The screen where the partner's capability would appear, plus any screen it hands off to. Use a demo or empty account, or redact first. Screenshots of live products very often contain real customer data.
- An honest read of each side's system. What the partner's API actually exposes, and what the host's codebase can already do. The fastest source is each team's own coding agent, asked to describe its own product's relevant endpoints, data and auth. Each side runs that on its own code and shares what it chooses.
- A tool you can change during the meeting. Linked screenshots in a slide deck, Figma frames on top of the screenshots, or a static HTML prototype your coding agent writes from them. The HTML route usually looks most like the real product.
Screenshots are the load-bearing input, not a fallback. A description of a product rebuilt from its code can be confidently wrong about density, real labels and how crowded a screen feels, and a plausible-but-wrong rendering of someone's product does more damage in a meeting than no rendering at all.
How to mock up an integration: seven rules
1. Build it in the host's look, not yours
The mock-up should look like the host product, with its colours, fonts and spacing, not like your design system or a generic wireframe kit. Then make the partner's part visibly different: keep the partner's accent colour far from the host's in hue. At a glance, everyone in the room should see which pixels belong to the host and which are the capability dropped into them. That is the question the meeting is about.
2. UI only: no real endpoints, no real data
Resist every instinct to make it work. The moment a mock-up calls a real API it stops being cheap, stops being safe, and becomes a product someone has to maintain. Every person, company and number in it should be fictional. State should vanish on refresh. Discovering the placement is wrong should cost an edit, not a sprint and a revert.
3. Draw what the partner cannot do, next to what it can
This is the rule that makes a mock-up worth more than a sales demo. In the one we built, the strongest screen was a form with a button that filled it from the partner's customer data. Pressing it left two of the seven fields empty, with the reason beside each, and marked a third as deliberately not sent. A mock-up that fills every field is selling a capability neither side has, and the meeting finds out a sprint later. The gaps are the argument.
4. Draw the friction, especially the only piece of it
Our first version drew connecting the two accounts as one button. The partner's own code showed a security challenge and a browser extension behind it. We redrew it as the real handshake. A mock-up that hides the one real obstacle gets found out in week one of the build, and then every other claim in it is suspect too. Friction is cheap to draw and expensive to omit.
5. Say what is invented, on each screen
Some screens are copied from real screenshots. Some are invented, because nobody had a screenshot of that part. Some show a capability you have verified exists, in a picture you made up. Label each screen individually, on the screen itself, because the person looking at it is looking at one screen, not reading the footnote.
6. Never draw an open question as a fact
Our first version had a sidebar line stating, confidently, how account access would work. The partner's codebase read later showed only one of the two access models was actually evidenced. The line now reads as the ask: the open question, named. A mock-up is shown to the people it describes. A confident sentence about their own backend that their engineers know is unsettled costs more credibility than it buys.
7. Lead with what already works
When you list what each side has to build, start with what already exists. Our first draft was a list of gaps, and it read as "this is enormous". The most valuable single finding was that the partner's API needed nothing built for the integration at all. A partner's real fear is that the integration is impossible, and the honest answer is often "already there, or one question away". Put that at the top.
How to run the meeting from the mock-up
Our first version had the technical evidence at the top and a flat list of decisions at the bottom. That is a reference document. You can read it; you cannot run a meeting off it. What works is the other way round: questions first, evidence second.
| Section | What goes in it |
|---|---|
| 1. The questions to settle today | Numbered. Each one: who owes the answer, why it matters, what each side's systems already told you, the options if it is a choice, and what a good answer should write down. |
| 2. The one question with no answer yet | Broken out beside the list, with ranked options, including any you ruled out and why. |
| 3. The evidence | One column per partner. Every row tagged: already works, to build, one question first, or decide together. |
| 4. One closing line | The thing worth saying out loud before everyone leaves. |
Order the questions by dependency, not importance
Some answers change what later questions are even asking. Whether a user ever opens the partner's own product decides what "which APIs do we need?" means, so it goes first, even if the API question feels more important. The running order is the agenda. Get it right and the meeting walks itself.
Give the hardest open question its own block
In most integrations there is one item nobody can answer yet, often how a sale inside the host gets attributed to the partner. Left as one bullet among twenty, it looks buried. Broken out with options, including the one you ruled out and why, it reads as work done rather than a problem dodged. Put it beside the question list, where you will reach it mid-meeting, not after three columns of evidence. The attribution side of that question is its own topic: partner attribution for SaaS.
Write the answers next to the questions
During or right after the meeting, record each answer under its question: answered, partly, or open. That turns the agenda into the record. Expect to re-cut it: a question that closed can reopen from the other side, and a question nobody understood is better replaced by a clearer one than argued about twice.
What happens after the meeting
Once both sides agree, the mock-up becomes the specification. Whatever each side uses to build, whether an engineer or their own coding agent, gets a picture of the agreed result instead of a paragraph describing it, and the code ends up matching what the founders agreed to rather than what someone inferred. Each side then builds its own half.
Keep the mock-up private to the people in the partnership. It shows an unreleased version of somebody's product, built from screenshots they shared in confidence. That is not a public asset by default, however good it looks.
Common integration mock-up mistakes
- Mocking up before both sides have described their systems. You will draw capabilities that do not exist and miss the ones that do.
- Every field filled. The happy path only. See rule 3.
- One button for a five-step flow. See rule 4.
- Real customer data in a screenshot. Demo account, or redact first.
- Evidence first, questions last. Nobody can run a meeting from it.
- Mocking up a commodity feature. If the partner's capability is something your own coding agent could rebuild in a weekend, a mock-up will not save the partnership. Check that the capability is worth integrating with before you draw it.
The mock-up sits between choosing an integration partner and building anything, and it is the cheapest point in the whole process to be wrong. On Ordana, a collaboration's members can view a mock-up like this privately from their Partnership tab; the ones that exist so far were made by hand, the same way this guide describes.
Related reading:
- The 3 Types of SaaS Integration: Placement, Capability, Handoff — which kind of integration you are drawing changes what the mock-up needs to show.
- How to Build a SaaS Partners Page That Recruits Partners — where the integration shows up once it ships.
- Integration Partners Get Paid Nothing — And That's Why Integrations Rot — why the partner on the other side of the mock-up needs a share of what it sells.