orcaqubits/sf-b2b-apex

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.

| Extension Point | Purpose | Example Use Cases | |---|---|---| | PricingCartCalculator | Custom pricing calculations | Volume discounts, contract pricing, tiered pricing | | ShippingCartCalculator | Shipping rate determination | Carrier integration, zone-based rates | | TaxCartCalculator | Tax calculations | Avalara, Vertex, custom tax engines | | InventoryCartCalculator | Real-time inventory validation | Warehouse checks, ATP calculations |

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

| Object | Access Method | Purpose | |---|---|---| | Cart | request.getCart() | Root cart object with all items and delivery groups | | CartItemList | cart.getCartItems() | Iterable list of all line items | | CartItem | cartItems.get(index) | Individual line item with product, quantity, pricing | | CartDeliveryGroupList | cart.getCartDeliveryGroups() | Shipping delivery groups | | CartDeliveryGroup | deliveryGroups.get(index) | Address, shipping method, delivery charges | | CartDeliveryGroupMethod | Constructor-based | Shipping option with name, cost, carrier |

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

| Limit | Synchronous | Asynchronous | |---|---|---| | SOQL queries | 100 | 200 | | DML statements | 150 | 150 | | CPU time | 10,000 ms | 60,000 ms | | Heap size | 6 MB | 12 MB | | Callouts per transaction | 100 | 100 | | Callout timeout (per call) | 10 s (configurable up to 120 s) | 10 s | | Callout total response size | 12 MB | 12 MB | | Future calls per transaction | 50 | 0 (not allowed from async) | | Queueable jobs per transaction | 50 | 1 |

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()

| Pattern | Returns Value? | Accepts Complex Params? | Use in calculate()? | |---|---|---|---| | Synchronous HTTP | Yes | Yes | Yes -- preferred for real-time data | | @future(callout=true) | No (void only) | No (primitives only) | Not for return values | | Queueable | No (async) | Yes | For post-processing follow-up |

• 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:

| Class | Purpose | |---|---| | ConnectApi.CommerceCart | Create, retrieve, delete carts; add items | | ConnectApi.CommerceCatalog | Product search, category browse | | ConnectApi.CheckoutInput / CartCheckoutOutput | Start and manage checkout |

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

| Artifact | Convention | Example | |---|---|---| | Calculator class | [Purpose]Calculator | VolumePricingCalculator | | Test class | [ClassName]Test | VolumePricingCalculatorTest | | Test data factory | B2BCommerceTestDataFactory | Shared across test classes | | Custom Metadata | Commerce_Config__mdt | Configuration without SOQL cost | | Platform Cache | local.CommerceCache | Frequently accessed pricing data | | Queueable job | [Purpose]Job | ShippingRateLoggerJob |

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', 'calculate', e);
    // Allow checkout to continue with existing prices
}

Best Practices

Bulkification and Performance

• Collect IDs first, single SOQL, map lookup -- never query in a loop
• Use Platform Cache (Cache.Org) for frequently accessed configuration data
• Use Custom Metadata for calculator configuration (free of SOQL limits)
• Use relationship queries to pull parent and child data in a single SOQL

Error Handling

• Wrap calculator logic in try/catch; log errors but allow checkout to continue (graceful degradation)
• Set item-level messages via item.setMessage() for validation errors visible to the buyer
• Distinguish QueryException, CalloutException, and generic Exception
• Never re-throw exceptions unless the error should halt the entire checkout

Testing

• Create a B2BCommerceTestDataFactory class for reusable test data
• Test happy path, empty cart, null product, bulk (200+ items), callout success, and callout failure
• Monitor governor limits in test assertions using Limits class methods
• Use @TestVisible annotation to expose private helper methods for unit testing

Async Processing

• Use Queueable (not @future) for complex async post-processing after calculate()
• Implement Database.AllowsCallouts on Queueable classes that make HTTP calls
• Enqueue at end of calculate() with System.enqueueJob()
• Chain Queueable jobs for multi-step async workflows

---

Fetch the latest Salesforce B2B Commerce Apex developer guide and CartExtension namespace reference for exact method signatures and current governor limits before implementing.