An API for your partners

Find out what they are actually going to do with it

Three customers ask for "an API" and mean three different things. A distributor's largest account wants to stop calling for order status. A manufacturer's dealer network wants to see inventory and submit warranty claims without logging into a portal. An insurance carrier's independent agents want to push a quote request and get a rated answer back inside the software they already work in. Those are three different products. The first is a lookup, the second is a submission plus a lookup, and the third is a synchronous transaction with real money attached. Building one general API for all three is how you get something that serves none of them well.

So before any design work, get on the phone with three partners who have asked, and ask a very specific question: what will you do with the response? Not what data do you want. What will you do. The distributor's customer wants to show an expected delivery date on their own internal screen so their receiving team stops calling. That means they need one field reliably, not forty fields occasionally. That answer changes the whole project.

Ask a second question too: who is going to write it? The answer is rarely "our developers." It is usually a contractor who bills hourly, sometimes the integrator who implemented their business system, and increasingly a middleware product with a drag-and-drop connector builder. All three want the same thing from you, which is the least surprising possible interface.

You may not need an API

This will not be a popular paragraph, but it saves people real money. A scheduled file still runs an enormous amount of business-to-business commerce, and for a whole class of needs it is the better answer. If four partners each want yesterday's shipments once a day, a file dropped on a server at five in the morning is cheaper for you and cheaper for them. Nobody is on call for it. There are no rate limits to argue about, no tokens to rotate, and their side can be built by someone who has never written a line of code against a web service.

The file wins when the data is a batch, the freshness requirement is measured in hours, and the partner count is small. The API wins when the answer has to be current at the moment of asking, when the partner is submitting something rather than receiving it, or when you have enough partners that hand-holding each file is more work than running a self-service front door.

Plenty of companies need both, and there is nothing embarrassing about that. Your largest trading partners will very likely stay on structured document exchange for years because their systems were built around it and the cost of changing is theirs, not yours.

The three shapes, and what each one requires

Lookup. Give me the status of this order, the price and availability for this item at my contract terms, the balance on this account. Read-only, low risk, and the place to start. The hard part is not the endpoint, it is deciding what a partner is allowed to see and proving it on every call.

Submission. Take this order, this claim, this timesheet, this service request. Now you have money and legal consequences on the line, and you need three things the lookup did not: a way for the partner to safely retry without creating two orders, a validation response a non-engineer can act on, and a clear statement of what happens next and when.

Keep-a-copy-in-sync. The partner wants their own database to match yours. This is the request that quietly turns into the biggest project. Do not solve it by letting them poll a full export every hour. Give them a changes feed: a single endpoint that returns everything modified since a cursor they pass back to you, in modification order, with deletions represented explicitly rather than by absence. That one design decision replaces most of the support tickets you would otherwise get.

What the partner wants	Right shape	The part teams underbuild	Honest onboarding time
Order or shipment status	Lookup by your id or theirs	Accepting their purchase order number as a lookup key	2–5 business days
Price and availability	Lookup, contract-aware	Their pricing tier, their units of measure, their item numbers	1–3 weeks
Submit an order or claim	Submission with a client-supplied reference	Safe retries, and errors written for a human	2–6 weeks
Mirror your catalog or customer list	Changes feed with a cursor	Deletions, and a full-resync path when they fall behind	3–8 weeks
Be notified when something changes	Webhook, with polling still available	Retries, signing, and a replay screen they can use themselves	2–6 weeks

Authentication your partner can actually implement

This is where good engineering advice and good business advice diverge, and you should know you are making a trade. Mutual certificates and signed assertions are more secure. They will also stop a meaningful share of your smaller partners from ever finishing, because the person on the other end is a generalist who has thirty other things to do and no idea how to install a client certificate in their integration tool.

For most partner programs, the pragmatic answer is a long, high-entropy key per partner over an encrypted connection, sent in a header, with three properties that matter more than the algorithm: it can be rotated without downtime because two keys can be valid at once, it is scoped so a leaked key exposes exactly one partner's data, and you can revoke it in seconds from an internal screen without deploying anything.

