B2B SaaS API Design: Versioning, Webhooks, and Rate Limits Done Right

The moment a customer writes code against your API, you have made a promise you cannot take back casually. B2B APIs are product surfaces with compatibility contracts: the integration a customer built in January must still work in December, through every feature you shipped in between. This guide covers the four design areas where B2B APIs earn trust or burn it: versioning, webhooks, idempotency, and rate limits.

Versioning: additive by default, versioned by exception

The sustainable policy has two tiers:

• Additive changes ship freely: new endpoints, new optional fields, new enum values on fields you documented as extensible. Customers must build tolerant readers (unknown fields ignored), and your docs should say so explicitly.
• Breaking changes get a version: removing or renaming fields, changing types or semantics, tightening validation. Date-based versions (2026-07-01) pinned per API key work better than /v2/ URLs at B2B scale: each customer upgrades on their schedule, and you can count exactly who sits on which version.

The operational half matters more than the scheme: a documented deprecation window (12 months is the enterprise norm), usage-based outreach to the customers actually on the old behavior, and Deprecation/Sunset headers so well-built clients can alert themselves. Killing an endpoint your biggest customer still calls is a churn event, not a cleanup.

Webhooks: delivery is your problem

Every B2B integration eventually needs events pushed outward, and webhook reliability is where most APIs disappoint. The contract that works:

• Sign every payload (HMAC with a per-endpoint secret, timestamp in the signature to kill replay). Document the verification snippet in five languages; unsigned webhooks are a security finding in your customer's audit, not just yours.
• Retry with backoff and a dead-letter view: failed deliveries retry over 24-72 hours with exponential backoff, and customers can see and replay failures in the dashboard. The replay button eliminates a whole category of support tickets.
• Order is not guaranteed, and you must say so: deliver events with sequence numbers or timestamps so consumers can reorder; promise-and-break ordering is worse than never promising.
• Thin payloads age best: event type, IDs, and a version, with the consumer fetching current state via the API. Fat payloads freeze your schema and leak data through logging middleware on the customer's side.

Idempotency: the difference between a retry and a duplicate

Networks fail after the request succeeds, so every serious client retries, and every mutating endpoint must make retries safe. The standard mechanic: an Idempotency-Key header on POST requests, stored with the response for 24+ hours; a repeated key returns the stored response instead of re-executing. Two details separate real implementations from checkbox ones: concurrent requests with the same key must not both execute (lock on first sight of the key), and a reused key with a different body is a 422, not a silent success. This is the same discipline that keeps billing systems from double-charging, applied to your customers' code.

Rate limits: protect the platform without breaking integrations

• Per-tenant, not per-IP: B2B customers run from clouds and NATs; IP-based limits punish the wrong people. Limits attach to the API key, and in multi-tenant architectures they double as noisy-neighbor protection.
• Communicate state on every response: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and a Retry-After on 429s. Clients cannot behave well against limits they cannot see.
• Separate read and write budgets, and give bulk operations a real batch endpoint (or async jobs with status polling) so customers are not forced to hammer single-item endpoints in a loop, the same async pattern from our LLM integration patterns for anything slow.
• Make tiers a commercial object: published defaults, higher tiers by plan, and the enterprise conversation handled by sales configuration, not by customers discovering 429s in production.

The parts customers grade you on silently

Error responses with machine-readable codes and human-readable hints (a stable code, a message, and the field that failed), cursor-based pagination that survives inserts, API keys that can be scoped and rotated without downtime, and a changelog that is actually maintained. None of these is glamorous; together they are why one API gets recommended in your customers' engineering Slack and another becomes the integration nobody wants to own.

An API is the one part of your product other people build their products on. If yours is growing from "endpoint we exposed" toward "platform customers depend on," our SaaS engineering team designs and retrofits the contract layers described here without breaking the integrations already in the wild.