Suspension and Lifecycle

Sub-merchant deletion is intentionally not exposed: once a sub-merchant exists, the only way to take them offline is to suspend them. This is a safety property — it keeps balances and obligations recoverable.

There are two layers of switches that gate Connect activity:

Marketplace-level kill-switches — connectEnabled and paused, surfaced on GET /api/connect/settings. Managed by Inflow. Affect every sub-merchant under the marketplace at once.
Sub-merchant-level switch — the suspension flag, toggled by the suspend / resume endpoints below. Self-service. Affects one sub-merchant at a time.

Sub-merchant lifecycle

A sub-merchant is in exactly one of these states at any time:

State	KYC	Wallet	Suspended?	Operable on `X-On-Behalf-Of`?
Pending KYC	`pending`	absent	no	no
Pending wallet	`pending` (or `approved` while wallet provisioning)	absent	no	no
Active	`approved`	present	no	yes
Suspended	`approved`	present	yes	no
Rejected	`rejected`	absent	no	no

A sub-merchant becomes operable on X-On-Behalf-Of only when KYC is approved and they are not suspended. See Acting on Behalf Of for the full rules and error codes.

Suspending a sub-merchant

POST /api/connect/accounts/:subMerchantId/suspend
Authorization: Bearer <inflow_apikey>

After this:

X-On-Behalf-Of calls for that sub-merchant return 403 ON_BEHALF_SUBMERCHANT_NOT_OPERABLE.
New money-movement work for the sub-merchant stops (no new payouts, no settlement processing).
KYC, wallet, and balance are left untouched — suspension is reversible.

Idempotent: suspending an already-suspended account is a no-op and returns the current state.

Resuming a sub-merchant

POST /api/connect/accounts/:subMerchantId/resume
Authorization: Bearer <inflow_apikey>

Clears the suspension. Idempotent — resuming an already-active sub-merchant is a no-op and returns the current state.

When to suspend vs. when to delete

Connect deliberately doesn't expose deletion. To take a sub-merchant offline:

Reason	Recommended action
Seller off-boarded permanently	`suspend` and stop using the `subMerchantId`. Their balance can still be paid out via a Connect support flow.
Compliance flag (your call, not Inflow's)	`suspend` while you investigate, `resume` if cleared.
Sub-merchant hits `rejected` KYC	`suspend` to freeze any pending obligations. They cannot be reactivated — a new sub-merchant (different email) is required.
KYC stuck pending forever	Don't suspend — it's already non-operable. Re-poll `…/kyc/status` to re-issue the link, or delete the record on your side and start a new one with a fresh email.

Marketplace-level kill-switches

Two read-only flags on GET /api/connect/settings affect every sub-merchant at once. Both are managed by Inflow and cannot be toggled via PATCH:

`connectEnabled`

true (default) — Connect is live for your marketplace.
false — every Connect-management route returns 403 CONNECT_DISABLED, and every merchant route called with X-On-Behalf-Of returns 403 ON_BEHALF_CONNECT_DISABLED.

Used when Inflow disables Connect for a specific marketplace (contract terminated, account in remediation, …). Not a short-lived signal.

`paused`

false (default) — normal operation.
true — every Connect-management route returns 403 MARKETPLACE_PAUSED, and every merchant route with X-On-Behalf-Of returns 403 ON_BEHALF_MARKETPLACE_PAUSED. Sub-merchant balances and KYC are preserved.

Used for short-lived holds (compliance review, fraud incident, regulatory request). Expect a clear comms thread from Inflow before this flips.

What happens to in-flight money?

Scenario	Effect
Sub-merchant suspended mid-flow	Already-credited balance stays put. Pending settlement stops until they're resumed. New `X-On-Behalf-Of` payments are rejected.
Marketplace paused	Same as above, but for all sub-merchants at once. The marketplace's own balance is not seized.
`connectEnabled` flipped to false	Same as paused.

Listing pending / rejected accounts

While beta doesn't expose a dedicated ?kycStatus= filter, you can iterate the standard GET /api/connect/accounts and inspect the kycStatus returned per row. For larger marketplaces, also persist kycStatus on your side (it's part of the create / status responses) so you can index against it.

Suspending a marketplace's own operations

The marketplace's own balance (where marketplace fees land) is managed via the standard merchant API — not via the Connect routes. To take your own marketplace offline, contact your Inflow support contact; there is no self-service kill-switch for the marketplace itself.