Offer the stronger option to the partners who ask for it. Large partners with a security review will ask, and they will be pleased that the answer is yes. Do not make it the only door.

Their identifiers matter more than yours

Your system thinks in your customer numbers, your item numbers, your order numbers. Your partner thinks in theirs, and the friction between those two vocabularies is where most integration hours go.

Two rules cover almost all of it. First, accept a lookup by the partner's own reference: their purchase order number, their claim number, their part number. That single feature removes a translation table from their side and is the difference between a two-week integration and a two-month one. Second, echo both identifiers in every response. When a support call happens — and it will — you want the partner reading you a number that exists in both systems.

Units of measure deserve their own paragraph, because they cause more silent errors than anything else in business-to-business integration. You sell by the case, they buy by the each. You quote per hundredweight, they think in pounds. Never infer the unit. Put it in the request, require it, echo it in the response, and reject a request that omits it rather than defaulting. A default unit of measure is a wrong order waiting for a busy week.

The metric that matters is time to first working call

Measure one thing above all others: the elapsed time from issuing a partner their credentials to their first successful production call. Not the number of endpoints, not uptime, not calls per day. That single number tells you whether the program works.

A well-run partner API lands somewhere in the range of a few days to a couple of weeks for a simple lookup, and a few weeks for a submission. When it stretches past two months, the cause is almost never the difficulty of the data. It is that the sandbox was empty, the documentation assumed knowledge the partner did not have, or a question sat unanswered for four days. Expect a real share of partners — commonly a quarter to a third — to start and never finish. Reducing that number is a support and documentation problem, not an engineering one.

A sandbox with data that looks like their account

An empty sandbox is worse than no sandbox, because the partner's first experience is a screen full of nothing and a support ticket. Populate it. A dealer's test account should have a handful of orders in different states, a couple of items on backorder, one on credit hold, a partial shipment, and a claim that was rejected. The interesting cases are the ones their code has to handle, and if they cannot reproduce them in test they will discover them in production, on a Friday.

The sandbox also needs a way to force a scenario. Give partners a documented way to make a test order ship, or to make a submission fail validation, without asking you to go do something in a back-office screen. Every one of those requests is a ticket, and tickets are what make partner programs expensive to run.

Versioning for integrations nobody will ever upgrade

Here is the reality of business-to-business integration: some partner will build against your API in 2026 with a contractor who is gone by 2027, and that code will run untouched until something breaks. Plan for that instead of resenting it.

Practically, that means additive changes only within a version — new fields are fine, removed or renamed fields are not, and a field that used to be optional becoming required is a breaking change even though nothing in your schema looks different. When you do need a new version, run the old one for a long, published window, and instrument calls per version per partner so you know exactly who you have to call. A deprecation notice on a documentation page reaches nobody. A phone call to the four partners still on version one reaches everyone who matters.

Watch the changes that do not look like changes: tightening a validation rule, shortening a field, changing the order of results, adding a value to a status list. That last one breaks partners who wrote a lookup table of your statuses, which is most of them. Say on day one whether status values are a closed list, and if they are open, publish an example that includes an unknown value so their code has to handle it.

Rate limits, and the partner who polls every five seconds

Somebody will poll an order-status endpoint every five seconds for an order placed last Tuesday. This is not malice. It is a default in a tool, or a loop written by someone who never considered that the answer changes twice a day.

Publish limits before you need them, enforce them politely, and always answer three questions in the rejection: which limit was hit, how long to wait, and how much is left. Then solve the underlying want, because a rate limit is a wall and the partner's problem is still real. That means a webhook, or a changes feed, so they can stop asking repeatedly for an answer that has not changed.

Errors written for the person who will read them

Partner API errors get read by two people: a developer during the build, and a customer-service representative six months later when an order did not arrive. Write for both. Keep a stable machine-readable code so their software can branch, and a human sentence that names the field, the value, and what to do about it.

