Companies and roles

A company is a B2B buyer account. Customers join it as employees, and each employee has a role. The same rules apply on the store and admin routes, except that merchants (admin routes) can act on any company and need no buyer permission.

MembershipCopy Anchor Link

• A customer belongs to at most one company.
• Store routes resolve the company from the signed-in customer, so no store path takes a company ID. Use /store/companies/me.
• Removed employees count as having no company.

Company statusCopy Anchor Link

Companies from buyer signup start pending when the company.signup_requires_approval setting is on, otherwise active. Merchants pick pending or active when they create one (default active). Buyer changes on a company that isn't active fail with company_not_active. See Signup and approval for status changes.

Customer groupCopy Anchor Link

Every company gets its own customer group, named after the company. Employees join the group when added and leave it when removed, so price lists and promotions that target the group apply to them.

• Group names are unique, so a taken name gets a suffix: Acme (2), Acme (3), up to Acme (50). Past that, creating or renaming the company fails and you need a different name.
• Renaming the company renames its group the same way.

CurrencyCopy Anchor Link

A company's currency_code must be a currency the store supports. Without one, it gets the store's default currency.

Roles and permissionsCopy Anchor Link

Roles are owner, admin, buyer, and viewer. owner always has every permission. The other roles get the permissions in the company.role_permissions B2B setting, with company-level overrides applied on top.

These are the defaults. Merchants can change them per company with overrides today. Tenant-wide changes need the B2B settings routes, which aren't served yet. Each store endpoint lists the permission it needs in x-waylo-permission. any means any active employee.

Employees added without a role get the company.default_role setting (default buyer).

OwnersCopy Anchor Link

• On store routes, only an owner can give or take the owner role, or remove an owner (owner_required).
• Once a company has an owner, it always keeps at least one active owner (last_owner).
• Nobody can change their own role or remove themselves (self_modification).

Deleting a companyCopy Anchor Link

Deleting a company sets every employee to removed, deletes its addresses, and deletes its customer group, so group price lists and promotions stop applying. Customers stay as plain customers and can join another company. The link rows between orders and the company are kept, but order.company reads as empty once the company is deleted.