Partner API acceptance tests prove that an integration can recover when something goes wrong, not just that the endpoints respond. Before launch, we test four cases: a lost response followed by a retry, a request for another partner's record, an event that arrives late, and a receiver that goes offline. If each one ends with one correct business record, the integration is ready.
What should a partner API prove before it goes live?
Most API projects test the happy path. A partner sends an order, the API returns a success code, and everyone signs off. The trouble starts later. A network timeout hides whether an order was saved. The partner retries and creates a duplicate. A status update arrives after a newer one and moves a record backward. Support staff then rebuild the story from email threads.
We ask clients to agree on one test before any partner connects: can both sides tell, at any moment, what state a transaction is in and who owns the next step? An API that answers quickly but cannot answer that question is not ready.
How do you define the contract around one transaction?
Start narrow. Pick one business transaction, such as submitting a purchase order or checking shipment status. Write down which company owns the source record, which system accepts changes, and when the transaction becomes binding. Receiving a valid order is not the same as reserving stock. If the API replies before stock is allocated, return a separate processing state so partners do not have to guess.
Define identifiers before field names. A partner's order number may only be unique inside that partner's account, so store the partner identity with it and keep it apart from your internal ID. Decide whether a corrected submission updates the order or creates a new version.
Then describe the interface in a machine-readable file. The OpenAPI Specification is a standard way to describe what an HTTP API can do without reading its source code. Use it to validate requests and responses during testing, and pair it with plain definitions. A field called "delivery date" needs a rule: requested, promised or actual? Provide valid and invalid examples that use clearly fictional data.
How do you stop one partner from seeing another partner's data?
Authentication tells you who is calling. Authorization decides what that caller may do with a specific record. A valid partner key must never mean access to every order in the database.
Broken object level authorization is the first item in the OWASP API Security Top 10 for 2023. It happens when an API accepts a record ID from the client and acts on it without checking that the caller is allowed to touch that record. OWASP recommends checking every request that uses a client-supplied ID and writing tests for the authorization logic.
In practice, set separate permissions for reading, creating, changing and cancelling. Return only the fields the workflow needs. Shipment progress, yes. Internal margin or staff notes, no. Also document who can suspend a compromised credential and how normal work resumes afterward.
What should happen when a request times out and is retried?
A timeout does not prove the server rejected the request. The change may have been saved while the reply was lost. Repeating a create request blindly can produce a second order.
Microsoft's API design guidance notes that PUT requests should be idempotent, while POST requests are not guaranteed to be, so repeating a POST can create duplicates. The usual fix is an idempotency key. Stripe's public API is one worked example: the client sends a unique key, a retry with the same key returns the saved result, keys can be up to 255 characters, and a reused key with different parameters returns an error. Your rules may differ, but write them down: key scope, how long results are kept, and what a conflict returns.
Also give partners a way to look up a transaction by a stable business reference. Retry windows close, and support still needs to answer one question: did this order go through?
How should webhooks and status events be handled?
Events are a separate contract. Each one needs an event ID, the record ID, an event time, a schema version and an endpoint where the partner can fetch the current record. State plainly which delivery and ordering guarantees you actually offer.
Stripe's webhook documentation is direct about this for its own service. It does not guarantee that events arrive in the order they were generated, endpoints may receive the same event more than once, and live mode retries undelivered events for up to three days. Partners consuming your events should plan for the same behavior unless you guarantee otherwise.
Decide what a success reply from the receiver means: received, queued, or fully processed. Without that definition, nobody can tell where work stopped.
Which four acceptance tests should you run before launch?
Run these in a non-production environment with synthetic orders. For each one, record the starting state, the request IDs, the failure you injected, the expected business result, what actually happened, and who reviewed it.
- Lost response, then retry. Submit an order, drop the reply after the server saves it, and retry with the same key. Pass only if one order exists and the agreed reply comes back. Then reuse the key with changed content and confirm the documented conflict response.
- Another partner's record. Sign in as test partner A and try to read, change, cancel and list an order that belongs to test partner B. Pass only if every attempt is refused and no protected fields appear.
- Late status event. Deliver a "completed" event, then replay an older "processing" event. Pass only if the record does not move backward.
- Receiver offline. Stop the test receiver, send an event, restart it and run the recovery path. Pass only if the business action happens once and any exhausted attempts land in a visible exception queue.
Keep these tests with the interface version and rerun them whenever server logic, partner code or the schema changes.
Who owns the integration after launch?
Name owners for the business workflow, the API service, partner onboarding and incident response. Give support a standard record for every problem: partner, correlation ID, operation, timestamp, observed state and a cleaned error summary. That is far more useful than a screenshot that says "integration failed."
For the first weeks, track accepted transactions, completed transactions, rejections by reason, duplicates prevented and results nobody could confirm. Set that baseline before anyone promises an improvement.
Our API integration services and custom development work start with the business process and its failure points, not the endpoint list. If you are connecting your first partner, bring one transaction and we will help you write the four tests above.
Frequently asked questions
No. It describes the interface. You still need business definitions, enforced permissions, retry rules, named owners and tests that prove the service behaves the way the file says it does.
No. Input errors need a fix, not a retry. Temporary failures can be retried with care, and requests that change data should only be retried when an idempotency rule protects them from running twice.
Not by itself. Authentication proves who is calling. The server must also check that the caller may act on the specific record in each request, and your tests should try cross-partner access on purpose.
Before launch, and again whenever the API, the partner's consuming code or the data schema changes. Keep the results with the interface version so you can show what was proven and when.
Sources
- OpenAPI Initiative: OpenAPI Specification v3.1.1
- OWASP: API1:2023 Broken Object Level Authorization
- Microsoft Learn: Web API design best practices
- Stripe Docs: Idempotent requests
- Stripe Docs: Receive Stripe events in your webhook endpoint
Planning a partner integration?
Bring one transaction and its current handoffs. We will map the failure cases and the tests that prove recovery before launch.
