@vtex/faststore-plugin-buyer-portal 2.0.10 → 2.0.11

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.11] - 2026-07-17
+
+### Fixed
+
+- Sidebar links on the Users, Roles, and Organizational Units pages now carry the currently viewed contract's id in the URL, instead of silently falling back to the org unit's first contract — this previously caused the Finance section (Budgets/Buying Policies) links and accounting fields on those pages to point at the wrong contract
+- Removed a redundant `getBuyerPortalFeatureFlags` fetch on the Contract Listing page and a conflicting `no-cache`/`next.revalidate: 300` combination on the shared HTTP client, both of which could intermittently hide the "Add contracts" button (and serve stale per-contract data) for up to 5 minutes
+- Removing the session's currently active contract from an organizational unit now switches the session to a remaining contract, instead of leaving the UI pointed at a contract that no longer exists
+- Added a back-forward-cache guard to the contract switch flow to address a QA report of briefly seeing the previous contract's data after switching and going back
+- `SumaPageLayout` (the layout actually rendering the Users/Roles/Organizational Units sidebar when the `suma` flag is on) now also resolves its contract id from the URL instead of falling back to the org unit's first contract; the Users/Roles/Organizational Units page loaders now fetch minimal contract details when the URL carries a contract id, so the sidebar identity block shows consistently everywhere, not just on Budgets/Buying Policies
+- The sidebar's "Accounting fields" fetch is now skipped while its containing layout is in a transient loading state (e.g. during a route transition), instead of firing with route-parsed, possibly-stale ids; the link itself still renders, just without its child fields until loading finishes
+- Widened the Contract Listing sidebar and adjusted its padding; the "Add contracts" button is no longer gated behind an admin role check
+
 ## [2.0.10] - 2026-07-17
 
 ### Changed
@@ -745,7 +757,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add CHANGELOG file
 - Add README file
 
