Provider Capability Matrix

A platform that normalises many external providers behind one interface faces an unavoidable fact: providers differ in ways that matter to consumers. Categorisation, status semantics, which of several "balances" is meant, identifier stability, whether cancellation is supported within a window.

Flattening those differences produces values that are uniformly available and quietly wrong. The capability matrix is the alternative: normalise the shape, and declare per provider what is genuinely supported.

Why it matters

Consumers need to know what they can rely on before they build. A field that silently returns an approximation for a third of providers produces bugs that surface in the consumer's product, months later, as data that does not reconcile.

It is also an operational asset: when a support engineer investigates a discrepancy, the first question is whether this provider actually supports the capability, and having that answer in a table rather than in someone's memory saves hours.

Implementation patterns

• Three states per capability, not two: supported, approximated (with the approximation described), and unsupported. The middle state is the one that carries the value, because it is where silent wrongness otherwise lives.
• Preserve the raw provider payload alongside the normalised value, so a consumer needing precision can reach through. Discarding it to keep the model clean makes every future investigation harder.
• Extend the model when a difference is genuine and general — one provider revealing a distinction usually means the model was wrong, not that the provider is odd.
• Expose the matrix through the API, not only in documentation, so a consumer can adapt at runtime rather than encoding assumptions.
• Track reliability per provider alongside capability, since consumers care about both and the operational data you already have is more honest than a vendor's claim.
• Pair with per-provider operational policy: timeouts from that provider's own latency distribution, concurrency limits so one slow provider cannot consume every worker, circuit breakers on latency as well as errors, and retry budgets bounded as a fraction of traffic.

Industry example

Financial-data aggregators such as Plaid, shipping aggregators such as Shiprocket and enterprise-integration platforms such as WorkOS all present a normalised interface over a heterogeneous and unreliable set of providers. In each case the normalisation is the product, and the honest declaration of where it breaks down is what makes the product trustworthy rather than merely convenient.

The alternative — a uniform interface that hides the variance — produces the characteristic complaint that the platform "works except for the ones that matter".

Failure scenarios

• Binary supported/unsupported, with approximations presented as full support.
• Raw payload discarded, leaving no way to investigate a discrepancy.
• The matrix maintained manually and drifting from reality as providers change.
• One operational policy across all providers, so one slow provider becomes a platform outage.
• Capabilities inferred from vendor documentation rather than from observed behaviour, which is optimistic in a predictable direction.

Trade-offs

Publishing the matrix exposes the platform's limitations, which sales teams dislike and which is exactly why it builds trust with the engineers who actually integrate. It also creates a maintenance obligation: an inaccurate matrix is worse than none, because it will be relied upon.

The deeper trade is between a clean abstraction and an honest one. A clean abstraction is easier to learn and produces silent wrongness; an honest one is more complex and produces correct integrations — and for anything financial or logistical, correctness wins.

Interview question

"Your normalised transaction model has a category field. Three of your two hundred providers do not supply categories and you infer them. What does your API return for those, and what does the consumer see?"