Seller eligibility & capabilities

Cüte has exactly one definition of "what can this user do". It lives in deriveEligibility (packages/commerce/onboarding/onboarding.eligibility.ts), a pure function over the user's data, and every gate conforms to it: the publish/checkout/bot gates call it directly, and the onboarding projection is derived from the same inputs. It is never mirrored into the JWT — see below.

A capability is enough data AND good standing. See onboarding for the two-axis model (setup progress vs standing).

The three capabilities

Widening rings. Withdrawing needs somewhere for the money to actually land, which an operational account does not by itself guarantee — a Stripe account can be verified with no bank attached.

A few of these surprise people:

• Nothing is asked of a seller before the listing form, on any rail. Who the payment provider pays is asked once, at the first publish, in one dialog: the legal name, birthday and address everywhere (Stripe DE refuses the recipient service agreement for DE accounts, so transfers stay inactive until the person is known), plus the CPF, phone and bank account where the rail wants them (Pagar.me takes them in the recipient payload). The fields are the market's identityRules and the gateway's capabilities, never a market name.
• A parked market fails canList outright (market_unavailable). A preview account in AR can fill in identity fields and still have no seller capability.
• Standing and identity holds are added at the eligibility layer, not in the data requirements. Otherwise a hold would knock a fully set-up seller back down the progress ladder — enforcement leaking into a progress label.

Suspension has teeth

account_status is read by the predicate on every gate, so changing it changes what a user can do immediately:

• a deactivated account is auto-reactivated to active on next login.

This closes the old gap where a suspended seller could still publish, receive orders, and withdraw.

Where each gate is enforced

checkSellerCanList (commerce/listings/listing.service.ts) reads the canonical snapshot and calls deriveEligibility, so the route gate, the publish gate, and the progress checklist can never disagree about who can sell.

Capabilities are NOT in the JWT

Capabilities are never claims. The access-token hook stamps exactly two fields into app_metadata — app_role and country_code — and actively strips can_buy / can_sell / can_withdraw / onboarding_state from any token that carries them.

The reason is staleness: a token lives up to an hour, and a capability that says "can withdraw" an hour after a suspension is a hole. Every gate therefore derives capabilities from live DB state immediately before the mutation, via deriveEligibility over a fresh getOnboardingSnapshot. There is no mirror to keep in sync.

onboarding_state is likewise not a claim, and is not something to gate on in any case: it is a progress label, not standing.

Payment account activation and withdrawal

A provider seller identity — Pagar.me calls it a recipient, Stripe a connected account — is created at the first publish, from the identity dialog, on every rail, and its status is stored in seller_payment_accounts.merchant_status, reached through the user's active seller_accounts row for their derived market. Receiving money unlocks as soon as the payment account exists. Withdrawal additionally requires that account and its provider-owned payout destination to be active. Cüte stores only safe payout metadata; the provider retains full bank credentials.

The account often starts pending at creation and is confirmed active later. The normalized seller.updated provider webhook (handled in payments/services/process-normalized-webhook.service.ts) syncs merchant_status and recomputes the projection, so an account that activates after creation flips canWithdraw on at the next gate check — no token refresh involved, because capabilities are not claims. This is the path that makes withdrawal reachable for accounts that are not active immediately.

Data model

Every input the predicate reads, and where it lives:

Code map