> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0356 — Choosing a provider per tenant and market: through the Connection, with a market default

> Accepted · 2026-10-25

## Context

`@Replaces(Port)` binds a custom driver over a port's shipped drivers for the whole container
([0263](https://docs.stackra.figentra.com/adr/0263-di-stays-and-gen-writes-the-wiring.md), [0306](https://docs.stackra.figentra.com/adr/0306-overrides-one-tree-under-src-overrides-and-five-placement-layers.md)
decision 9). It cannot pick a provider per tenant or per country. Payments, SMS, WhatsApp, fiscal clearance, KYC,
shipping, accounting and AI do exactly that: a KSA tenant charges through a KSA gateway, an Academorix tenant may bring
its own SMS account. [0308](https://docs.stackra.figentra.com/adr/0308-integrations-v3-1-provider-descriptions-connection-stores-and-webhooks.md) rule 4
lets a Connection's fields override an Integration's, but that covers credentials, not the choice of provider. The
adapter readiness report asked for one rule before payments and fiscal are built. The owner decided it on 2026-10-25
(round-3 #8, with OS-74), and in round 22 kept Figentra's own provider choices in the Figentra OS ADRs.

## Decision

1. **`@Replaces` stays global.** It swaps the driver class of a port for every tenant in that deployment. It is never
   used to choose a provider per tenant, market or legal entity.
2. **The Connection chooses the provider.** A capability that has more than one provider (a port with several driver
   Integrations) resolves the provider for a call from the tenant's Connection for that capability, found at the scope
   by walking the Integration's declared levels
   ([0308](https://docs.stackra.figentra.com/adr/0308-integrations-v3-1-provider-descriptions-connection-stores-and-webhooks.md) rule 9). The driver bound to
   that Connection's Integration serves the call.
3. **Market default.** When the tenant has no Connection for the capability, the platform's default for the Market
   applies: a platform Connection set per Market and capability
   ([0244](https://docs.stackra.figentra.com/adr/0244-markets-owned-by-pricing.md)). For payments the Market is the checkout's Market, which already carries
   the payment methods and processors (0244 decision 1).
4. **Two ways to get a provider.** For each capability that offers both, the tenant uses either:
   * **platform-provided**: the platform's provider account, through a platform Connection; the tenant pays the
     platform (for example in credits or a platform rate); or
   * **bring your own**: the tenant connects its own provider account from the app market
     ([0355](https://docs.stackra.figentra.com/adr/0355-marketplace-one-integration-with-up-to-five-roles-one-app-market-and-open-to-any-developer.md)) and
     pays the provider directly. Payments ([0357](https://docs.stackra.figentra.com/adr/0357-payments-architecture-ports-gateway-drivers-a-platform-layer-and-a-closed-loop-wallet.md)
     decision 3), messaging (SMS, WhatsApp, push), AI model keys and other provider accounts and OAuth apps
     ([0308](https://docs.stackra.figentra.com/adr/0308-integrations-v3-1-provider-descriptions-connection-stores-and-webhooks.md) rule 11) all use this
     rule. Which plans may bring their own account is the product's choice.
5. **Platform market defaults are data, not code.** The default provider per Market for a capability is set as
   platform configuration, so a change of default is not a release.
6. **Sandboxes.** Sandbox behaviour (test-mode gateways, captured messages, test endpoints) is in
   [0359](https://docs.stackra.figentra.com/adr/0359-modes-and-configuration-environments-display-modes-sandbox-promotion-and-live-records.md) decision 11,
   whichever way the provider was chosen.
7. **Failover** across a capability's providers is a driver feature of the port; on which accounts it is on is the
   product's choice.
8. **Figentra's choices.** Figentra's default providers per Market (for example its SMS defaults), the fees and credits
   it charges, which plans may bring their own accounts, OAuth apps or AI keys, and failover on tenant accounts are
   Figentra OS ADRs [0028](https://docs.os.figentra.com/adr/0028-ai-credits-messaging-credits-and-bring-your-own-providers),
   [0034](https://docs.os.figentra.com/adr/0034-payments-architecture-one-engine-three-layers-and-providers),
   [0035](https://docs.os.figentra.com/adr/0035-figentra-pay-fees-wallets-refunds-disputes-and-reconciliation),
   [0047](https://docs.os.figentra.com/adr/0047-notifications-and-paid-messaging-figentra-service-or-bring-your-own-provider),
   [0049](https://docs.os.figentra.com/adr/0049-integrations-connectors-and-outbound-webhooks) and
   [0067](https://docs.os.figentra.com/adr/0067-ai-data-region-credits-own-keys-and-customer-facing-ai) (owner round 22,
   [0259](https://docs.stackra.figentra.com/adr/0259-module-placement-three-homes.md)).

## Consequences

* Payments, messaging, fiscal, KYC, shipping, accounting and AI share one rule for picking a provider, so no service
  invents its own country switch.
* A new market is a new set of platform Connections and defaults, not a code change.
* Every multi-provider capability needs a port with a driver per provider, each an Integration
  ([0355](https://docs.stackra.figentra.com/adr/0355-marketplace-one-integration-with-up-to-five-roles-one-app-market-and-open-to-any-developer.md)
  decision 1).
* The hosted Connection store with per-tenant encryption (round-3 #10, OS integrations) must exist before any
  per-tenant provider runs in production.

## Enforcement

planned — a `ConnectionContext` driver in `@stackra/integrations` that resolves the tenant Connection, then the market
default; a conformance test per multi-provider port (tenant Connection wins; no Connection gives the market default;
`@Replaces` changes the driver class only); a gen or validator check that refuses `@Replaces` code that branches on the
tenant or the Market.

## Open questions

1. **Which Market keys the default for non-payment capabilities.** For SMS and WhatsApp it could be the tenant's Market
   or the recipient's country; for fiscal it could be the legal entity. Not decided.
2. **Fallback from a failing tenant Connection.** Whether a call falls back to the Figentra-provided provider when the
   tenant's own Connection fails, or refuses, is not decided. OS-219 says connections are never auto-disconnected;
   it does not say whether calls switch provider.
3. **Several tenant Connections for one capability** (for example two gateways in one Market): which serves a call is
   not decided beyond 0308 rule 10 (`connection_ambiguous`).

## Supersedes and sources

Supersedes: none. Reads with [0263](https://docs.stackra.figentra.com/adr/0263-di-stays-and-gen-writes-the-wiring.md),
[0308](https://docs.stackra.figentra.com/adr/0308-integrations-v3-1-provider-descriptions-connection-stores-and-webhooks.md),
[0244](https://docs.stackra.figentra.com/adr/0244-markets-owned-by-pricing.md),
[0219](https://docs.stackra.figentra.com/adr/0219-the-merchant-account-chain-and-registered-price-models.md) decision 2 and
[0156](https://docs.stackra.figentra.com/adr/0156-ai-runtime-provider-drivers-memory-and-guardrails.md). Sources: owner decisions in chat, 2026-10-25:
round-3 questionnaire 8 and 10 (`notes/handover/360/questionnaire-round-3.md`); Commerce questionnaire Answers, 27
(gateways chosen per tenant and market through the Connection); OS answers OS-74, OS-93 and OS-313, and the defaults
OS-18, OS-186, OS-188, OS-202, OS-216 and OS-219 (`notes/handover/os/`); `360/adapter-readiness-and-missing-packages.md`
finding 1 and action 4.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.