B2B settings
Every tenant setting, its default, and what it controls.
B2B rules are tenant settings with defaults, never code. The backend stores only the settings a merchant has changed. Every other key falls back to its default.
Settings
| Key | Type | Default | Controls |
|---|---|---|---|
company.signup_requires_approval | boolean | false | Companies from signup start pending until a merchant approves them. |
company.default_role | admin, buyer, or viewer | buyer | Role for employees added without one. |
company.role_permissions | Permission lists for admin, buyer, viewer | See roles | What each role can do. owner always has every permission and can't be set. |
company.invite_ttl_hours | integer, 1 or more | 168 | Hours before a company invite expires. |
catalog.visibility | public, login_to_see_prices, or login_to_view | public | Who can browse the catalog and see prices. |
catalog.mode | commerce or catalog_only | commerce | catalog_only turns off cart and checkout. |
quote.enabled | boolean | true | Buyers can request quotes. |
quote.validity_days | integer, 1 or more | 30 | Days a sent quote stays valid. |
company.role_permissions must list all three roles, with no permission repeated. The permissions are manage_company, manage_employees, manage_billing, approve, view_company_orders, view_company_quotes, and shop.
Only company.signup_requires_approval, company.default_role, and company.role_permissions take effect today. The others are in the contract for features still being built (invites, gated catalog, quotes), and changing them has no effect yet.
Store and admin visibility
| Who | Route | Sees |
|---|---|---|
| Merchants | GET /admin/b2b-settings | Every setting, with defaults merged |
| Storefronts | GET /store/b2b-settings | catalog.visibility, catalog.mode, and quote.enabled only |
Storefronts use the public settings as UI hints, such as hiding prices or the quote button. The backend enforces every rule whatever the client shows.
POST /admin/b2b-settings changes the settings you send and leaves the rest alone. It emits b2b-setting.updated with the changed keys.
These three routes are in the API contract but the backend doesn't serve them yet. Until it does, every tenant runs on the defaults above.
Company overrides
A merchant can override some settings for one company, with settings_override on POST /admin/companies/{id}. It replaces the company's whole override object, with no merge, so always send every override the company should keep. Send null to clear them all.
| Key | Override |
|---|---|
company.default_role | Replaces the tenant default for this company. |
company.role_permissions | Replaces the list for each role it names. Roles left out keep the tenant list. |
quote.validity_days | Replaces the tenant default for this company. No effect until quotes ship. |
Any other key is rejected, and so is owner in company.role_permissions. Buyers can't read or change overrides.
curl -X POST http://localhost:9000/admin/companies/comp_123 \
-u "sk_...:" \
-H "Content-Type: application/json" \
-d '{
"settings_override": {
"company.default_role": "viewer",
"company.role_permissions": { "buyer": ["shop", "view_company_orders"] }
}
}'This sets both overrides. Sending only company.role_permissions later would drop the company.default_role override.