"Invalid item" is a support call. "Item ABC-1120 is not on your contract; contract items are listed on the price endpoint" is not. And distinguish clearly between four situations that partners constantly conflate: you sent something malformed, you sent something valid that our rules reject, you are not allowed to see this, and we are having a problem. Those need four different reactions and they are frequently collapsed into one generic failure.

The support burden is the real cost

The build is a project. The support is a permanent operating expense, and it is the part nobody budgets. Every partner integration is a relationship with a third-party developer you do not employ, working on a system you cannot see, on a schedule you do not control.

Plan for a named person who owns partner integration questions with a published response time. Plan for an internal screen that shows a partner's recent calls, their errors and their rate-limit hits, so support can answer without asking an engineer to grep a log. And plan for onboarding to be a repeatable process with a checklist: credentials issued, sandbox verified, test cases passed, production keys issued, first live transaction confirmed by a human on both sides.

Documentation that starts with something that works

Partner developers do not read reference documentation first. They look for a command they can paste into a terminal that returns real data from their own account, and everything after that is easier. Put that at the top of the page: one call, with their key, returning something recognisable.

Then, in order: a short page on authentication and key rotation, one worked end-to-end example per shape with real request and response bodies, an explanation of the identifiers and units, the error list with what to do about each, the limits, and only then the full reference. A schema file is useful for tooling and it is not documentation. The best partner documentation we have seen is largely worked examples with the reference underneath.

The partner who is scraping your portal

If someone is screen-scraping your customer portal, that is not a security incident to be blocked. It is a product requirement someone else already wrote for you, and it is free research. Find out who they are and what fields they take. That list is your first version.

The same applies to the customer whose team re-keys your order confirmations into their own system by hand. Somebody is spending four hours a day on that, and they will happily tell you exactly which fields matter and which they ignore. Ask them before designing, and the design mostly writes itself.

Set expectations in writing, even informally

Partners will build business processes on your endpoint, so tell them what they can rely on before they find out the hard way. A single page covers it: expected availability, when you do maintenance and how much notice you give, how long a version is supported after a successor ships, what the limits are, what data they are permitted to store, and what happens to their access when the commercial relationship ends. None of that has to be a contractual guarantee to be useful. Written expectations prevent nearly every angry email in this category.

The mistakes we get called in to fix

• An empty sandbox, so the first partner experience is a support ticket
• Lookup only by your identifiers, forcing every partner to build a cross-reference table
• A default unit of measure that quietly turns cases into eaches on a large order
• Authentication a generalist cannot implement, and a partner list stuck at two of eleven
• An hourly full export because there is no changes feed, with the load to match
• Errors that say "invalid request", read six months later by someone in customer service
• Status values quietly added, breaking every partner who wrote a lookup table
• No per-partner visibility, so every question becomes an engineering task

A six-week first release

That last week is worth more than the rest combined. Sit with the first partner's developer while they build, silently if you can manage it. Every place they hesitate is a defect in your documentation, and every question they ask will be asked again by the next twelve partners. Fix it once, before you have twelve.

Before you open it to partners

• You know what each partner will do with the response, in their words
• You have decided honestly whether a scheduled file serves some of them better
• Lookups accept the partner's own identifiers and echo both
• Units of measure are explicit, required, and never defaulted
• Keys are per partner, rotatable with overlap, revocable in seconds
• The sandbox contains the awkward cases and a way to trigger each
• Submissions are safe to retry with a partner-supplied reference
• Errors name the field, the value and the next step
• Calls per version per partner are instrumented before the first deprecation
• A named person owns partner questions, with a published response time

Bottom line

A partner API succeeds or fails on somebody else's developer finishing the integration. That makes onboarding, sandbox quality and documentation the product, and the schema a detail. Find out which of the three shapes you are actually building, be willing to say a scheduled file is the better answer, accept their identifiers, make the units explicit, choose authentication a generalist can finish, and measure the days from credentials to first live call. Everything else on this page is downstream of that one number.

Frequently asked questions