API design for B2B partners: versioning, errors and documentation that speed up integration

A B2B API is a product whose users are developers at partner companies. They judge it by one thing: how quickly and safely they can integrate and keep their integration running. Clear design, predictable behaviour and good documentation reduce partner onboarding from months to weeks — and reduce your support load along the way.

Model resources around the business

Design endpoints around the concepts partners already understand — offers, orders, travellers, payments, invoices — not around internal tables or services. Use consistent naming, plural resource paths and standard HTTP methods. A partner should be able to guess the next endpoint after reading the first two.

Make writes safe to retry

Partners’ networks fail like everyone else’s. Every endpoint that creates or changes something should accept an idempotency key, so a retry returns the original result rather than a duplicate. The technique is described in detail in idempotency in booking and payment APIs.

Version deliberately

• Additive changes — new optional fields, new endpoints — stay in the current version. Tell partners to ignore unknown fields.
• Breaking changes — removing fields, changing types or semantics — require a new major version.
• Deprecation — publish a timeline, add deprecation headers, and email affected partners using usage data.
• Parallel running — keep the old version alive long enough for real migration, not just announcement.

URL versioning (/v2/orders) is simple and visible; header-based versioning is cleaner but harder for partners to debug. Either works if applied consistently.

Errors partners can act on

Use one error format everywhere. RFC 9457 (Problem Details for HTTP APIs) provides a solid base. Each error should include:

• a stable, documented error code (offer_expired, traveller_name_invalid),
• a readable message,
• the field involved for validation errors,
• a request ID that support can trace.

Map supplier errors to your own vocabulary; partners should never need to understand a third party’s error codes.

Pagination, filtering and limits

Use cursor-based pagination for lists that change, document maximum page sizes, and support filtering by the fields partners actually query: dates, status, reference. Publish rate limits and return them in response headers so partners can back off gracefully.

Authentication and access

• API keys or OAuth client credentials per partner and per environment.
• Scopes that limit what each key can do — read-only reporting keys should not create bookings.
• Key rotation without downtime.
• Per-partner audit logs.

Events, not polling

Partners need to know when orders change — schedule changes, cancellations, refunds. Offer webhooks, so they do not poll endlessly. Delivery reliability and signing are covered in reliable webhooks.

Sandbox and test controls

A sandbox should behave like production, with realistic data and the same validation. The most valuable feature is deterministic test scenarios: special inputs that trigger price changes, timeouts, supplier errors or schedule changes, so partners can test their failure handling before go-live.

Documentation is part of the API

Good documentation includes:

• an OpenAPI specification kept in sync with the code,
• a quick-start guide that reaches a successful call in minutes,
• end-to-end workflow guides (search to booking to cancellation),
• examples for every error code,
• a changelog with dates.

Generate reference docs from the specification, and write the guides by hand.

The takeaway

The best B2B APIs feel boring in the right way: predictable names, safe retries, consistent errors, honest versioning and a sandbox that tells the truth. That predictability is what turns integration from a project into a routine.