BackPort Update from Main

CLAUDE.md

@@ -0,0 +1,91 @@
+# Commerce Extensibility Repository
+
+Sample implementations for extending Salesforce Commerce services (pricing, buyer groups, tax, shipping, checkout, etc.).
+
+## Repository Structure
+
+```
+commerce/
+├── domain/      # Business logic extensions (pricing, tax, buyer groups, etc.)
+└── endpoint/    # API extensions (cart, search, account)
+```
+
+---
+
+## Apex v67.0 Migration
+
+Reference: [Apex Release Notes - Summer '26](https://help.salesforce.com/s/articleView?id=release-notes.rn_apex.htm&release=262&type=5)
+
+When a user asks to migrate files for Apex v67.0, follow this process:
+
+#### Step 1: Analyze
+
+Scan `.cls` files and identify issues based on the v67.0 Secure by Default changes:
+
+**Sharing Keywords** - Classes without a sharing keyword now default to `WITH SHARING`:
+```apex
+// Explicitly declare the sharing mode you need
+public without sharing class MyExtension { }
+public with sharing class MyExtension { }
+public inherited sharing class MyExtension { }
+```
+
+**Query Mode** - Queries now run as `USER_MODE` by default:
+```apex
+// Add WITH SYSTEM_MODE only if you need to bypass user permissions
+[SELECT Id FROM Account WHERE Id = :id WITH SYSTEM_MODE]
+```
+
+**DML Access Level** - DML operations now run as `USER_MODE` by default:
+```apex
+// Add SYSTEM_MODE only if you need to bypass user permissions
+Database.insert(records, AccessLevel.SYSTEM_MODE);
+insert as system records;
+```
+
+**Deprecated Syntax** - `WITH SECURITY_ENFORCED` is deprecated:
+```apex
+// ❌ Deprecated
+[SELECT Name FROM Account WITH SECURITY_ENFORCED]
+
+// ✅ Use WITH USER_MODE
+[SELECT Name FROM Account WITH USER_MODE]
+```
+
+#### Step 2: Show Diff to User
+
+Present each change clearly with file name, line numbers, what will change, and why.
+
+If user asks, show detailed before/after diff for each change.
+
+#### Step 3: Get Approval
+
+```
+Should I apply these X changes across Y files? (yes/no)
+
+Reply 'yes' to proceed, or ask me to show details for any file.
+```
+
+**Wait for explicit "yes" before proceeding.**
+
+#### Step 4: Apply Changes
+
+1. Update code with required changes
+2. Keep API version unchanged (backward compatibility)
+3. Preserve existing formatting
+
+#### Step 5: Report
+
+```
+✅ Migration complete!
+
+Updated:
+- File1.cls (4 queries, docs)
+- File2.cls (docs only)
+
+Next steps:
+1. Review changes
+2. Run tests
+3. Commit when ready
+```
+

README.md

@@ -8,8 +8,11 @@ This repository contains a reference implementation of the Commerce Extensibilit
 	- Shipping Calculator
 	- Tax Calculator
 	- Tax Service
-- [Domain Extension for Checkout](#domain-extension-for-checkout)
-	- Checkout Create Order
+- [Domain Extensions for Checkout](#domain-extensions-for-checkout)
+	- CreateOrder Service
+	- SplitShipment Service
+- [Domain Extensions for Buyer Group](#domain-extensions-for-buyer-group)
+	- Buyer Group Extensibility Service
 
 Each set of sample code includes: an Apex class, a test class, and any necessary resource files.
 
@@ -37,7 +40,7 @@ The sample code for Shipping Calculator includes an Apex class (in `ShippingCalc
 
 ### Tax Calculator
 
-The sample code for Tax Calculator includes an Apex class (in `TaxCalculatorSample.apxc`) that calls an external service to retrieve tax information and then save those taxes in `CartTaxes` in `CartItems` and `CartItemAdjustments`.
+The sample code for Tax Calculator includes an Apex class (in `TaxCalculatorSample.apxc`) that calls an external service to retrieve tax information and then save those taxes in `CartTaxes` in `CartItems`.
 
 ### Tax Service
 
@@ -54,15 +57,32 @@ All error cases are propagated to the admin as CommerceDiagnosticEvents (see [Co
 
 All reference implementations include examples of how to propagate an error to the user.
 
-## Domain Extension for Checkout
-### Checkout Create Order
+## Domain Extensions for Checkout
 
-The sample code for [Checkout Create Order](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/CheckoutCreateOrder.html) extension point includes an Apex class (see [CreateOrderSample.cls](commerce/domain/checkout/order/createOrder/classes/CreateOrderSample.cls) that provides an example of how to work with the [OrderGraph](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/OrderGraph.html).
+### CreateOrder Service
 
-A unit test (see [CreateOrderSampleUnitTest.cls](commerce/domain/checkout/order/createOrder/classes/CreateOrderSampleUnitTest.cls))) that follows this approach for [Mocking the Base Apex Class in Tests](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/mock-the-base-apex-class.html).
+The sample code for the [CreateOrder Service](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/CheckoutCreateOrder.html) extension point includes an Apex class (see [CreateOrderSample.cls](commerce/domain/checkout/order/createOrder/classes/CreateOrderSample.cls)) that provides an example of how to work with the [OrderGraph](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/OrderGraph.html).
+
+A unit test (see [CreateOrderSampleUnitTest.cls](commerce/domain/checkout/order/createOrder/classes/CreateOrderSampleUnitTest.cls)) that follows this approach for [Mocking the Base Apex Class in Tests](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/mock-the-base-apex-class.html).
 
 Also, there is an "integration" test (see [CreateOrderSampleIntegrationTest.cls](commerce/domain/checkout/order/createOrder/classes/CreateOrderSampleIntegrationTest.cls)) that verifies implementation of the CreateOrder extension that calls real default extension point behavior. This testing approach can be used in addition to unit test, it has wider test coverage, but it is less isolated than unit test presented in the example below.
 
+### SplitShipment Service
+
+The sample code for the [SplitShipment Service](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/SplitShipmentService.html) extension point includes an Apex class (see [SplitShipmentSample.cls](commerce/domain/shipping/splitshipment/SplitShipmentSample.cls)) that creates cart delivery groups by conveyable and non-conveyable products. 
+
+Another example (see [SplitShipmentCallsSuper.cls](commerce/domain/shipping/splitshipment/SplitShipmentCallsSuper.cls)) calls the default implementation.
+
+Also, there is a unit test (see [SplitShipmentUnitTest.cls](commerce/domain/shipping/splitshipment/SplitShipmentUnitTest.cls)) that follows this approach for [Mocking the Base Apex Class in Tests](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/mock-the-base-apex-class.html).
+
+## Domain Extensions for Buyer Group
+
+### Buyer Group Extensibility Service
+
+The sample code for Buyer Group Extensibility Service includes the following :
+- An Apex class (in `BuyerGroupEvaluationServiceSample.apxc`) that uses active postal codes to retrieve buyer groups for logged in and guest users.
+- An Org Platform Cache (in `BuyerGroup.cachePartition`) to support low latency in buyer group retrieval.
+- Supported Custom objects for storing and associating buyer groups to users via postal codes.(in `PostalCode__c`, `Active_PostalCode__c` and `Postal_Code_Buyer_Group__c`)
 
 ## Deployment
 

commerce/domain/buyergroup/service/cachePartitions/BuyerGroup.cachePartition-meta.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PlatformCachePartition xmlns="http://soap.sforce.com/2006/04/metadata">
+    <isDefaultPartition>true</isDefaultPartition>
+    <masterLabel>BuyerGroup</masterLabel>
+    <platformCachePartitionTypes>
+        <allocatedCapacity>0</allocatedCapacity>
+        <allocatedPartnerCapacity>0</allocatedPartnerCapacity>
+        <allocatedPurchasedCapacity>0</allocatedPurchasedCapacity>
+        <allocatedTrialCapacity>0</allocatedTrialCapacity>
+        <cacheType>Session</cacheType>
+    </platformCachePartitionTypes>
+    <platformCachePartitionTypes>
+        <allocatedCapacity>10</allocatedCapacity>
+        <allocatedPartnerCapacity>0</allocatedPartnerCapacity>
+        <allocatedPurchasedCapacity>0</allocatedPurchasedCapacity>
+        <allocatedTrialCapacity>0</allocatedTrialCapacity>
+        <cacheType>Organization</cacheType>
+    </platformCachePartitionTypes>
+</PlatformCachePartition>

commerce/domain/buyergroup/service/classes/BuyerGroupEvaluationServiceSample.cls

@@ -0,0 +1,101 @@
+/**
+ * BuyerGroupEvaluationServiceSample is a sample implementation of the BuyerGroupEvaluationService used to determine buyer group IDs for a user (guest or logged-in).
+ * The use case for this sample implementation is as follows:
+ * - Out-of-the-box buyer groups based on account, market, and data cloud segment should be returned for both logged-in and guest users.
+ * - In addition, if the user is a guest or logged-in, then the buyer groups associated with the active postal code stored using deviceId should also be returned.
+ * - For logged-in users, the buyer groups associated with the BillingPostalCode and ShippingPostalCode of the Account linked to the user are also returned.
+ *
+ * Data model changes to support the sample code are as follows:
+ * - PostalCode__c: Stores the supported postal codes in the PostalCode field.
+ * - Active_PostalCode__c: Stores the association between deviceId (Guest UUID cookie value) and PostalCode__c.
+ *                          This can typically be populated via a custom LWC component where a customer chooses a postal code from a list of available postal codes.
+ * - Postal_Code_Buyer_Group__c: A junction entity that stores a static mapping between PostalCode__c and the buyer groups associated with it.
+ *
+ * Important considerations in the code below:
+ * - Buyer group responses should be cached using Org Cache to support low latency.
+ * - No more than MAX_BUYER_GROUPS should be returned by the code.
+ *
+ * SECURITY CONSIDERATIONS (Secure by Default - Apex v67.0+):
+ *
+ * Starting with Apex v67.0 (Summer '26), all classes must explicitly declare sharing mode and
+ * all queries must specify WITH SYSTEM_MODE or WITH USER_MODE.
+ *
+ * This sample uses:
+ * - WITHOUT SHARING: Buyer group evaluation needs to work for guest users who have no object/field
+ *   permissions. Using "with sharing" would prevent guest users from accessing buyer group data.
+ *
+ * - WITH SYSTEM_MODE for all queries: Guest users need to retrieve buyer group associations, postal
+ *   codes, and account data. WITH USER_MODE would cause permission errors for guest users.
+ *
+ * Note: WITH SYSTEM_MODE is backward compatible (ignored in v64-v66 where it was already the default).
+ *
+ * For more information on Apex Secure by Default, see:
+ * https://help.salesforce.com/s/articleView?id=release-notes.rn_apex.htm&release=262&type=5
+ */
+public without sharing class BuyerGroupEvaluationServiceSample extends commercebuygrp.BuyerGroupEvaluationService {
+
+    private static Integer MAX_BUYER_GROUPS = 30;
+
+    public override commercebuygrp.BuyerGroupResponse getBuyerGroupIds(commercebuygrp.BuyerGroupRequest request) {
+        String currentUserId = UserInfo.getUserId(); // Gets the current user ID; could be a logged-in or guest user
+        String webstoreId = request.getStoreId(); // Gets the webstore record ID
+        String accountId = request.getAccountId(); // Gets the account ID of the user
+        String siteId = ((String) [SELECT SiteId FROM WebstoreNetwork WHERE WebstoreId = :webstoreId WITH SYSTEM_MODE][0].get('SiteId')).substring(0, 15); // Gets the network site ID
+        Map<String, Object> requestParameters = request.getRequestContextParameters();
+        Boolean isGuestUser = (Boolean) requestParameters.get('isGuestUser');
+        String guestUUIDKey = 'guest_uuid_essential_' + siteId; // Gets the guest UUID cookie key for the current webstore
+        String deviceId  = (String) requestParameters.get(guestUUIDKey); // Gets the guest UUID cookie value for the current user and webstore
+
+        String cachePartition = 'local.BuyerGroup';
+        Cache.OrgPartition orgPartition = Cache.Org.getPartition(cachePartition); // Gets the buyer group org cache partition
+
+        // Cache key must be alphanumeric; converting currentUserId and deviceId to a hashed key
+        String cacheKey = EncodingUtil.convertToHex(Crypto.generateDigest('MD5', Blob.valueOf(isGuestUser ? deviceId : currentUserId)));
+        if (orgPartition.contains(cacheKey)) {
+            // Cache hit — return cached buyer groups
+            return new commercebuygrp.BuyerGroupResponse((Set<String>) orgPartition.get(cacheKey));  
+        }
+
+        // Getting default out-of-the-box buyer groups based on existing logic: account, market, and data cloud segment-based buyer groups
+        commercebuygrp.BuyerGroupResponse defaultBuyerGroupResponse = super.getBuyerGroupIds(request);
+        Set<String> buyerGroupIds = new Set<String>(defaultBuyerGroupResponse.getBuyerGroupIds());
+
+        Set<String> activePostalCodes = new Set<String>();
+
+        // If the user is logged in, get the BillingPostalCode and ShippingPostalCode
+        if (!isGuestUser) {
+            SObject currentAccount = [SELECT BillingPostalCode, ShippingPostalCode FROM Account WHERE Id = :accountId WITH SYSTEM_MODE][0];
+            String billingPostalCode = (String) currentAccount.get('BillingPostalCode');
+            String shippingPostalCode = (String) currentAccount.get('ShippingPostalCode');
+            if (billingPostalCode != null) {
+                activePostalCodes.add(billingPostalCode);
+            }
+            if (shippingPostalCode != null) {
+                activePostalCodes.add(shippingPostalCode);
+            }
+        }
+
+        // Get active postal codes for both logged-in and guest users based on their device ID
+        for (Active_PostalCode__c activePostalCode : [SELECT PostalCode__r.PostalCode__c FROM Active_PostalCode__c WHERE DeviceId__c = :deviceId WITH SYSTEM_MODE]) {
+            if (activePostalCode.PostalCode__c != null) {
+                activePostalCodes.add(activePostalCode.PostalCode__r.PostalCode__c);
+            }
+        }
+
+        // Get the buyer groups associated with the postal codes
+        for (Postal_Code_Buyer_Group__c buyerGroup : [SELECT Buyer_Group__c FROM Postal_Code_Buyer_Group__c WHERE PostalCode__r.PostalCode__c IN :activePostalCodes WITH SYSTEM_MODE]) {
+            buyerGroupIds.add(buyerGroup.Buyer_Group__c);
+        }
+
+        // Buyer group extensibility supports only up to MAX_BUYER_GROUPS buyer groups
+        if (buyerGroupIds.size() > MAX_BUYER_GROUPS) {
+            commercebuygrp.BuyerGroupResponse response = new commercebuygrp.BuyerGroupResponse();
+            String errorMessage = 'More than ' + MAX_BUYER_GROUPS + ' buyer groups retrieved for the user. Contact Store Administrator.';
+            response.setError(errorMessage, errorMessage);
+            return response;
+        }
+
+        orgPartition.put(cacheKey, buyerGroupIds);
+        return new commercebuygrp.BuyerGroupResponse(buyerGroupIds);
+    }
+}

commerce/domain/buyergroup/service/classes/BuyerGroupEvaluationServiceSample.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>64.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

commerce/domain/buyergroup/service/classes/BuyerGroupShareableURLSample.cls

@@ -0,0 +1,77 @@
+/**
+ * BuyerGroupShareableURLSample
+ *
+ * This class is a sample implementation of the {@code commercebuygrp.BuyerGroupEvaluationService}.
+ * It demonstrates how to extend the default buyer group evaluation logic to include custom criteria
+ * based on request context parameters. In this case, the custom criterion is the user's region, which
+ * is passed as a URL parameter (e.g., in a shareable URL for the storefront).
+ *
+ * Use Case:
+ * - Retrieve default buyer groups based on standard rules (account, market, and data cloud segments).
+ * - Additionally, include buyer groups associated with the user's region (if provided via request context).
+ *
+ * Notes:
+ * - This example demonstrates extensibility for shareable URLs in the commerce storefront.
+ * - To use this, the region parameter must be explicitly set in the request context via URL.
+ * - When implementing real logic, replace the placeholder region-based filtering with actual mapping logic.
+ *
+ * Limitations:
+ * - Maximum allowed buyer groups is controlled by {@link #MAX_BUYER_GROUPS} (currently set to 30).
+ * - If the number exceeds this limit, an error response is returned instead of the list.
+ *
+ * SECURITY CONSIDERATIONS (Secure by Default - Apex v67.0+):
+ *
+ * Starting with Apex v67.0 (Summer '26), all classes must explicitly declare sharing mode.
+ *
+ * This sample uses:
+ * - WITHOUT SHARING: Buyer group evaluation needs to work for guest users who have no permissions.
+ *   The base implementation (super.getBuyerGroupIds) already handles data access with system-level
+ *   permissions, so this class inherits that security model.
+ *
+ * For more information on Apex Secure by Default, see:
+ * https://help.salesforce.com/s/articleView?id=release-notes.rn_apex.htm&release=262&type=5
+ */
+public without sharing class BuyerGroupShareableURLSample extends commercebuygrp.BuyerGroupEvaluationService {
+
+    /** Maximum number of buyer groups that can be associated with a single user request. */
+    private static final Integer MAX_BUYER_GROUPS = 30;
+
+    /**
+     * Retrieves buyer group IDs for a user, including:
+     *  - Default buyer groups (account, market, data cloud segments).
+     *  - Region-based buyer groups (if region parameter is provided).
+     *
+     * @param request The {@link commercebuygrp.BuyerGroupRequest} containing context parameters.
+     * @return A {@link commercebuygrp.BuyerGroupResponse} with buyer group IDs or an error if the limit is exceeded.
+     */
+    public override commercebuygrp.BuyerGroupResponse getBuyerGroupIds(commercebuygrp.BuyerGroupRequest request) {
+        // Extract context parameters from the incoming request
+        Map<String, Object> requestParameters = request.getRequestContextParameters();
+
+        // Retrieve the custom region parameter passed via shareable URL (e.g., &region=asia)
+        String region = (String) requestParameters.get('region');
+
+        // Get default out-of-the-box buyer groups using base implementation
+        commercebuygrp.BuyerGroupResponse defaultBuyerGroupResponse = super.getBuyerGroupIds(request);
+        Set<String> buyerGroupIds = new Set<String>(defaultBuyerGroupResponse.getBuyerGroupIds());
+
+        // If region is provided and equals "asia", add region-specific buyer groups
+        if (region != null && region.equalsIgnoreCase('asia')) {
+            // Add logic to fetch additional buyer groups for Asia region.
+            // Example: buyerGroupIds.addAll(getRegionSpecificGroups(region));
+        }
+
+        // Enforce maximum limit for buyer groups
+        if (buyerGroupIds.size() > MAX_BUYER_GROUPS) {
+            // Create error response when limit exceeds
+            commercebuygrp.BuyerGroupResponse response = new commercebuygrp.BuyerGroupResponse();
+            String errorMessage = 'More than ' + MAX_BUYER_GROUPS + ' buyer groups retrieved for the user. Contact Store Administrator.';
+            response.setError(errorMessage, errorMessage);
+            return response;
+        }
+
+
+        // Return final response with allowed buyer group IDs
+        return new commercebuygrp.BuyerGroupResponse(buyerGroupIds);
+    }
+}

commerce/domain/buyergroup/service/classes/BuyerGroupShareableURLSample.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>65.0</apiVersion>
+    <status>Active</status>
+</ApexClass>