-[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.10...HEAD
+[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/2.0.11...HEAD
 [1.3.55]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.54...v1.3.55
 [1.3.54]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.53...v1.3.54
 [1.3.53]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.52...v1.3.53
@@ -842,3 +854,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 [2.0.10]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.9...v2.0.10
 [2.0.9]: https://github.com/vtex/faststore-plugin-buyer-portal/releases/tag/2.0.9
+
+[2.0.11]: https://github.com/vtex/faststore-plugin-buyer-portal/releases/tag/2.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore-plugin-buyer-portal",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "description": "A plugin for faststore with buyer portal",
   "main": "index.js",
   "scripts": {

package/src/features/addresses/clients/AddressesClient.ts

@@ -9,7 +9,7 @@ import type {
 } from "../types";
 import type {
   EditLocationSettingsParams,
-  GetAddressesByUnitIdParams,
+  GetAttachedAddressesByCustomerIdParams,
 } from "../types/AddressData";
 
 type AddressResponse = {
@@ -33,21 +33,25 @@ export default class AddressesClient extends Client {
     );
   }
 
-  async getAddressesByUnitId({
+  async getAttachedAddressesByCustomerId({
     orgUnitId,
+    customerId,
     cookie,
     name,
     addressType,
     page = 1,
-  }: GetAddressesByUnitIdParams) {
-    return this.get<AddressResponse>(`units/${orgUnitId}/addresses`, {
-      headers: { Cookie: cookie },
-      params: {
-        page,
-        name: name ?? "",
-        addressType: addressType ?? "",
-      },
-    });
+  }: GetAttachedAddressesByCustomerIdParams) {
+    return this.get<AddressResponse>(
+      `units/${orgUnitId}/customers/${customerId}/addresses/attached`,
+      {
+        headers: { Cookie: cookie },
+        params: {
+          page,
+          name: name ?? "",
+          addressType: addressType ?? "",
+        },
+      }
+    );
   }
 
   getAddressById(

package/src/features/addresses/components/CreateAddressSettingsDrawer/CreateAddressSettingsDrawer.tsx

@@ -91,6 +91,7 @@ export const CreateAddressSettingsDrawer = ({
 
   const { searchedAddresses } = useDebouncedSearchAddressByUnitId({
     orgUnitId: router.query.orgUnitId as string,
+    contractId: router.query.contractId as string,
     search: searchValue,
     addressType: activeField === "Shipping" ? "Shipping" : "Billing",
   });

package/src/features/addresses/hooks/useDebouncedSearchAddressByUnitId.ts

@@ -8,12 +8,14 @@ import type { UseDebouncedSearchAddressByUnitIdProps } from "../types/AddressDat
 
 export const useDebouncedSearchAddressByUnitId = ({
   orgUnitId,
+  contractId,
   search = "",
   addressType,
 }: UseDebouncedSearchAddressByUnitIdProps) => {
   const debouncedSearchTerm = useDebounce(search, DEBOUNCE_TIMEOUT);
   const { listAddressesData, listAddressesLoading } = useListAddresses({
     orgUnitId,
+    contractId,
     search: debouncedSearchTerm,
     addressType,
   });

package/src/features/addresses/hooks/useListAddresses.ts

@@ -1,24 +1,34 @@
 import { type QueryOptions, useQuery } from "../../shared/hooks";
-import { getAddressesByUnitIdService } from "../services";
+import { getAttachedAddressesByCustomerIdService } from "../services";
 
 type UseListAddressesProps = {
   orgUnitId: string;
+  contractId: string;
   search: string;
   page?: number;
   addressType?: string;
 };
 
 export const useListAddresses = (
-  { orgUnitId, search, page = 1, addressType }: UseListAddressesProps,
-  options?: QueryOptions<AwaitedType<typeof getAddressesByUnitIdService>>
+  {
+    orgUnitId,
+    contractId,
+    search,
+    page = 1,
+    addressType,
+  }: UseListAddressesProps,
+  options?: QueryOptions<
+    AwaitedType<typeof getAttachedAddressesByCustomerIdService>
+  >
 ) => {
   const { data, error, isLoading, refetch } = useQuery(
-    `api/addresses/unitId=${orgUnitId}/page=${page}/search=${
+    `api/addresses/unitId=${orgUnitId}/contractId=${contractId}/page=${page}/search=${
       search ?? ""
     }/addressType=${addressType ?? ""}`,
     ({ cookie }) =>
-      getAddressesByUnitIdService({
+      getAttachedAddressesByCustomerIdService({
         orgUnitId,
+        contractId,
         search,
         cookie,
         addressType,

package/src/features/addresses/layouts/AddressesLayout/AddressesLayout.tsx

@@ -90,6 +90,7 @@ export const AddressLayout = () => {
     useListAddresses(
       {
         orgUnitId: (router.query.orgUnitId as string) ?? "",
+        contractId: (router.query.contractId as string) ?? "",
         page: isRouterSynced ? page : 0,
         search: committedSearch,
       },

package/src/features/addresses/services/{get-addresses-by-unit-id.service.ts → get-attached-addresses-by-customer-id.service.ts}

@@ -5,7 +5,7 @@ import {
 } from "../../shared/utils/withClientErrorBoundary";
 import { addressesClient } from "../clients/AddressesClient";
 
-export type GetAddressesByUnitIdServiceProps = Partial<{
+export type GetAttachedAddressesByCustomerIdServiceProps = Partial<{
   search: string;
   orgUnitId: string;
   status: string;
@@ -14,11 +14,13 @@ export type GetAddressesByUnitIdServiceProps = Partial<{
   page?: number;
   addressType?: string;
 }> & {
+  contractId: string;
   cookie: string;
 };
 
-export const getAddressesByUnitIdServiceFn = async ({
+export const getAttachedAddressesByCustomerIdServiceFn = async ({
   orgUnitId,
+  contractId,
   status,
   type,
   sort,
@@ -26,17 +28,19 @@ export const getAddressesByUnitIdServiceFn = async ({
   search = "",
   page = 1,
   addressType,
-}: GetAddressesByUnitIdServiceProps) => {
-  if (!orgUnitId) {
+}: GetAttachedAddressesByCustomerIdServiceProps) => {
+  if (!orgUnitId || !contractId) {
     return { data: [], total: 0 };
   }
-  const { addresses, total } = await addressesClient.getAddressesByUnitId({
-    orgUnitId,
-    cookie,
-    name: search,
-    addressType,
-    page,
-  });
+  const { addresses, total } =
+    await addressesClient.getAttachedAddressesByCustomerId({
+      orgUnitId,
+      customerId: contractId,
+      cookie,
+      name: search,
+      addressType,
+      page,
+    });
 
   const formattedAddress = addresses
     ?.filter((address) => {
@@ -51,10 +55,10 @@ export const getAddressesByUnitIdServiceFn = async ({
   return { data: formattedAddress, total };
 };
 
-export const getAddressesByUnitIdService = withClientErrorBoundary(
-  getAddressesByUnitIdServiceFn,
+export const getAttachedAddressesByCustomerIdService = withClientErrorBoundary(
+  getAttachedAddressesByCustomerIdServiceFn,
   {
-    componentName: "AddressesByUnitId",
+    componentName: "AttachedAddressesByCustomerId",
     onError: handleUnauthorizedRedirect,
   }
 );

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

@@ -4,9 +4,9 @@ export {
   type GetAddressesServiceProps,
 } from "./get-addresses.service";
 export {
-  getAddressesByUnitIdService,
-  type GetAddressesByUnitIdServiceProps,
-} from "./get-addresses-by-unit-id.service";
+  getAttachedAddressesByCustomerIdService,
+  type GetAttachedAddressesByCustomerIdServiceProps,
+} from "./get-attached-addresses-by-customer-id.service";
 export {
   createNewAddressService,
   type CreateNewAddressServiceProps,

package/src/features/addresses/types/AddressData.ts

@@ -102,8 +102,9 @@ export type AddressInput = {
   neighborhood?: string;
 };
 
-export type GetAddressesByUnitIdParams = {
+export type GetAttachedAddressesByCustomerIdParams = {
   orgUnitId: string;
+  customerId: string;
   cookie: string;
   name?: string;
   addressType?: string;
@@ -120,6 +121,7 @@ export type DefaultAddressParams = {
 
 export type UseDebouncedSearchAddressByUnitIdProps = {
   orgUnitId: string;
+  contractId: string;
   search: string;
   addressType?: string;
 };

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

@@ -14,11 +14,14 @@ import {
   VerticalNav,
   LetterHighlight,
 } from "../../../shared/components";
-import { useDrawerProps, useBuyerPortal } from "../../../shared/hooks";
+import {
+  useDrawerProps,
+  useBuyerPortal,
+  useReloadOnBfcacheRestore,
+} from "../../../shared/hooks";
 import { GlobalLayout } from "../../../shared/layouts";
 import { SumaSidebar } from "../../../shared/layouts/SumaPageLayout/SumaSidebar";
 import { buyerPortalRoutes } from "../../../shared/utils/buyerPortalRoutes";
-import { USER_ROLES } from "../../../users/types";
 import { AddContractsDrawer } from "../../components/AddContractsDrawer/AddContractsDrawer";
 import { ConfirmRemoveDrawer } from "../../components/ConfirmRemoveDrawer/ConfirmRemoveDrawer";
 import { ContractSelectAllRow } from "../../components/ContractSelectAllRow";
@@ -32,6 +35,7 @@ import {
   useContractSwitchChannel,
   useRemoveContracts,
   useSetDefaultContract,
+  useSwitchContract,
 } from "../../hooks";
 
 import { buildContractSettingsNavItems } from "./ContractSettingsNav";
@@ -96,8 +100,8 @@ export const ContractListingLayout = ({
     ...addContractsDrawer
   } = useDrawerProps();
 
-  const { featureFlags } = useBuyerPortal();
-  const isAdmin = user?.roles?.includes(USER_ROLES.SUPER_USER) ?? false;
+  const { featureFlags, clientContext } = useBuyerPortal();
+  const { switchContract } = useSwitchContract();
 
   const {
     open: openConfirmRemoveDrawer,
@@ -119,6 +123,34 @@ export const ContractListingLayout = ({
     onSuccess: () => {
       confirmRemoveDrawer.close();
       clearSelection();
+
+      const removedActiveContract = pendingRemoveIds.has(
+        clientContext.customerId
+      );
+
+      if (removedActiveContract) {
+        const remainingContracts = contracts.filter(
+          (c) => !pendingRemoveIds.has(c.id)
+        );
+        const fallbackContractId = getDefaultContractId(remainingContracts);
+
+        if (fallbackContractId) {
+          switchContract(fallbackContractId, { orgUnitId: orgUnit.id }).then(
+            (switched) => {
+              if (!switched) {
+                pushToast({
+                  message:
+                    "Contracts removed, but we couldn't refresh your active contract. Please reload the page.",
+                  status: "ERROR",
+                });
+                router.replace(router.asPath);
+              }
+            }
+          );
+          return;
+        }
+      }
+
       router.replace(router.asPath);
       pushToast({
         message: `${pendingRemoveIds.size} contract${
@@ -200,6 +232,8 @@ export const ContractListingLayout = ({
     return cleanup;
   }, []);
 
+  useReloadOnBfcacheRestore();
+
   useEffect(() => {
     if (router.query.error === "contract-load-failed") {
       pushToast({
@@ -289,7 +323,7 @@ export const ContractListingLayout = ({
             info={headerInfo}
             data-fs-bp-contract-listing-header
           >
-            {featureFlags?.suma && isAdmin && (
+            {featureFlags?.suma && (
               <HeaderInside.Button
                 onClick={openAddContractsDrawer}
                 aria-label="Add contracts"

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

@@ -21,7 +21,7 @@
   margin: var(--fs-bp-margin-0) var(--fs-bp-margin-auto);
 
   @include u.media(">=notebook") {
-    grid-template-columns: 16.25rem 1fr;
+    grid-template-columns: 20rem 1fr;
   }
 }
 
@@ -30,7 +30,7 @@
   @import "../../../shared/components/LetterHighlight/letter-highlight.scss";
 
   display: none;
-  padding: var(--fs-bp-padding-5) var(--fs-bp-padding-5) var(--fs-bp-padding-12) var(--fs-bp-padding-2);
+  padding: var(--fs-bp-padding-5) var(--fs-bp-padding-5) var(--fs-bp-padding-12) var(--fs-bp-padding-5);
   border-right: 1px solid var(--fs-bp-color-neutral-2);
   overflow-y: auto;
 

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

@@ -104,7 +104,10 @@ export const OrgUnitsDetailsLayout = ({
     listAccountingFieldRefresh,
   } = useListAccountingFields({ orgUnitId: orgUnit.id });
 
-  const organizationMenu = getOrganizationSettingsLinks(orgUnit.id);
+  const organizationMenu = getOrganizationSettingsLinks({
+    orgUnitId: orgUnit.id,
+    contractId: linkParams.contractId,
+  });
 
   const financeMenu = getFinanceSettingsLinks(linkParams);
 

package/src/features/shared/clients/Client.ts

@@ -97,7 +97,7 @@ class Client {
         ...(headers.Cookie ? getAuthFromCookie(headers.Cookie ?? "") : {}),
         ...headers,
       },
-      ...(cache ? { cache, next: { revalidate: 300 } } : {}),
+      ...(cache ? { cache } : {}),
     };
 
     const paramsString = toQueryParams(params);

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

@@ -19,3 +19,4 @@ export { ANALYTICS_FALLBACK_CORRELATION_ID } from "./analytics/constants";
 export { useGetScopeConfig, SCOPE_KEYS } from "./useGetScopeConfig";
 export { useSetScopeConfig } from "./useSetScopeConfig";
 export { useUrlPaginatedSearch } from "./useUrlPaginatedSearch";
+export { useReloadOnBfcacheRestore } from "./useReloadOnBfcacheRestore";

package/src/features/shared/hooks/useReloadOnBfcacheRestore.ts

@@ -0,0 +1,24 @@
+import { useEffect } from "react";
+
+import { useRouter } from "next/router";
+
+/**
+ * Forces a full reload when the page is restored from the browser's
+ * back-forward cache (e.g. after pressing Back), so contract-scoped layouts
+ * never resume with frozen JS state/closures from before a prior contract
+ * switch.
+ */
+export const useReloadOnBfcacheRestore = () => {
+  const router = useRouter();
+
+  useEffect(() => {
+    const handlePageShow = (event: PageTransitionEvent) => {
+      if (event.persisted) {
+        router.reload();
+      }
+    };
+
+    window.addEventListener("pageshow", handlePageShow);
+    return () => window.removeEventListener("pageshow", handlePageShow);
+  }, []);
+};

package/src/features/shared/layouts/BaseTabsLayout/SidebarMenu.tsx

@@ -3,6 +3,7 @@ import type { ReactNode } from "react";
 import { useRouter } from "next/router";
 
 import { useBuyerPortal } from "../../hooks";
+import { resolveContractId } from "../../utils";
 import { FullSidebarNav } from "../SumaPageLayout/FullSidebarNav";
 
 export type SidebarMenuProps = {
@@ -16,21 +17,19 @@ export type SidebarMenuProps = {
   loading?: boolean;
 };
 
-export const SidebarMenu = ({ ...otherProps }: SidebarMenuProps) => {
+export const SidebarMenu = ({ loading, ...otherProps }: SidebarMenuProps) => {
   const { currentOrgUnit, currentContract } = useBuyerPortal();
   const router = useRouter();
 
   const orgUnitId = (router.query.orgUnitId as string) || "";
-  const customerId = (router.query.contractId as string) || "";
-
-  const idContract =
-    (currentContract?.id
-      ? currentContract?.id
-      : currentOrgUnit?.customerGroup.customerIds[0]) ?? "";
 
   const linkParams = {
     orgUnitId: orgUnitId || currentOrgUnit?.id || "",
-    contractId: customerId || idContract,
+    contractId: resolveContractId({
+      queryContractId: router.query.contractId,
+      currentContract,
+      currentOrgUnit,
+    }),
   };
 
   return (
@@ -38,6 +37,7 @@ export const SidebarMenu = ({ ...otherProps }: SidebarMenuProps) => {
       <FullSidebarNav
         orgUnitId={linkParams.orgUnitId}
         contractId={linkParams.contractId}
+        loading={loading}
       />
     </aside>
   );

package/src/features/shared/layouts/ContractTabsLayout/ContractTabsLayout.tsx

@@ -4,7 +4,7 @@ import { DropdownItem } from "@faststore/ui";
 
 import { OrgUnitDetailsNavbar } from "../../../org-units/components";
 import { Icon } from "../../components";
-import { useBuyerPortal } from "../../hooks";
+import { useBuyerPortal, useReloadOnBfcacheRestore } from "../../hooks";
 import { getContractSettingsLinks } from "../../utils";
 import { BaseTabsLayout } from "../BaseTabsLayout/BaseTabsLayout";
 import { SumaSidebar } from "../SumaPageLayout/SumaSidebar";
@@ -29,6 +29,8 @@ export const ContractTabsLayout = ({
   const { currentOrgUnit, currentUser, currentContract, featureFlags } =
     useBuyerPortal();
 
+  useReloadOnBfcacheRestore();
+
   const resolvedOrgUnitId = currentOrgUnit?.id ?? orgUnitId ?? "";
   const resolvedContractId =
     currentContract?.id ??
@@ -57,6 +59,7 @@ export const ContractTabsLayout = ({
             contractId={resolvedContractId}
             variant="full"
             showBackLink
+            loading={loading}
           />
           <section data-fs-bp-contract-listing-section>{children}</section>
         </div>

package/src/features/shared/layouts/OrgUnitTabsLayout/OrgUnitTabLayout.tsx

@@ -17,7 +17,10 @@ export const OrgUnitTabsLayout = ({
 }: OrgUnitTabsLayoutProps) => {
   const { currentOrgUnit, currentUser, currentContract } = useBuyerPortal();
 
-  const verticalLinks = getOrganizationSettingsLinks(currentOrgUnit?.id ?? "");
+  const verticalLinks = getOrganizationSettingsLinks({
+    orgUnitId: currentOrgUnit?.id ?? "",
+    contractId: currentContract?.id ?? "",
+  });
 
   return (
     <BaseTabsLayout data-fs-bp-org-unit-tabs-layout>

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

@@ -12,6 +12,7 @@ import {
   getContractSettingsLinks,
   getFinanceSettingsLinks,
   getOrganizationSettingsLinks,
+  resolveContractId,
 } from "../../utils";
 import { buyerPortalRoutes } from "../../utils/buyerPortalRoutes";
 
@@ -21,6 +22,7 @@ export type FullSidebarNavProps = {
   orgUnitId: string;
   contractId: string;
   showContractTitle?: boolean;
+  loading?: boolean;
 };
 
 const mapLinksHandler = ({
@@ -35,6 +37,7 @@ export const FullSidebarNav = ({
   orgUnitId,
   contractId,
   showContractTitle = true,
+  loading = false,
 }: FullSidebarNavProps) => {
   const { currentOrgUnit, currentContract } = useBuyerPortal();
 
@@ -46,21 +49,26 @@ export const FullSidebarNav = ({
 
   const resolvedOrgUnitId = orgUnitId || currentOrgUnit?.id || "";
   const resolvedContractId =
-    contractId ||
-    currentContract?.id ||
-    currentOrgUnit?.customerGroup.customerIds[0] ||
-    "";
+    contractId || resolveContractId({ currentContract, currentOrgUnit });
 
   const linkParams = {
     orgUnitId: resolvedOrgUnitId,
     contractId: resolvedContractId,
   };
 
+  // Skip the fetch entirely while this sidebar is just a transient loading
+  // placeholder (e.g. LoadingTabsLayout during a route transition) — it would
+  // otherwise fire with route-parsed, possibly-stale ids. The item below still
+  // renders (just with no children yet), since data/loading naturally stay at
+  // their initial empty/false values while the fetch is skipped.
   const {
     listAccountingFieldLoading,
     listAccountingFieldData,
     listAccountingFieldRefresh,
-  } = useListAccountingFields({ orgUnitId: resolvedOrgUnitId });
+  } = useListAccountingFields(
+    { orgUnitId: resolvedOrgUnitId },
+    { lazy: loading }
+  );
 
   const contractMenu =
     getContractSettingsLinks(linkParams).map(mapLinksHandler);
@@ -95,7 +103,10 @@ export const FullSidebarNav = ({
     ),
   });
 
-  const organizationMenu = getOrganizationSettingsLinks(resolvedOrgUnitId);
+  const organizationMenu = getOrganizationSettingsLinks({
+    orgUnitId: resolvedOrgUnitId,
+    contractId: resolvedContractId,
+  });
   const financeMenu = getFinanceSettingsLinks(linkParams);
 
   return (

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

@@ -1,7 +1,10 @@
 import type { ReactNode } from "react";
 
+import { useRouter } from "next/router";
+
 import { OrgUnitDetailsNavbar } from "../../../org-units/components";
-import { useBuyerPortal } from "../../hooks";
+import { useBuyerPortal, useReloadOnBfcacheRestore } from "../../hooks";
+import { resolveContractId } from "../../utils";
 
 import { SumaSidebar } from "./SumaSidebar";
 
@@ -20,13 +23,19 @@ export const SumaPageLayout = ({
 }: SumaPageLayoutProps) => {
   const { featureFlags, currentOrgUnit, currentUser, currentContract } =
     useBuyerPortal();
+  const router = useRouter();
+
+  useReloadOnBfcacheRestore();
 
   if (!featureFlags?.suma || !currentOrgUnit?.id) {
     return <>{children}</>;
   }
 
-  const contractId =
-    currentContract?.id ?? currentOrgUnit.customerGroup.customerIds[0] ?? "";
+  const contractId = resolveContractId({
+    queryContractId: router.query.contractId,
+    currentContract,
+    currentOrgUnit,
+  });
 
   return (
     <>
@@ -48,6 +57,7 @@ export const SumaPageLayout = ({
           contractId={contractId}
           variant={sidebarVariant}
           showBackLink={showBackLink}
+          loading={loading}
         />
         <section data-fs-bp-contract-listing-section>{children}</section>
       </div>

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

@@ -12,6 +12,7 @@ export type SumaSidebarProps = {
   contractId: string;
   variant?: "listing" | "full";
   showBackLink?: boolean;
+  loading?: boolean;
 };
 
 export const SumaSidebar = ({
@@ -19,6 +20,7 @@ export const SumaSidebar = ({
   contractId,
   variant = "full",
   showBackLink = false,
+  loading = false,
 }: SumaSidebarProps) => {
   const { featureFlags, currentContract } = useBuyerPortal();
   const contractsUrl = buyerPortalRoutes.contracts({ orgUnitId });
@@ -73,6 +75,7 @@ export const SumaSidebar = ({
           orgUnitId={orgUnitId}
           contractId={contractId}
           showContractTitle={!showIdentity}
+          loading={loading}
         />
       )}
     </aside>

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

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveContractId } from "../resolveContractId";
+
+import type { ContractData } from "../../../contracts/types";
+import type { OrgUnitBasicData } from "../../../org-units/types";
+
+const contract = { id: "contract-b" } as ContractData;
+const orgUnit = {
+  customerGroup: { customerIds: ["contract-a", "contract-b"] },
+} as OrgUnitBasicData;
+
+describe("resolveContractId", () => {
+  it("prefers the URL's contractId over context", () => {
+    expect(
+      resolveContractId({
+        queryContractId: "contract-c",
+        currentContract: contract,
+        currentOrgUnit: orgUnit,
+      })
+    ).toBe("contract-c");
+  });
+
+  it("takes the first value when the URL param is an array", () => {
+    expect(
+      resolveContractId({
+        queryContractId: ["contract-c", "contract-d"],
+        currentContract: contract,
+        currentOrgUnit: orgUnit,
+      })
+    ).toBe("contract-c");
+  });
+
+  it("falls back to currentContract when the URL has no contractId", () => {
+    expect(
+      resolveContractId({ currentContract: contract, currentOrgUnit: orgUnit })
+    ).toBe("contract-b");
+  });
+
+  it("falls back to the org unit's first customer id as a last resort", () => {
+    expect(resolveContractId({ currentOrgUnit: orgUnit })).toBe("contract-a");
+  });
+
+  it("returns an empty string when nothing is known", () => {
+    expect(resolveContractId({})).toBe("");
+  });
+});

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

@@ -10,6 +10,12 @@ function replaceParams(template: string, params: Record<string, string>) {
     .replace(/\/+/g, "/"); // Remove consecutive slashes
 }
 
+function appendContractIdParam(url: string, contractId?: string): string {
+  return contractId
+    ? `${url}?contractId=${encodeURIComponent(contractId)}`
+    : url;
+}
+
 export const buyerPortalRoutes = {
   // orgUnitId + contractId
   profileDetails: (params: { orgUnitId: string; contractId: string }) =>
@@ -66,18 +72,34 @@ export const buyerPortalRoutes = {
       `${base}/buying-policy/[orgUnitId]/[contractId]/[buyingPolicyId]`,
       params
     ),
-  // orgUnitId only
-  users: (params: { orgUnitId: string }) =>
-    replaceParams(`${base}/users/[orgUnitId]`, params),
+  // orgUnitId only (contractId is optional and only carried in the URL so
+  // the sidebar can keep linking to the right contract elsewhere)
+  users: (params: { orgUnitId: string; contractId?: string }) =>
+    appendContractIdParam(
+      replaceParams(`${base}/users/[orgUnitId]`, {
+        orgUnitId: params.orgUnitId,
+      }),
+      params.contractId
+    ),
 
-  roles: (params: { orgUnitId: string }) =>
-    replaceParams(`${base}/roles/[orgUnitId]`, params),
+  roles: (params: { orgUnitId: string; contractId?: string }) =>
+    appendContractIdParam(
+      replaceParams(`${base}/roles/[orgUnitId]`, {
+        orgUnitId: params.orgUnitId,
+      }),
+      params.contractId
+    ),
 
   roleDetails: (params: { orgUnitId: string; roleName: string }) =>
     replaceParams(`${base}/roles/[orgUnitId]/[roleName]`, params),
 
-  orgUnits: (params: { orgUnitId: string }) =>
-    replaceParams(`${base}/org-units/[orgUnitId]`, params),
+  orgUnits: (params: { orgUnitId: string; contractId?: string }) =>
+    appendContractIdParam(
+      replaceParams(`${base}/org-units/[orgUnitId]`, {
+        orgUnitId: params.orgUnitId,
+      }),
+      params.contractId
+    ),
 
   // orgUnitId + specific ID
   userDetails: (params: { orgUnitId: string; userId: string }) =>

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

@@ -22,7 +22,7 @@ export const SCOPE_KEYS = {
   CREDIT_CARDS: "creditCards",
 } as const;
 
-export const CURRENT_VERSION = "2.0.10";
+export const CURRENT_VERSION = "2.0.11";
 
 export const CHANGES_TIMEOUT_MESSAGE =
   "Changes may take up to 10 minutes to apply.";

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

@@ -1,10 +1,16 @@
 import { buyerPortalRoutes } from "./buyerPortalRoutes";
 
-export const getOrganizationSettingsLinks = (orgUnitId: string) => [
-  { name: "Users", link: buyerPortalRoutes.users({ orgUnitId }) },
-  { name: "Roles", link: buyerPortalRoutes.roles({ orgUnitId }) },
+export const getOrganizationSettingsLinks = ({
+  orgUnitId,
+  contractId,
+}: {
+  orgUnitId: string;
+  contractId?: string;
+}) => [
+  { name: "Users", link: buyerPortalRoutes.users({ orgUnitId, contractId }) },
+  { name: "Roles", link: buyerPortalRoutes.roles({ orgUnitId, contractId }) },
   {
     name: "Organizational Units",
-    link: buyerPortalRoutes.orgUnits({ orgUnitId }),
+    link: buyerPortalRoutes.orgUnits({ orgUnitId, contractId }),
   },
 ];

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

@@ -13,6 +13,6 @@ export const getSumaListingSidebarLinks = ({
     name: "Contracts",
     link: buyerPortalRoutes.contracts({ orgUnitId }),
   },
-  ...getOrganizationSettingsLinks(orgUnitId),
+  ...getOrganizationSettingsLinks({ orgUnitId, contractId }),
   ...getFinanceSettingsLinks({ orgUnitId, contractId }),
 ];

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

@@ -23,6 +23,7 @@ export {
 } from "./getKeyByValue";
 export { getOrganizationSettingsLinks } from "./getOrganizationSettingsLinks";
 export { getSumaListingSidebarLinks } from "./getSumaListingSidebarLinks";
+export { resolveContractId } from "./resolveContractId";
 export { getTreeDepth } from "./getTreeDepth";
 export { doLogout } from "./logout";
 export { transformToDecimalMoney } from "./monetaryConverter";

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

@@ -0,0 +1,30 @@
+import type { ContractData } from "../../contracts/types";
+import type { OrgUnitBasicData } from "../../org-units/types";
+
+export type ResolveContractIdParams = {
+  queryContractId?: string | string[];
+  currentContract?: ContractData | null;
+  currentOrgUnit?: OrgUnitBasicData | null;
+};
+
+/**
+ * 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.
+ */
+export const resolveContractId = ({
+  queryContractId,
+  currentContract,
+  currentOrgUnit,
+}: ResolveContractIdParams): string => {
+  const fromQuery = Array.isArray(queryContractId)
+    ? queryContractId[0]
+    : queryContractId;
+
+  return (
+    fromQuery ||
+    currentContract?.id ||
+    currentOrgUnit?.customerGroup.customerIds[0] ||
+    ""
+  );
+};

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

@@ -3,6 +3,7 @@ import { getBuyerPortalFeatureFlags } from "../services/feature-flags/get-featur
 
 import { ClientContext, getClientContext } from "./getClientContext";
 
+import type { FeatureFlags } from "../components/BuyerPortalProvider/BuyerPortalProvider";
 import type { AuthRouteProps } from "../types";
 import type { LoaderData } from "../types";
 
@@ -10,13 +11,18 @@ export type WithAuthLoaderOptions = {
   validateAccess?: (props: { cookie: string }) => Promise<boolean>;
 };
 
+export type WithAuthLoaderClientContext = ClientContext & {
+  /** Single in-flight fetch shared with the flags merge below — reuse this instead of calling getBuyerPortalFeatureFlags again. */
+  featureFlagsPromise: Promise<FeatureFlags>;
+};
+
 /**
  * Utility function to encapsulate access validation in loaders.
  * Similar to withAuthProvider but for server-side usage.
  */
 export const withAuthLoader = async <T>(
   data: LoaderData,
-  dataLoader: (clientContext: ClientContext) => Promise<T>,
+  dataLoader: (clientContext: WithAuthLoaderClientContext) => Promise<T>,
   options?: WithAuthLoaderOptions
 ): Promise<AuthRouteProps<T>> => {
   try {
@@ -35,9 +41,11 @@ export const withAuthLoader = async <T>(
       };
     }
 
+    const featureFlagsPromise = getBuyerPortalFeatureFlags(cookie);
+
     const [pageData, featureFlags] = await Promise.all([
-      dataLoader({ cookie, userId, ...clientContext }),
-      getBuyerPortalFeatureFlags(cookie),
+      dataLoader({ cookie, userId, ...clientContext, featureFlagsPromise }),
+      featureFlagsPromise,
     ]);
 
     const mergedPageData = (() => {

package/src/pages/contracts.tsx

@@ -3,7 +3,6 @@ import { listAttachedContractsService } 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";
-import { getBuyerPortalFeatureFlags } from "../features/shared/services/feature-flags/get-feature-flags.service";
 import {
   type ClientContext,
   withLoaderErrorBoundary,
@@ -46,35 +45,38 @@ const loaderFunction = async (
     throw new Error(`Missing required query param: orgUnitId=${orgUnitId}`);
   }
 
-  return withAuthLoader(data, async ({ cookie, userId, ...clientContext }) => {
-    const featureFlags = await getBuyerPortalFeatureFlags(cookie);
+  return withAuthLoader(
+    data,
+    async ({ cookie, userId, featureFlagsPromise, ...clientContext }) => {
+      const featureFlags = await featureFlagsPromise;
 
-    if (!featureFlags?.suma) {
-      data.res?.writeHead(302, {
-        Location: buyerPortalRoutes.orgUnitDetails({ orgUnitId }),
-      });
-      data.res?.end();
+      if (!featureFlags?.suma) {
+        data.res?.writeHead(302, {
+          Location: buyerPortalRoutes.orgUnitDetails({ orgUnitId }),
+        });
+        data.res?.end();
 
-      return { redirected: true } as unknown as ContractsPageData;
-    }
+        return { redirected: true } as unknown as ContractsPageData;
+      }
 
-    const [orgUnit, contracts, user] = await Promise.all([
-      getOrgUnitBasicDataService({ id: orgUnitId, cookie }),
-      listAttachedContractsService({ orgUnitId, cookie }),
-      getUserByIdService({ orgUnitId, userId, cookie }),
-    ]);
+      const [orgUnit, contracts, user] = await Promise.all([
+        getOrgUnitBasicDataService({ id: orgUnitId, cookie }),
+        listAttachedContractsService({ orgUnitId, cookie }),
+        getUserByIdService({ orgUnitId, userId, cookie }),
+      ]);
 
-    return {
-      data: {
-        orgUnit,
-        contracts: contracts ?? [],
-        user,
-      },
-      context: {
-        clientContext: { cookie, userId, ...clientContext },
-      },
-    };
-  });
+      return {
+        data: {
+          orgUnit,
+          contracts: contracts ?? [],
+          user,
+        },
+        context: {
+          clientContext: { cookie, userId, ...clientContext },
+        },
+      };
+    }
+  );
 };
 
 export const loader = withLoaderErrorBoundary(loaderFunction, {

package/src/pages/org-units.tsx

@@ -1,3 +1,4 @@
+import { getContractDetailsService } from "../features/contracts/services";
 import { OrgUnitsLayout } from "../features/org-units/layouts";
 import {
   getChildrenOrgUnitsService,
@@ -16,6 +17,7 @@ import {
 } from "../features/shared/utils";
 import { getUserByIdService } from "../features/users/services";
 
+import type { ContractData } from "../features/contracts/types";
 import type {
   OrgUnitBasicData,
   OrgUnitSearchResponse,
@@ -29,6 +31,7 @@ export type OrgUnitsPageData = {
   context: {
     clientContext: ClientContext;
     currentOrgUnit: OrgUnitBasicData | null;
+    currentContract: ContractData | null;
     currentUser: UserData | null;
   };
   hasError?: boolean;
@@ -37,13 +40,14 @@ export type OrgUnitsPageData = {
 
 type OrgUnitsPageQuery = {
   orgUnitId: string;
+  contractId?: string;
   search?: string;
 };
 
 const loaderFunction = async (
   data: LoaderData<OrgUnitsPageQuery>
 ): Promise<AuthRouteProps<OrgUnitsPageData>> => {
-  const { search, orgUnitId } = data.query;
+  const { search, orgUnitId, contractId } = data.query;
 
   return withAuthLoader(
     data,
@@ -55,6 +59,18 @@ const loaderFunction = async (
 
       const user = await getUserByIdService({ orgUnitId, userId, cookie });
 
+      // 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,
+            cookie,
+          })
+        : null;
+
       const clientContext = {
         cookie,
         customerId,
@@ -73,6 +89,7 @@ const loaderFunction = async (
           context: {
             clientContext,
             currentOrgUnit,
+            currentContract,
             currentUser: user,
           },
         };
@@ -99,6 +116,7 @@ const loaderFunction = async (
           context: {
             clientContext,
             currentOrgUnit,
+            currentContract,
             currentUser: user,
           },
         };
@@ -113,6 +131,7 @@ const loaderFunction = async (
         context: {
           clientContext,
           currentOrgUnit,
+          currentContract,
           currentUser: user,
         },
       };

package/src/pages/roles.tsx

@@ -1,3 +1,4 @@
+import { getContractDetailsService } from "../features/contracts/services";
 import { getOrgUnitBasicDataService } from "../features/org-units/services";
 import { RolesLayout } from "../features/roles/layout";
 import { getRolesAndPermissionsService } from "../features/roles/services";
@@ -13,6 +14,7 @@ import {
 } from "../features/shared/utils";
 import { getUserByIdService } from "../features/users/services";
 
+import type { ContractData } from "../features/contracts/types";
 import type { OrgUnitBasicData } from "../features/org-units/types";
 import type { AuthRouteProps, LoaderData } from "../features/shared/types";
 import type { UserData } from "../features/users/types";
@@ -24,30 +26,45 @@ export type RolesPageData = {
   context: {
     clientContext: ClientContext;
     currentOrgUnit: OrgUnitBasicData | null;
+    currentContract: ContractData | null;
     currentUser: UserData | null;
   };
   hasError?: boolean;
   error?: ErrorBoundaryProps;
 };
 
+export type RolesPageQuery = {
+  orgUnitId: string;
+  contractId?: string;
+};
+
 const loaderFunction = async (
-  data: LoaderData
+  data: LoaderData<RolesPageQuery>
 ): Promise<AuthRouteProps<RolesPageData>> => {
-  const { orgUnitId } = data.query;
+  const { orgUnitId, contractId } = data.query;
 
   return withAuthLoader(data, async ({ cookie, userId, ...clientContext }) => {
-    const [rolesAndPermissions, currentOrgUnit, user] = await Promise.all([
-      getRolesAndPermissionsService({
-        unitId: orgUnitId,
-        customerId: clientContext.customerId,
-        cookie,
-      }),
-      getOrgUnitBasicDataService({
-        id: orgUnitId,
-        cookie,
-      }),
-      getUserByIdService({ orgUnitId, userId, cookie }),
-    ]);
+    // 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] =
+      await Promise.all([
+        getRolesAndPermissionsService({
+          unitId: orgUnitId,
+          customerId: clientContext.customerId,
+          cookie,
+        }),
+        getOrgUnitBasicDataService({
+          id: orgUnitId,
+          cookie,
+        }),
+        getUserByIdService({ orgUnitId, userId, cookie }),
+        contractDetailsPromise,
+      ]);
 
     return {
       data: {
@@ -56,6 +73,7 @@ const loaderFunction = async (
       context: {
         clientContext: { cookie, userId, ...clientContext },
         currentOrgUnit,
+        currentContract,
         currentUser: user,
       },
     };

package/src/pages/users.tsx

@@ -1,3 +1,4 @@
+import { getContractDetailsService } from "../features/contracts/services";
 import { getOrgUnitBasicDataService } from "../features/org-units/services";
 import { getRolesIdsService } from "../features/roles/services";
 import { RoleData } from "../features/roles/types";
@@ -17,6 +18,7 @@ import {
   getUsersByOrgUnitIdService,
 } from "../features/users/services";
 
+import type { ContractData } from "../features/contracts/types";
 import type { OrgUnitBasicData } from "../features/org-units/types";
 import type { AuthRouteProps, LoaderData } from "../features/shared/types";
 import type {
@@ -35,6 +37,7 @@ export type UsersPageData = {
   context: {
     clientContext: ClientContext;
     currentOrgUnit: OrgUnitBasicData | null;
+    currentContract: ContractData | null;
     currentUser: UserData | null;
     rolesOptions: RoleData[];
   };
@@ -44,6 +47,7 @@ export type UsersPageData = {
 
 export type UsersPageQuery = GetUsersByOrgUnitIdServiceProps & {
   orgUnitId: string;
+  contractId?: string;
   search?: string;
   page?: string;
 };
@@ -51,7 +55,7 @@ export type UsersPageQuery = GetUsersByOrgUnitIdServiceProps & {
 const loaderFunction = async (
   data: LoaderData<UsersPageQuery>
 ): Promise<AuthRouteProps<UsersPageData>> => {
-  const { orgUnitId, search = "", page = "1" } = data.query;
+  const { orgUnitId, contractId, search = "", page = "1" } = data.query;
 
   return withAuthLoader(
     data,
@@ -71,30 +75,48 @@ const loaderFunction = async (
             clientContext: { cookie, userId, customerId, ...clientContext },
             currentUser: null,
             currentOrgUnit: null,
+            currentContract: null,
             rolesOptions: [],
           },
         };
       }
 
-      const [currentOrgUnit, usersResponse, user, rolesOptions] =
-        await Promise.all([
-          getOrgUnitBasicDataService({
-            id: orgUnitId,
-            cookie,
-          }),
-          getUsersByOrgUnitIdService({
-            cookie,
-            orgUnitId,
-            search: search ?? "",
-            page: validPage ?? 1,
-          }),
-          getUserByIdService({ orgUnitId, userId, cookie }),
-          getRolesIdsService({
+      // 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
+        ? getContractDetailsService({
+            contractId,
             unitId: orgUnitId,
             cookie,
-            customerId,
-          }),
-        ]);
+          })
+        : Promise.resolve(null);
+
+      const [
+        currentOrgUnit,
+        usersResponse,
+        user,
+        rolesOptions,
+        currentContract,
+      ] = await Promise.all([
+        getOrgUnitBasicDataService({
+          id: orgUnitId,
+          cookie,
+        }),
+        getUsersByOrgUnitIdService({
+          cookie,
+          orgUnitId,
+          search: search ?? "",
+          page: validPage ?? 1,
+        }),
+        getUserByIdService({ orgUnitId, userId, cookie }),
+        getRolesIdsService({
+          unitId: orgUnitId,
+          cookie,
+          customerId,
+        }),
+        contractDetailsPromise,
+      ]);
 
       const { users, total } = usersResponse;
 
@@ -116,6 +138,7 @@ const loaderFunction = async (
         context: {
           clientContext: { cookie, userId, customerId, ...clientContext },
           currentOrgUnit,
+          currentContract,
           currentUser: user,
           rolesOptions,
         },