@vtex/faststore-plugin-buyer-portal 2.0.26 → 2.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore-plugin-buyer-portal",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "description": "A plugin for faststore with buyer portal",
   "main": "index.js",
   "files": [

package/src/features/contracts/components/ContractListItem/ContractListItem.tsx

@@ -29,10 +29,12 @@ export const ContractListItem = ({
   const displayName = contract.name ?? contract.email;
   const { pushToast } = useUI();
   const { switchContract, loading } = useSwitchContract();
+  const isRemovable = contract.isAttached !== false;
 
   const handleCheckboxClick = (event: React.MouseEvent) => {
     event.stopPropagation();
     event.preventDefault();
+    if (!isRemovable) return;
     onSelect(contract.id, event);
   };
 
@@ -59,10 +61,14 @@ export const ContractListItem = ({
     >
       <div
         data-fs-bp-contract-list-item-checkbox
+        data-fs-bp-contract-list-item-checkbox-disabled={
+          !isRemovable || undefined
+        }
         role="checkbox"
         aria-checked={isSelected}
+        aria-disabled={!isRemovable}
         aria-label={`Select ${displayName ?? "contract"}`}
-        tabIndex={0}
+        tabIndex={isRemovable ? 0 : -1}
         onClick={handleCheckboxClick}
         onKeyDown={(e) =>
           e.key === " " && handleCheckboxClick(e as unknown as React.MouseEvent)
@@ -91,7 +97,7 @@ export const ContractListItem = ({
         <Dropdown>
           <BasicDropdownMenu.Trigger />
           <BasicDropdownMenu>
-            {contract.isDefault ? (
+            {contract.isDefault || !isRemovable ? (
               <DropdownItem disabled>
                 <Icon name="Star" width={16} height={16} />
                 {t("contracts.actions.setAsDefault")}
@@ -105,7 +111,8 @@ export const ContractListItem = ({
             <BasicDropdownMenu.Separator />
             <DropdownItem
               data-fs-bp-dropdown-menu-item-mode="danger"
-              onClick={onRemove}
+              disabled={!isRemovable}
+              onClick={isRemovable ? onRemove : undefined}
             >
               <Icon name="CircleRemove" width={16} height={16} />
               {t("shared.buttons.remove")}

package/src/features/contracts/layouts/ContractListingLayout/ContractListingLayout.tsx

@@ -23,6 +23,7 @@ import { GlobalLayout } from "../../../shared/layouts";
 import { SumaSidebar } from "../../../shared/layouts/SumaPageLayout/SumaSidebar";
 import { useLocalization } from "../../../shared/localization/LocalizationContext";
 import { buyerPortalRoutes } from "../../../shared/utils/buyerPortalRoutes";
+import { contractScopedLink } from "../../../shared/utils/contractScopedLink";
 import { AddContractsDrawer } from "../../components/AddContractsDrawer/AddContractsDrawer";
 import { ConfirmRemoveDrawer } from "../../components/ConfirmRemoveDrawer/ConfirmRemoveDrawer";
 import { ContractSelectAllRow } from "../../components/ContractSelectAllRow";
@@ -169,9 +170,14 @@ export const ContractListingLayout = ({
     },
   });
 
+  const removableIds = new Set(
+    contracts.filter((c) => c.isAttached !== false).map((c) => c.id)
+  );
+
   const handleRequestRemove = (overrideIds?: Set<string>) => {
     const targetIds = overrideIds ?? selectedIds;
-    if (targetIds.size === contracts.length) {
+    if (targetIds.size === 0) return;
+    if (targetIds.size === removableIds.size) {
       openUnableToRemoveDrawer();
       return;
     }
@@ -180,6 +186,7 @@ export const ContractListingLayout = ({
   };
 
   const handleItemRemove = (id: string) => {
+    if (!removableIds.has(id)) return;
     handleRequestRemove(new Set([id]));
   };
 
@@ -215,6 +222,7 @@ export const ContractListingLayout = ({
   });
 
   const handleSetDefault = (contractId: string) => {
+    if (!removableIds.has(contractId)) return;
     setDefaultContract({ orgUnitId: orgUnit.id, contractId })?.catch(() => {});
   };
 
@@ -267,9 +275,14 @@ export const ContractListingLayout = ({
     selectedIds.has(id)
   ).length;
 
+  // Contracts sourced from the legacy fallback (never attached) can't be
+  // selected for bulk removal — the BFF has no attach relation to detach.
+  const removableFilteredIds = filteredIds.filter((id) => removableIds.has(id));
+
   const handleSelect = (id: string, event: React.MouseEvent) => {
+    if (!removableIds.has(id)) return;
     if (event.shiftKey) {
-      handleShiftClick(id, filteredIds);
+      handleShiftClick(id, removableFilteredIds);
     } else {
       handleModifierClick(id);
     }
@@ -279,14 +292,14 @@ export const ContractListingLayout = ({
     if (selectedInFiltered > 0) {
       clearSelection();
     } else {
-      handleSelectAll(filteredIds);
+      handleSelectAll(removableFilteredIds);
     }
   };
 
   const handleKeyDown = (event: React.KeyboardEvent) => {
     if ((event.metaKey || event.ctrlKey) && event.key === "a") {
       event.preventDefault();
-      handleSelectAll(filteredIds);
+      handleSelectAll(removableFilteredIds);
     }
   };
 
@@ -342,7 +355,7 @@ export const ContractListingLayout = ({
             <BasicCard
               data-fs-bp-contracts-settings-card
               footerMessage={t("orgUnitDetails.links.manageContractSettings")}
-              footerLink={buyerPortalRoutes.profileDetails({
+              footerLink={contractScopedLink(buyerPortalRoutes.profileDetails, {
                 orgUnitId: orgUnit.id,
                 contractId: defaultContractId,
               })}

package/src/features/contracts/layouts/ContractListingLayout/ContractSettingsNav.tsx

@@ -4,6 +4,7 @@ import { AccountingFieldDropdown } from "../../../accounting-fields/components";
 import { checkAccountingFieldIsEmpty } from "../../../accounting-fields/utils";
 import { Icon } from "../../../shared/components";
 import { buyerPortalRoutes } from "../../../shared/utils/buyerPortalRoutes";
+import { contractScopedLink } from "../../../shared/utils/contractScopedLink";
 
 import type { AccountingField } from "../../../accounting-fields/types";
 import type { LocalizeFn } from "../../../shared/localization/types";
@@ -35,23 +36,23 @@ export const buildContractSettingsNavItems = ({
   return [
     {
       name: t("contracts.nav.basicInformation"),
-      link: buyerPortalRoutes.profileDetails(linkParams),
+      link: contractScopedLink(buyerPortalRoutes.profileDetails, linkParams),
     },
     {
       name: t("layouts.navigation.addresses"),
-      link: buyerPortalRoutes.addresses(linkParams),
+      link: contractScopedLink(buyerPortalRoutes.addresses, linkParams),
     },
     {
       name: t("layouts.navigation.paymentMethods"),
-      link: buyerPortalRoutes.paymentMethods(linkParams),
+      link: contractScopedLink(buyerPortalRoutes.paymentMethods, linkParams),
     },
     {
       name: t("layouts.navigation.creditCards"),
-      link: buyerPortalRoutes.creditCards(linkParams),
+      link: contractScopedLink(buyerPortalRoutes.creditCards, linkParams),
     },
     {
       name: t("contracts.nav.assortment"),
-      link: buyerPortalRoutes.productAssortment(linkParams),
+      link: contractScopedLink(buyerPortalRoutes.productAssortment, linkParams),
     },
     {
       name: t("layouts.navigation.accountingFields"),
@@ -59,10 +60,14 @@ export const buildContractSettingsNavItems = ({
       submenu: {
         items: accountingFields.map((field) => ({
           name: field.name,
-          link: buyerPortalRoutes.accountingFields({
-            ...linkParams,
-            accountingFieldId: field.id,
-          }),
+          link: contractScopedLink(
+            (params) =>
+              buyerPortalRoutes.accountingFields({
+                ...params,
+                accountingFieldId: field.id,
+              }),
+            linkParams
+          ),
           hasNotification: checkAccountingFieldIsEmpty(field),
           actions: (
             <AccountingFieldDropdown

package/src/features/contracts/layouts/ContractListingLayout/contract-listing-layout.scss

@@ -89,6 +89,14 @@
         flex-shrink: 0;
         color: var(--fs-bp-color-brand);
       }
+
+      [data-fs-bp-suma-sidebar-identity-contract] {
+        @include text-style("body");
+        color: var(--fs-bp-color-neutral-8);
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
     }
   }
 
@@ -437,6 +445,11 @@
         outline: 2px solid var(--fs-bp-color-brand);
         outline-offset: 2px;
       }
+
+      &[data-fs-bp-contract-list-item-checkbox-disabled] {
+        cursor: not-allowed;
+        opacity: 0.4;
+      }
     }
 
     [data-fs-bp-letter-highlight] {

package/src/features/contracts/services/__tests__/list-unit-contracts.service.test.ts

@@ -0,0 +1,117 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../list-attached-contracts.service", () => ({
+  listAttachedContractsService: vi.fn(),
+}));
+
+vi.mock("../get-contracts-org-by-unit-id.service", () => ({
+  getContractsByOrgUnitIdService: vi.fn(),
+}));
+
+import { getContractsByOrgUnitIdService } from "../get-contracts-org-by-unit-id.service";
+import { listAttachedContractsService } from "../list-attached-contracts.service";
+import { listUnitContractsService } from "../list-unit-contracts.service";
+
+import type { ContractData } from "../../types";
+
+const listAttachedContractsMock = vi.mocked(listAttachedContractsService);
+const getContractsByOrgUnitIdMock = vi.mocked(getContractsByOrgUnitIdService);
+
+const cookie = "VtexIdclientAutCookie=test-token";
+const orgUnitId = "unit-123";
+
+function contract(id: string, isDefault = false): ContractData {
+  return {
+    id,
+    name: id,
+    email: `${id}@b.com`,
+    isActive: true,
+    creationDate: "2026-01-01",
+    isDefault,
+  };
+}
+
+describe("listUnitContractsService", () => {
+  beforeEach(() => {
+    listAttachedContractsMock.mockReset();
+    getContractsByOrgUnitIdMock.mockReset();
+  });
+
+  it("returns the attached listing when the unit has attached contracts", async () => {
+    listAttachedContractsMock.mockResolvedValue([
+      contract("a", true),
+      contract("b"),
+    ]);
+
+    const result = await listUnitContractsService({ orgUnitId, cookie });
+
+    expect(result.map((c) => c.id)).toEqual(["a", "b"]);
+    expect(getContractsByOrgUnitIdMock).not.toHaveBeenCalled();
+  });
+
+  it("flags attached contracts as isAttached: true", async () => {
+    listAttachedContractsMock.mockResolvedValue([contract("a", true)]);
+
+    const result = await listUnitContractsService({ orgUnitId, cookie });
+
+    expect(result.map((c) => c.isAttached)).toEqual([true]);
+  });
+
+  it("falls back to the legacy unit-contracts listing when nothing is attached", async () => {
+    listAttachedContractsMock.mockResolvedValue([]);
+    getContractsByOrgUnitIdMock.mockResolvedValue([
+      contract("legacy-1"),
+      contract("legacy-2"),
+    ]);
+
+    const result = await listUnitContractsService({ orgUnitId, cookie });
+
+    expect(result.map((c) => c.id)).toEqual(["legacy-1", "legacy-2"]);
+    expect(getContractsByOrgUnitIdMock).toHaveBeenCalledWith({
+      orgUnitId,
+      cookie,
+    });
+  });
+
+  it("flags legacy fallback contracts as isAttached: false", async () => {
+    listAttachedContractsMock.mockResolvedValue([]);
+    getContractsByOrgUnitIdMock.mockResolvedValue([contract("legacy-1")]);
+
+    const result = await listUnitContractsService({ orgUnitId, cookie });
+
+    expect(result.map((c) => c.isAttached)).toEqual([false]);
+  });
+
+  it("flags the first fallback contract as default when none is flagged", async () => {
+    listAttachedContractsMock.mockResolvedValue([]);
+    getContractsByOrgUnitIdMock.mockResolvedValue([
+      contract("legacy-1"),
+      contract("legacy-2"),
+    ]);
+
+    const result = await listUnitContractsService({ orgUnitId, cookie });
+
+    expect(result.map((c) => c.isDefault)).toEqual([true, false]);
+  });
+
+  it("honors an explicit default in the fallback listing", async () => {
+    listAttachedContractsMock.mockResolvedValue([]);
+    getContractsByOrgUnitIdMock.mockResolvedValue([
+      contract("legacy-1"),
+      contract("legacy-2", true),
+    ]);
+
+    const result = await listUnitContractsService({ orgUnitId, cookie });
+
+    expect(result.map((c) => c.isDefault)).toEqual([false, true]);
+  });
+
+  it("returns an empty list when both listings are empty", async () => {
+    listAttachedContractsMock.mockResolvedValue([]);
+    getContractsByOrgUnitIdMock.mockResolvedValue([]);
+
+    const result = await listUnitContractsService({ orgUnitId, cookie });
+
+    expect(result).toEqual([]);
+  });
+});

package/src/features/contracts/services/__tests__/resolve-attached-contract.service.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../list-unit-contracts.service", () => ({
+  listUnitContractsService: vi.fn(),
+}));
+
+vi.mock("../../../shared/services/logger", () => ({
+  logError: vi.fn(),
+}));
+
+import { logError } from "../../../shared/services/logger";
+import { listUnitContractsService } from "../list-unit-contracts.service";
+import { resolveAttachedContractService } from "../resolve-attached-contract.service";
+
+import type { ContractData } from "../../types";
+
+const listUnitContractsMock = vi.mocked(listUnitContractsService);
+const logErrorMock = vi.mocked(logError);
+
+const cookie = "VtexIdclientAutCookie=test-token";
+const orgUnitId = "unit-123";
+
+function contract(id: string, isDefault = false): ContractData {
+  return {
+    id,
+    name: id,
+    email: `${id}@b.com`,
+    isActive: true,
+    creationDate: "2026-01-01",
+    isDefault,
+  };
+}
+
+describe("resolveAttachedContractService", () => {
+  beforeEach(() => {
+    listUnitContractsMock.mockReset();
+    logErrorMock.mockReset();
+  });
+
+  it("returns the URL's contract when it belongs to the unit", async () => {
+    listUnitContractsMock.mockResolvedValue([
+      contract("a", true),
+      contract("b"),
+    ]);
+
+    const result = await resolveAttachedContractService({
+      orgUnitId,
+      contractId: "b",
+      cookie,
+    });
+
+    expect(result?.id).toBe("b");
+  });
+
+  it("returns the unit's default contract when no contractId is given", async () => {
+    listUnitContractsMock.mockResolvedValue([
+      contract("a"),
+      contract("b", true),
+    ]);
+
+    const result = await resolveAttachedContractService({ orgUnitId, cookie });
+
+    expect(result?.id).toBe("b");
+  });
+
+  it("falls back to the unit's default when the URL's contract belongs to another unit", async () => {
+    listUnitContractsMock.mockResolvedValue([
+      contract("a", true),
+      contract("b"),
+    ]);
+
+    const result = await resolveAttachedContractService({
+      orgUnitId,
+      contractId: "foreign-contract",
+      cookie,
+    });
+
+    expect(result?.id).toBe("a");
+  });
+
+  it("falls back to the first contract when none is flagged as default", async () => {
+    listUnitContractsMock.mockResolvedValue([contract("a"), contract("b")]);
+
+    const result = await resolveAttachedContractService({ orgUnitId, cookie });
+
+    expect(result?.id).toBe("a");
+  });
+
+  it("returns null when the unit has no contracts", async () => {
+    listUnitContractsMock.mockResolvedValue([]);
+
+    const result = await resolveAttachedContractService({ orgUnitId, cookie });
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when the lookup fails instead of breaking the page", async () => {
+    listUnitContractsMock.mockRejectedValue(new Error("BFF unavailable"));
+
+    const result = await resolveAttachedContractService({ orgUnitId, cookie });
+
+    expect(result).toBeNull();
+  });
+
+  it("logs the error when the lookup fails", async () => {
+    listUnitContractsMock.mockRejectedValue(new Error("BFF unavailable"));
+
+    await resolveAttachedContractService({ orgUnitId, cookie });
+
+    expect(logErrorMock).toHaveBeenCalledWith(
+      "Failed to resolve attached contract",
+      expect.objectContaining({
+        orgUnitId,
+        error_message: "BFF unavailable",
+      })
+    );
+  });
+});

package/src/features/contracts/services/index.ts

@@ -12,6 +12,16 @@ export { getContractDetailsService } from "./get-contract-details.service";
 
 export { listAttachedContractsService } from "./list-attached-contracts.service";
 
+export {
+  listUnitContractsService,
+  type ListUnitContractsServiceProps,
+} from "./list-unit-contracts.service";
+
+export {
+  resolveAttachedContractService,
+  type ResolveAttachedContractServiceProps,
+} from "./resolve-attached-contract.service";
+
 export { listAvailableContractsService } from "./list-available-contracts.service";
 
 export {

package/src/features/contracts/services/list-unit-contracts.service.ts

@@ -0,0 +1,44 @@
+import { getContractsByOrgUnitIdService } from "./get-contracts-org-by-unit-id.service";
+import { listAttachedContractsService } from "./list-attached-contracts.service";
+
+import type { ContractData } from "../types";
+
+export type ListUnitContractsServiceProps = {
+  orgUnitId: string;
+  cookie: string;
+};
+
+/**
+ * Lists the contracts a unit operates under. The SUMA attach listing is the
+ * source of truth, but units that predate the attach flow have nothing
+ * explicitly attached — for those, fall back to the legacy unit-contracts
+ * endpoint (`units/<id>/contracts`), which is what the pre-SUMA portal
+ * displayed. Never fall back to the unit's `customerGroup.customerIds`:
+ * those mirror the session's customer group, not the unit's own contracts.
+ * The first fallback contract is flagged as default when none is, mirroring
+ * what listAttachedContractsService does for an unflagged BFF response.
+ * Fallback contracts are flagged `isAttached: false` — callers must treat
+ * them as read-only (no attach/detach actions), since the BFF has no
+ * attach relation to operate on for them.
+ */
+export const listUnitContractsService = async ({
+  orgUnitId,
+  cookie,
+}: ListUnitContractsServiceProps): Promise<ContractData[]> => {
+  const attached = await listAttachedContractsService({ orgUnitId, cookie });
+
+  if (attached?.length) {
+    return attached.map((contract) => ({ ...contract, isAttached: true }));
+  }
+
+  const contracts =
+    (await getContractsByOrgUnitIdService({ orgUnitId, cookie })) ?? [];
+
+  const hasExplicitDefault = contracts.some((contract) => contract.isDefault);
+
+  return contracts.map((contract, index) => ({
+    ...contract,
+    isDefault: hasExplicitDefault ? Boolean(contract.isDefault) : index === 0,
+    isAttached: false,
+  }));
+};

package/src/features/contracts/services/resolve-attached-contract.service.ts

@@ -0,0 +1,53 @@
+import { logError } from "../../shared/services/logger";
+
+import { listUnitContractsService } from "./list-unit-contracts.service";
+
+import type { ContractData } from "../types";
+
+export type ResolveAttachedContractServiceProps = {
+  orgUnitId: string;
+  /** contractId carried in the URL — may be absent or belong to another unit */
+  contractId?: string;
+  cookie: string;
+};
+
+/**
+ * Resolves which contract the sidebar of an org-unit-scoped page should link
+ * to: the URL's contractId when it belongs to the unit, otherwise the unit's
+ * default contract. Contracts come from listUnitContractsService (attached
+ * listing, legacy unit contracts as fallback). Returns null when the unit has
+ * no resolvable contract (or the lookup fails) — callers must then avoid
+ * building contract-scoped URLs, since an empty contractId segment makes the
+ * path fall into the home catch-all route and 302 the user to their root org
+ * unit.
+ */
+export const resolveAttachedContractService = async ({
+  orgUnitId,
+  contractId,
+  cookie,
+}: ResolveAttachedContractServiceProps): Promise<ContractData | null> => {
+  let contracts: ContractData[];
+
+  try {
+    contracts = await listUnitContractsService({ orgUnitId, cookie });
+  } catch (error) {
+    // The contract only feeds sidebar links/identity; the page's own data
+    // must still render if this lookup fails. Log it though — otherwise a
+    // transient BFF 5xx is indistinguishable from "unit has no contract".
+    logError("Failed to resolve attached contract", {
+      orgUnitId,
+      error_message: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+
+  if (!contracts.length) {
+    return null;
+  }
+
+  return (
+    contracts.find((contract) => contract.id === contractId) ??
+    contracts.find((contract) => contract.isDefault) ??
+    contracts[0]
+  );
+};

package/src/features/contracts/types/ContractData.ts

@@ -4,6 +4,8 @@ export type ContractData = {
   email: string;
   isActive: boolean;
   isDefault?: boolean;
+  /** False when sourced from the legacy unit-contracts fallback (never explicitly attached) — undefined/true means attached. */
+  isAttached?: boolean;
   creationDate: string;
   salesRepresentative?: string;
   imageUrl?: string;

package/src/features/org-units/layouts/OrgUnitDetailsLayout/OrgUnitDetailsLayout.tsx

@@ -28,6 +28,7 @@ import { useMediaQuery } from "../../../shared/hooks/useMediaQuery";
 import { GlobalLayout } from "../../../shared/layouts";
 import { useLocalization } from "../../../shared/localization/LocalizationContext";
 import {
+  contractScopedLink,
   getContractSettingsLinks,
   getFinanceSettingsLinks,
   getOrganizationSettingsLinks,
@@ -127,10 +128,14 @@ export const OrgUnitsDetailsLayout = ({
     submenu: {
       items: (listAccountingFieldData ?? []).map((item) => ({
         name: item.name,
-        link: buyerPortalRoutes.accountingFields({
-          ...linkParams,
-          accountingFieldId: item.id,
-        }),
+        link: contractScopedLink(
+          (params) =>
+            buyerPortalRoutes.accountingFields({
+              ...params,
+              accountingFieldId: item.id,
+            }),
+          linkParams
+        ),
         hasNotification: checkAccountingFieldIsEmpty(item),
         actions: (
           <AccountingFieldDropdown
@@ -261,7 +266,7 @@ export const OrgUnitsDetailsLayout = ({
             <BasicCard
               data-fs-bp-contracts-settings-card
               footerMessage={t("orgUnitDetails.links.manageContractSettings")}
-              footerLink={buyerPortalRoutes.profileDetails({
+              footerLink={contractScopedLink(buyerPortalRoutes.profileDetails, {
                 orgUnitId: orgUnit.id,
                 contractId: singleContract?.id ?? "",
               })}
@@ -345,9 +350,9 @@ export const OrgUnitsDetailsLayout = ({
             footerMessage={t(
               "orgUnitDetails.links.manageFinanceAndComplianceSettings"
             )}
-            footerLink={buyerPortalRoutes.buyingPolicies({
+            footerLink={contractScopedLink(buyerPortalRoutes.buyingPolicies, {
               orgUnitId: orgUnit.id,
-              contractId: contracts[0]?.id,
+              contractId: contracts[0]?.id ?? "",
             })}
             enableFooter
           >

package/src/features/profile/layouts/ProfileLayout/ProfileLayout.tsx

@@ -1,7 +1,14 @@
 import { Fragment } from "react";
 
+import { OrgUnitBreadcrumb } from "../../../org-units/components";
+import {
+  MAX_DESKTOP_BREADCRUMB_ITEMS,
+  MAX_MOBILE_BREADCRUMB_ITEMS,
+  QUERY_TABLET,
+} from "../../../org-units/layouts/OrgUnitDetailsLayout/utils";
 import { HeaderInside } from "../../../shared/components";
 import { useBuyerPortal } from "../../../shared/hooks";
+import { useMediaQuery } from "../../../shared/hooks/useMediaQuery";
 import { GlobalLayout, ContractTabsLayout } from "../../../shared/layouts";
 import { useLocalization } from "../../../shared/localization/LocalizationContext";
 
@@ -15,7 +22,12 @@ export type ProfileLayoutProps = {
 
 export const ProfileLayout = ({ data }: ProfileLayoutProps) => {
   const { t } = useLocalization();
-  const { currentOrgUnit: orgUnit } = useBuyerPortal();
+  const {
+    currentOrgUnit: orgUnit,
+    currentUser,
+    featureFlags,
+  } = useBuyerPortal();
+  const isMobile = useMediaQuery(QUERY_TABLET);
 
   const rows = getProfileDetailRows(data);
 
@@ -29,6 +41,23 @@ export const ProfileLayout = ({ data }: ProfileLayoutProps) => {
         pageName={t("shared.labels.contract")}
       >
         <section data-fs-bp-profile>
+          {/* Under SUMA this page is the unit's landing page, so identify
+              which unit the user is in — a child's profile is otherwise
+              indistinguishable from the root's when they share contracts. */}
+          {featureFlags?.suma && orgUnit && (
+            <HeaderInside data-fs-bp-profile-breadcrumb>
+              <OrgUnitBreadcrumb
+                userId={currentUser?.id ?? ""}
+                userRoles={currentUser?.roles ?? []}
+                orgUnit={orgUnit}
+                maxItems={
+                  isMobile
+                    ? MAX_MOBILE_BREADCRUMB_ITEMS
+                    : MAX_DESKTOP_BREADCRUMB_ITEMS
+                }
+              />
+            </HeaderInside>
+          )}
           <HeaderInside title={t("profile.titles.profile")} />
 
           {data && (

package/src/features/shared/layouts/SumaPageLayout/FullSidebarNav.tsx

@@ -10,6 +10,7 @@ import { Icon, VerticalNav } from "../../components";
 import { useBuyerPortal, useDrawerProps } from "../../hooks";
 import { useLocalization } from "../../localization/LocalizationContext";
 import {
+  contractScopedLink,
   getContractSettingsLinks,
   getFinanceSettingsLinks,
   getOrganizationSettingsLinks,
@@ -82,10 +83,14 @@ export const FullSidebarNav = ({
     submenu: {
       items: (listAccountingFieldData ?? []).map((item) => ({
         name: item.name,
-        link: buyerPortalRoutes.accountingFields({
-          ...linkParams,
-          accountingFieldId: item.id,
-        }),
+        link: contractScopedLink(
+          (params) =>
+            buyerPortalRoutes.accountingFields({
+              ...params,
+              accountingFieldId: item.id,
+            }),
+          linkParams
+        ),
         hasNotification: checkAccountingFieldIsEmpty(item),
         actions: (
           <AccountingFieldDropdown

package/src/features/shared/layouts/SumaPageLayout/SumaSidebar.tsx

@@ -23,12 +23,18 @@ export const SumaSidebar = ({
   showBackLink = false,
   loading = false,
 }: SumaSidebarProps) => {
-  const { featureFlags, currentContract } = useBuyerPortal();
+  const { featureFlags, currentContract, currentOrgUnit } = useBuyerPortal();
   const { t } = useLocalization();
   const contractsUrl = buyerPortalRoutes.contracts({ orgUnitId });
 
+  // Identify WHERE the user is (the org unit), not just which contract they
+  // operate under — a child unit sharing its contracts with the root org is
+  // otherwise indistinguishable from it. The contract becomes a secondary
+  // line; contract-only identity is kept for pages with no unit context.
   const contractName = currentContract?.name ?? currentContract?.email ?? "";
-  const showIdentity = variant === "full" && !!contractName;
+  const unitName = currentOrgUnit?.name ?? "";
+  const identityName = unitName || contractName;
+  const showIdentity = variant === "full" && !!identityName;
 
   return (
     <aside
@@ -48,10 +54,10 @@ export const SumaSidebar = ({
 
       {showIdentity && (
         <div data-fs-bp-suma-sidebar-identity>
-          <LetterHighlight size="large" letter={contractName} />
+          <LetterHighlight size="large" letter={identityName} />
           <div data-fs-bp-suma-sidebar-identity-row>
-            <span data-fs-bp-suma-sidebar-identity-name>{contractName}</span>
-            {currentContract?.isDefault && (
+            <span data-fs-bp-suma-sidebar-identity-name>{identityName}</span>
+            {!unitName && currentContract?.isDefault && (
               <Icon
                 name="Default"
                 width={20}
@@ -61,6 +67,22 @@ export const SumaSidebar = ({
               />
             )}
           </div>
+          {unitName && contractName && (
+            <div data-fs-bp-suma-sidebar-identity-row>
+              <span data-fs-bp-suma-sidebar-identity-contract>
+                {contractName}
+              </span>
+              {currentContract?.isDefault && (
+                <Icon
+                  name="Default"
+                  width={16}
+                  height={16}
+                  data-fs-bp-suma-sidebar-identity-default
+                  aria-label="Default contract"
+                />
+              )}
+            </div>
+          )}
         </div>
       )}
 

package/src/features/shared/utils/__tests__/contractScopedLink.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+
+import { buyerPortalRoutes } from "../buyerPortalRoutes";
+import { contractScopedLink } from "../contractScopedLink";
+
+describe("contractScopedLink", () => {
+  it("builds the contract-scoped URL when a contractId is known", () => {
+    expect(
+      contractScopedLink(buyerPortalRoutes.addresses, {
+        orgUnitId: "unit-1",
+        contractId: "contract-1",
+      })
+    ).toBe("/pvt/organization-account/addresses/unit-1/contract-1");
+  });
+
+  it("falls back to the unit's contracts listing when contractId is empty", () => {
+    // An empty contractId would render `/addresses/unit-1/`, which the home
+    // catch-all route captures and 302s to the user's root org unit.
+    expect(
+      contractScopedLink(buyerPortalRoutes.addresses, {
+        orgUnitId: "unit-1",
+        contractId: "",
+      })
+    ).toBe("/pvt/organization-account/contracts/unit-1");
+  });
+
+  it("supports builders with extra params via a wrapping arrow", () => {
+    expect(
+      contractScopedLink(
+        (params) =>
+          buyerPortalRoutes.accountingFields({
+            ...params,
+            accountingFieldId: "field-1",
+          }),
+        { orgUnitId: "unit-1", contractId: "" }
+      )
+    ).toBe("/pvt/organization-account/contracts/unit-1");
+  });
+});

package/src/features/shared/utils/__tests__/resolveContractId.test.ts

@@ -11,13 +11,22 @@ const orgUnit = {
 } as OrgUnitBasicData;
 
 describe("resolveContractId", () => {
-  it("prefers the URL's contractId over context", () => {
+  it("prefers the loader-validated currentContract over the URL's contractId", () => {
     expect(
       resolveContractId({
         queryContractId: "contract-c",
         currentContract: contract,
         currentOrgUnit: orgUnit,
       })
+    ).toBe("contract-b");
+  });
+
+  it("uses the URL's contractId when no currentContract is resolved", () => {
+    expect(
+      resolveContractId({
+        queryContractId: "contract-c",
+        currentOrgUnit: orgUnit,
+      })
     ).toBe("contract-c");
   });
 
@@ -25,7 +34,6 @@ describe("resolveContractId", () => {
     expect(
       resolveContractId({
         queryContractId: ["contract-c", "contract-d"],
-        currentContract: contract,
         currentOrgUnit: orgUnit,
       })
     ).toBe("contract-c");

package/src/features/shared/utils/constants.ts

@@ -22,4 +22,4 @@ export const SCOPE_KEYS = {
   CREDIT_CARDS: "creditCards",
 } as const;
 
-export const CURRENT_VERSION = "2.0.26";
+export const CURRENT_VERSION = "2.0.27";

package/src/features/shared/utils/contractScopedLink.ts

@@ -0,0 +1,16 @@
+import { buyerPortalRoutes } from "./buyerPortalRoutes";
+
+/**
+ * Builds a contract-scoped URL, falling back to the unit's contracts listing
+ * when no contractId is known. An empty contractId would otherwise produce a
+ * URL with an empty segment, which the home catch-all route
+ * (`/pvt/organization-account/[[...contractMode]]`) captures and 302s to the
+ * user's root org unit — bouncing them out of the unit they were browsing.
+ */
+export const contractScopedLink = (
+  buildLink: (params: { orgUnitId: string; contractId: string }) => string,
+  { orgUnitId, contractId }: { orgUnitId: string; contractId: string }
+) =>
+  contractId
+    ? buildLink({ orgUnitId, contractId })
+    : buyerPortalRoutes.contracts({ orgUnitId });

package/src/features/shared/utils/getContractSettingsLinks.ts

@@ -1,12 +1,10 @@
 import { buyerPortalRoutes } from "./buyerPortalRoutes";
+import { contractScopedLink } from "./contractScopedLink";
 
 import type { LocalizeFn } from "../localization/types";
 
 export const getContractSettingsLinks = (
-  {
-    orgUnitId,
-    contractId,
-  }: {
+  linkParams: {
     orgUnitId: string;
     contractId: string;
   },
@@ -14,22 +12,22 @@ export const getContractSettingsLinks = (
 ) => [
   {
     name: t("layouts.navigation.profile"),
-    link: buyerPortalRoutes.profileDetails({ orgUnitId, contractId }),
+    link: contractScopedLink(buyerPortalRoutes.profileDetails, linkParams),
   },
   {
     name: t("layouts.navigation.addresses"),
-    link: buyerPortalRoutes.addresses({ orgUnitId, contractId }),
+    link: contractScopedLink(buyerPortalRoutes.addresses, linkParams),
   },
   {
     name: t("layouts.navigation.paymentMethods"),
-    link: buyerPortalRoutes.paymentMethods({ orgUnitId, contractId }),
+    link: contractScopedLink(buyerPortalRoutes.paymentMethods, linkParams),
   },
   {
     name: t("layouts.navigation.creditCards"),
-    link: buyerPortalRoutes.creditCards({ orgUnitId, contractId }),
+    link: contractScopedLink(buyerPortalRoutes.creditCards, linkParams),
   },
   {
     name: t("layouts.navigation.assortments"),
-    link: buyerPortalRoutes.productAssortment({ orgUnitId, contractId }),
+    link: contractScopedLink(buyerPortalRoutes.productAssortment, linkParams),
   },
 ];

package/src/features/shared/utils/getFinanceSettingsLinks.ts

@@ -1,12 +1,10 @@
 import { buyerPortalRoutes } from "./buyerPortalRoutes";
+import { contractScopedLink } from "./contractScopedLink";
 
 import type { LocalizeFn } from "../localization/types";
 
 export const getFinanceSettingsLinks = (
-  {
-    orgUnitId,
-    contractId,
-  }: {
+  linkParams: {
     orgUnitId: string;
     contractId: string;
   },
@@ -14,10 +12,10 @@ export const getFinanceSettingsLinks = (
 ) => [
   {
     name: t("layouts.navigation.budgets"),
-    link: buyerPortalRoutes.budgets({ orgUnitId, contractId }),
+    link: contractScopedLink(buyerPortalRoutes.budgets, linkParams),
   },
   {
     name: t("layouts.navigation.buyingPolicies"),
-    link: buyerPortalRoutes.buyingPolicies({ orgUnitId, contractId }),
+    link: contractScopedLink(buyerPortalRoutes.buyingPolicies, linkParams),
   },
 ];

package/src/features/shared/utils/index.ts

@@ -21,6 +21,7 @@ export {
 export { maskCardNumber, maskCVV, maskExpirationDate } from "./creditCard";
 export { formatCurrency } from "./formatCurrency";
 export { getClientContext, type ClientContext } from "./getClientContext";
+export { contractScopedLink } from "./contractScopedLink";
 export { getContractSettingsLinks } from "./getContractSettingsLinks";
 export { getFinanceSettingsLinks } from "./getFinanceSettingsLinks";
 export {

package/src/features/shared/utils/resolveContractId.ts

@@ -9,8 +9,11 @@ export type ResolveContractIdParams = {
 
 /**
  * Single source of truth for which contract the sidebar should link to.
- * The URL's `contractId` (when present) always wins; `customerIds[0]` is a
- * last resort for direct/bookmarked visits where nothing else is known.
+ * `currentContract` wins when the loader resolved one — loaders validate it
+ * against the unit's attached contracts (honoring the URL's `contractId`
+ * when attached), so it is more trustworthy than the raw URL param, which
+ * may carry a contract from another org unit. `customerIds[0]` is a last
+ * resort for flows whose loaders don't resolve a contract.
  */
 export const resolveContractId = ({
   queryContractId,
@@ -22,8 +25,8 @@ export const resolveContractId = ({
     : queryContractId;
 
   return (
-    fromQuery ||
     currentContract?.id ||
+    fromQuery ||
     currentOrgUnit?.customerGroup.customerIds[0] ||
     ""
   );

package/src/pages/contracts.tsx

@@ -1,5 +1,5 @@
 import { ContractListingLayout } from "../features/contracts/layouts/ContractListingLayout/ContractListingLayout";
-import { listAttachedContractsService } from "../features/contracts/services";
+import { listUnitContractsService } from "../features/contracts/services";
 import { getOrgUnitBasicDataService } from "../features/org-units/services";
 import { withErrorBoundary } from "../features/shared/components";
 import { ErrorTabsLayout } from "../features/shared/layouts/ErrorTabsLayout/ErrorTabsLayout";
@@ -65,7 +65,7 @@ const loaderFunction = async (
 
       const [orgUnit, contracts, user, localizationLabels] = await Promise.all([
         getOrgUnitBasicDataService({ id: orgUnitId, cookie }),
-        listAttachedContractsService({ orgUnitId, cookie }),
+        listUnitContractsService({ orgUnitId, cookie }),
         getUserByIdService({ orgUnitId, userId, cookie }),
         getLocalizationLabelsService({
           entryIds: [

package/src/pages/org-unit-details.tsx

@@ -1,4 +1,7 @@
-import { getContractsByOrgUnitIdService } from "../features/contracts/services";
+import {
+  getContractsByOrgUnitIdService,
+  resolveAttachedContractService,
+} from "../features/contracts/services";
 import { OrgUnitsDetailsLayout } from "../features/org-units/layouts";
 import {
   getOrgUnitBasicDataService,
@@ -71,7 +74,24 @@ const loaderFunction = async (
     const featureFlags = await getBuyerPortalFeatureFlags(cookie);
 
     if (featureFlags?.suma) {
-      const location = buyerPortalRoutes.contracts({ orgUnitId, contractId });
+      // Under SUMA the unit's landing page is its Contract Information
+      // (profile) — the SUMA counterpart of this details page, with the full
+      // sidebar (Addresses, Payment methods, …). Resolve which contract that
+      // is for THIS unit instead of trusting the URL's contractId, which may
+      // carry the unit the user navigated from. Units with no resolvable
+      // contract land on their contracts listing, where admins can attach one.
+      const contract = await resolveAttachedContractService({
+        orgUnitId,
+        contractId,
+        cookie,
+      });
+
+      const location = contract
+        ? buyerPortalRoutes.profileDetails({
+            orgUnitId,
+            contractId: contract.id,
+          })
+        : buyerPortalRoutes.contracts({ orgUnitId });
 
       data.res?.writeHead(302, { Location: location });
       data.res?.end();

package/src/pages/org-units.tsx

@@ -1,4 +1,7 @@
-import { getContractDetailsService } from "../features/contracts/services";
+import {
+  getContractDetailsService,
+  resolveAttachedContractService,
+} from "../features/contracts/services";
 import { OrgUnitsLayout } from "../features/org-units/layouts";
 import {
   getChildrenOrgUnitsService,
@@ -55,30 +58,40 @@ const loaderFunction = async (
 
   return withAuthLoader(
     data,
-    async ({ cookie, customerId, userId, ...restClientContext }) => {
-      const [currentOrgUnit, user, localizationLabels] = await Promise.all([
-        getOrgUnitBasicDataService({
-          id: data.query.orgUnitId,
-          cookie,
-        }),
-        getUserByIdService({ orgUnitId, userId, cookie }),
-        getLocalizationLabelsService({
-          entryIds: LOCALIZATION_ENTRY_IDS.orgUnits,
-          locale: data.locale,
-        }),
-      ]);
-
+    async ({
+      cookie,
+      customerId,
+      userId,
+      featureFlagsPromise,
+      ...restClientContext
+    }) => {
       // Organizational Units don't need contract data, but the sidebar
-      // (rendered by shared layouts) uses `currentContract` for its identity
-      // block, so fetch it when the URL carries the contract the user was
-      // last viewing.
-      const currentContract = contractId
-        ? await getContractDetailsService({
-            contractId,
-            unitId: orgUnitId,
+      // (rendered by shared layouts) builds contract-scoped links and its
+      // identity block from `currentContract`. Under SUMA, resolve it
+      // against the unit's attached contracts (URL contractId when
+      // attached, else the unit's default) so those links never carry a
+      // foreign or empty id. With the flag off, keep the pre-SUMA behavior
+      // byte-for-byte: fetch only when the URL already carries a contractId.
+      const featureFlags = await featureFlagsPromise;
+      const contractDetailsPromise = featureFlags?.suma
+        ? resolveAttachedContractService({ orgUnitId, contractId, cookie })
+        : contractId
+        ? getContractDetailsService({ contractId, unitId: orgUnitId, cookie })
+        : Promise.resolve(null);
+
+      const [currentOrgUnit, user, localizationLabels, currentContract] =
+        await Promise.all([
+          getOrgUnitBasicDataService({
+            id: data.query.orgUnitId,
             cookie,
-          })
-        : null;
+          }),
+          getUserByIdService({ orgUnitId, userId, cookie }),
+          getLocalizationLabelsService({
+            entryIds: LOCALIZATION_ENTRY_IDS.orgUnits,
+            locale: data.locale,
+          }),
+          contractDetailsPromise,
+        ]);
 
       const clientContext = {
         cookie,

package/src/pages/roles.tsx

@@ -1,4 +1,7 @@
-import { getContractDetailsService } from "../features/contracts/services";
+import {
+  getContractDetailsService,
+  resolveAttachedContractService,
+} from "../features/contracts/services";
 import { getOrgUnitBasicDataService } from "../features/org-units/services";
 import { RolesLayout } from "../features/roles/layout";
 import { getRolesAndPermissionsService } from "../features/roles/services";
@@ -46,51 +49,65 @@ const loaderFunction = async (
 ): Promise<AuthRouteProps<RolesPageData>> => {
   const { orgUnitId, contractId } = data.query;
 
-  return withAuthLoader(data, async ({ cookie, userId, ...clientContext }) => {
-    // Roles don't need contract data, but the sidebar (rendered by shared
-    // layouts) uses `currentContract` for its identity block, so fetch it
-    // when the URL carries the contract the user was last viewing.
-    const contractDetailsPromise = contractId
-      ? getContractDetailsService({ contractId, unitId: orgUnitId, cookie })
-      : Promise.resolve(null);
-
-    const [
-      rolesAndPermissions,
-      currentOrgUnit,
-      user,
-      currentContract,
-      localizationLabels,
-    ] = await Promise.all([
-      getRolesAndPermissionsService({
-        unitId: orgUnitId,
-        customerId: clientContext.customerId,
-        cookie,
-      }),
-      getOrgUnitBasicDataService({
-        id: orgUnitId,
-        cookie,
-      }),
-      getUserByIdService({ orgUnitId, userId, cookie }),
-      contractDetailsPromise,
-      getLocalizationLabelsService({
-        entryIds: LOCALIZATION_ENTRY_IDS.roles,
-        locale: data.locale,
-      }),
-    ]);
+  return withAuthLoader(
+    data,
+    async ({ cookie, userId, featureFlagsPromise, ...clientContext }) => {
+      // Roles don't need contract data, but the sidebar (rendered by shared
+      // layouts) builds contract-scoped links and its identity block from
+      // `currentContract`. Under SUMA, resolve it against the unit's
+      // attached contracts (URL contractId when attached, else the unit's
+      // default) so those links never carry a foreign or empty id. With the
+      // flag off, keep the pre-SUMA behavior byte-for-byte: fetch only when
+      // the URL already carries a contractId.
+      const featureFlags = await featureFlagsPromise;
+      const contractDetailsPromise = featureFlags?.suma
+        ? resolveAttachedContractService({
+            orgUnitId,
+            contractId,
+            cookie,
+          })
+        : contractId
+        ? getContractDetailsService({ contractId, unitId: orgUnitId, cookie })
+        : Promise.resolve(null);
 
-    return {
-      data: {
+      const [
         rolesAndPermissions,
-      },
-      context: {
-        clientContext: { cookie, userId, ...clientContext },
         currentOrgUnit,
+        user,
         currentContract,
-        currentUser: user,
-        localization: { labels: localizationLabels },
-      },
-    };
-  });
+        localizationLabels,
+      ] = await Promise.all([
+        getRolesAndPermissionsService({
+          unitId: orgUnitId,
+          customerId: clientContext.customerId,
+          cookie,
+        }),
+        getOrgUnitBasicDataService({
+          id: orgUnitId,
+          cookie,
+        }),
+        getUserByIdService({ orgUnitId, userId, cookie }),
+        contractDetailsPromise,
+        getLocalizationLabelsService({
+          entryIds: LOCALIZATION_ENTRY_IDS.roles,
+          locale: data.locale,
+        }),
+      ]);
+
+      return {
+        data: {
+          rolesAndPermissions,
+        },
+        context: {
+          clientContext: { cookie, userId, ...clientContext },
+          currentOrgUnit,
+          currentContract,
+          currentUser: user,
+          localization: { labels: localizationLabels },
+        },
+      };
+    }
+  );
 };
 
 export const loader = withLoaderErrorBoundary(loaderFunction, {

package/src/pages/users.tsx

@@ -1,4 +1,7 @@
-import { getContractDetailsService } from "../features/contracts/services";
+import {
+  getContractDetailsService,
+  resolveAttachedContractService,
+} from "../features/contracts/services";
 import { getOrgUnitBasicDataService } from "../features/org-units/services";
 import { getRolesIdsService } from "../features/roles/services";
 import { RoleData } from "../features/roles/types";
@@ -63,7 +66,13 @@ const loaderFunction = async (
 
   return withAuthLoader(
     data,
-    async ({ cookie, userId, customerId, ...clientContext }) => {
+    async ({
+      cookie,
+      userId,
+      customerId,
+      featureFlagsPromise,
+      ...clientContext
+    }) => {
       const validPage = getValidPage(page);
 
       const localizationLabels = await getLocalizationLabelsService({
@@ -92,9 +101,20 @@ const loaderFunction = async (
       }
 
       // Users don't need contract data, but the sidebar (rendered by shared
-      // layouts) uses `currentContract` for its identity block, so fetch it
-      // when the URL carries the contract the user was last viewing.
-      const contractDetailsPromise = contractId
+      // layouts) builds contract-scoped links and its identity block from
+      // `currentContract`. Under SUMA, resolve it against the unit's
+      // attached contracts (URL contractId when attached, else the unit's
+      // default) so those links never carry a foreign or empty id. With the
+      // flag off, keep the pre-SUMA behavior byte-for-byte: fetch only when
+      // the URL already carries a contractId.
+      const featureFlags = await featureFlagsPromise;
+      const contractDetailsPromise = featureFlags?.suma
+        ? resolveAttachedContractService({
+            orgUnitId,
+            contractId,
+            cookie,
+          })
+        : contractId
         ? getContractDetailsService({
             contractId,
             unitId: orgUnitId,