Implementation reference
UCP on Salesforce Commerce Cloud.
Five agent-facing endpoints, what each one maps onto inside SFCC, the compatibility matrix, and the four things that actually break these projects. Written for the architect who has to sign off, not for the buyer who has to be convinced.
{
"version": "1.0.0",
"name": "Your Store",
"capabilities": {
"product_discovery": true,
"checkout": true,
"payment": true,
"order_tracking": true
},
"discovery": {
"endpoint": "/api/ucp/discover"
},
"checkout": {
"mode": "agent_delegated",
"providers": ["stripe", "adyen"]
}
} Served by the cartridge; values come from Business Manager site preferences.
Surfaces
Five endpoints, and what they touch.
Each surface maps onto SFCC machinery you already run. That mapping is the whole design: no shadow catalogue, no second pricing path, no re-certified payments.
-
Declares who you are and which capabilities you support. This is the file an agent reads before it does anything else — if it 404s, nothing downstream matters.
On SFCC
Served by a cartridge controller, cached at the CDN. Values come from Business Manager site preferences, so merchandisers change them without a code deploy.
-
Search and retrieve products with prices, availability, variants, and the attributes an agent needs to choose between merchants.
On SFCC
Reads through OCAPI Shop API or SCAPI, so price books, promotions, and inventory lists behave exactly as they do on the storefront. No shadow catalogue to keep in sync.
-
Creates a server-side cart with real tax, shipping, and promotion calculation, then returns the state an agent needs to confirm.
On SFCC
Maps onto SFCC basket calculation, so your existing tax service, shipping methods, and promotion engine run unchanged.
-
Accepts a delegated payment credential and settles through your existing PSP. You remain the merchant of record.
On SFCC
Wraps your current payment processor hook, which is why an implementation does not require re-certifying payments.
-
Post-purchase state for the agent that placed the order: fulfilment, tracking, and returns eligibility.
On SFCC
Reads order data through OCAPI or SCAPI with the same auth model as the rest of the integration.
Discovery manifest
GET /.well-known/ucpProduct discovery
GET /api/ucp/discoverCheckout session
POST /api/ucp/checkout/sessionsPayment handler
POST /api/ucp/checkout/sessions/{id}/payOrder status
GET /api/ucp/orders/{orderNo}Compatibility
What it runs on.
Stated plainly, including where the answer is no. SiteGenesis is the one that catches teams out — the controller conventions differ enough that it is a port, not an install.
- SFRA
- 6.x and above
- Drop-in cartridge following SFRA conventions
- SiteGenesis
- Not supported
- Controller conventions differ; a port is custom work
- API layer
- OCAPI Shop API or SCAPI
- Either works; SCAPI preferred on newer instances
- Headless (PWA Kit)
- Supported
- The protocol layer is independent of the front end
- Payments
- Existing PSP
- Wraps your current processor hook rather than replacing it
- Multi-site
- Per-site configuration
- Site preferences are per site; one cartridge serves several
- Licence
- MIT
- Read, fork, and audit before you engage anyone
Failure modes
What actually breaks these projects.
None of these are protocol problems. All four are the reason an SFCC agent project slips, and all four are cheaper to handle before the build than after.
Bot mitigation blocks the agent before your code runs
The most common cause of a failed SFCC agent integration has nothing to do with the cartridge. eCDN WAF rules, rate limits, and challenge pages reject non-browser clients, so the manifest is unreachable and the audit reports a 404 that your team cannot reproduce in a browser. Allowlist agent traffic and the named AI crawlers first.
Catalogue attributes that never mattered for humans
Agents compare on structured attributes. Dimensions, materials, compatibility, and return terms are frequently blank on 30-50% of SKUs in a long-lived SFCC catalogue, because the storefront rendered them from copy. That data work is usually the longest task in the project — longer than the protocol code.
Price and promotion parity
If the agent path calculates prices differently from the storefront, you get support tickets and lost trust. Running discovery and checkout through the same OCAPI or SCAPI calculation is what prevents this, and it is why we do not build a separate pricing path.
Attribution that reports nothing
Agent sessions do not generate the pageviews your analytics expects. Instrument the protocol layer server-side — session created, checkout created, payment settled, order placed — or the channel will look like zero revenue in reporting while orders arrive.
Questions
Asked most often.
Can AI agents buy from a Salesforce Commerce Cloud store?
Yes, once the store exposes a UCP discovery manifest and agent-callable checkout. SFCC has no native agent checkout surface, so this is added as a cartridge that maps UCP endpoints onto OCAPI or SCAPI. Our ucp-sfcc cartridge does exactly that and is MIT-licensed on GitHub — discovery manifest, product discovery, checkout sessions, payment handler, and order status, on SFRA 6.x and above.
Does the cartridge replace SFCC checkout?
No. It adds a second path to the same basket calculation. Tax service, shipping methods, promotion engine, and payment processor all run unchanged, and you remain the merchant of record. The storefront checkout is untouched.
OCAPI or SCAPI — which should we use?
Either works. SCAPI is the better choice on newer instances and where you are already migrating; OCAPI Shop API is fine on established estates and often faster to ship because the client credentials and permissions already exist. The protocol surface is identical to the agent either way.
How long does UCP on SFCC take?
6 to 14 weeks for a typical enterprise SFCC estate, and the protocol code is rarely the long pole. Catalogue attribute enrichment, WAF and bot-mitigation changes, and payment sign-off usually take longer than the integration itself. Headless and heavily customised stacks run 8 to 16 weeks.
Can we implement it ourselves?
Yes. The cartridge is MIT-licensed and the installation guide is public. Teams with SFCC platform experience and available capacity do this without help. What engagements typically buy is the surrounding work — attribute enrichment across the catalogue, WAF policy, payment certification, and the measurement layer that makes the channel reportable.