Salesforce B2B Commerce Apex Extensions (CartExtension Namespace)

Before Writing Code

ALWAYS fetch live documentation BEFORE writing any Apex code:

1. Web-search: "Salesforce B2B Commerce Apex developer guide 2026"
2. Web-search: "Salesforce B2B Commerce checkout integration Spring 2026"
3. Web-fetch official Salesforce documentation for:
   • B2B Commerce ConnectApi namespace reference
   • CartExtension namespace and AbstractCartCalculator class
   • Apex governor limits (latest release notes)
   • Test class requirements and best practices
4. Web-fetch: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/
5. Web-fetch: https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-cart-calculate.html

Why this matters: Salesforce releases three times per year (Spring, Summer, Winter). Commerce APIs, CartExtension interfaces, and governor limits change. Live docs prevent using deprecated patterns.

Conceptual Architecture

CartExtension Namespace Overview

Salesforce B2B Commerce uses the CartExtension namespace to provide extension points for customizing checkout logic. Each calculator extends CartExtension.AbstractCartCalculator and overrides the calculate() method.

Calculator Lifecycle

1. Customer adds items to cart or initiates checkout
2. Platform invokes registered calculator's calculate() method
3. Calculator receives CartCalculateCalculatorRequest with access to the full cart
4. Calculator reads cart items via request.getCart(), which returns a CartExtension.Cart
5. Calculator performs business logic (SOQL queries, external callouts, computations)
6. Calculator writes results back to cart items (prices, tax amounts, shipping methods, inventory status)
7. Platform validates results and continues to the next checkout step

Key CartExtension Objects

Note: CartItemList uses index-based access (get(i)) and size(), not enhanced for-loops.

Calculator Registration (UI-Only)

Register calculators via the Salesforce UI. There is NO custom metadata type (B2B_Commerce_Hook__mdt or similar) for registration.

1. Navigate to Commerce Setup > Integrations > Register Cart Calculator
2. Select the calculator type (Pricing, Shipping, Tax, or Inventory)
3. Assign your Apex class that extends the appropriate abstract class
4. Registration is per-store -- each B2B store can have its own calculator implementations
5. Only one calculator per type per store can be active at a time

Governor Limits

Custom Metadata queries do NOT count against SOQL limits. Always verify these limits against the current release notes -- values change across Salesforce releases.

Bulkification Rules

B2B carts can have hundreds of line items. All calculator code must be bulkified:

• Collect all product IDs in a single pass over cart items
• Execute one SOQL query using WHERE Id IN :idSet
• Use Map<Id, SObject> for O(1) lookups when applying results
• Never place SOQL or DML inside a loop
• Use List<SObject> for batch DML operations
• Use relationship queries (parent-child SOQL) to reduce query count further

Callout Patterns Within calculate()

• Always use Named Credentials (callout:MyCredential/path) -- never hardcode auth headers
• Set explicit timeouts on all callouts (req.setTimeout(10000))
• Implement fallback logic when external services are unavailable

ConnectApi Namespace

The ConnectApi namespace provides programmatic cart and checkout operations:

ConnectApi classes are not constructable in test context by default. Use wrapper/mock patterns or Test.isRunningTest() guards for testability.

Test Requirements

• 75% minimum code coverage required for deployment; aim for 85%+ for calculators
• Use @TestSetup to create shared test data (Account, Product2, WebStore, WebCart, CartDeliveryGroup, CartItem)
• CartCalculateCalculatorRequest is not directly constructable in tests -- test business logic methods separately
• Use Test.setMock(HttpCalloutMock.class, ...) for callout tests
• Assert governor limits with Limits.getQueries(), Limits.getDmlStatements(), Limits.getCpuTime()
• Required test scenarios: empty cart, null product reference, zero quantity, bulk (200+ items), callout success, callout failure, graceful degradation

Naming Conventions

Code Examples

Pattern: CartExtension calculator skeleton

public class MyCalculator extends CartExtension.PricingCartCalculator {
    public override void calculate(
        CartExtension.CartCalculateCalculatorRequest request
    ) {
        CartExtension.Cart cart = request.getCart();
        // Fetch live docs for CartCalculateCalculatorRequest API
    }
}

Pattern: Bulkified query + map lookup

Set<Id> ids = new Set<Id>();
// ... collect ids from cart items ...
Map<Id, Product2> products = new Map<Id, Product2>(
    [SELECT Id, Field__c FROM Product2 WHERE Id IN :ids]
);
// ... apply via products.get(itemProductId) ...

Pattern: HttpCalloutMock for tests

private class MockResponse implements HttpCalloutMock {
    public HttpResponse respond(HttpRequest req) {
        // Fetch live docs for HttpCalloutMock interface
    }
}

Pattern: Graceful error handling in calculate()

try {
    applyPricing(cartItems);
} catch (CalloutException e) {
    CommerceLogger.logError('Calculator', 'cal