Configuration & Discovery

This section details how to enable UCP for your storefront in Salesforce Commerce Business Manager. Those settings power your business profile — the document platforms fetch to learn what you support before they start a checkout.

This is how platforms discover your capabilities (services, payment handlers, protocol version). Product discovery and platform onboarding are platform-specific; for Google, see Enabling Google as a Platform. To call Checkout Session APIs after the profile is published, see Checkout Session Authentication.

Business Profile

Platforms do not start at checkout. They retrieve your business profile from a well-known URL. B2C Commerce publishes that profile from the UCP settings you save in Business Manager. The discovery endpoint is unauthenticated and is meant to be called before any checkout-session request. Checkout Session APIs themselves require SLAS; see Checkout Session Authentication.

Starting with B2C Commerce release 26.9, Salesforce publishes a versioned profile:

Endpoint	What it returns
`GET /.well-known/ucp`	The root profile at your preferred protocol version, plus a `supported_versions` map of other versions this release can serve
`GET /.well-known/ucp/{version}`	A complete leaf profile pinned to that protocol version. Leaf profiles do not include `supported_versions`

1https://{shortCode}.api.commercecloud.salesforce.com/ucp/shopper-ucp/v1/organizations/{instanceId}/sites/{siteId}/.well-known/ucp
2https://{shortCode}.api.commercecloud.salesforce.com/ucp/shopper-ucp/v1/organizations/{instanceId}/sites/{siteId}/.well-known/ucp/{version}

Replace {shortCode}, {instanceId}, and {siteId} with values for your instance and site.

After you save UCP settings in Business Manager, GET the root well-known URL and confirm the profile before you test checkout sessions. Check that ucp.version, capabilities, and payment handlers match what you configured.

What the profile advertises

The profile declares:

Services — the shopping API endpoint platforms use for checkout sessions
Capabilities — checkout, fulfillment, and order (order is advertised so platforms can receive lifecycle webhooks; there is no shopper Order GET in this release)
Payment handlers — how the platform should acquire payment credentials (assembled from Business Manager when you use Salesforce Payments)
Signing keys — public keys platforms use to verify order lifecycle events

Business Manager setting	Where it shows up
UCP Active	Profile and checkout APIs are served only while UCP is enabled
Payment Provider, Payment Zone, Google Pay Merchant ID / Name, Storefront URL	`ucp.payment_handlers` on the profile (Salesforce Payments path)
Saving UCP settings	`signing_keys` generated automatically on the profile

Continue URL, Privacy Policy URL, and Order Lookup URL are returned on checkout session responses, not on the well-known profile. Configure them in UCP Checkout Settings.

Protocol versions

B2C Commerce release 26.9 supports protocol versions 2026-01-23 and 2026-04-08. The root profile is a single version. Other supported versions appear in ucp.supported_versions as URLs to the leaf endpoint.

If a platform requests a version this release does not support, GET /.well-known/ucp/{version} returns HTTP 422 with the UCP error code version_unsupported.

Customizing the profile

Salesforce assembles the default profile from Business Manager. To replace payment handlers — for example when you use a third-party payment provider — implement sfcc.ucp.shopperBusinessProfiles.v1.businessProfile.modifyGETResponse. Do not change ucp.version in that hook.

Note

UCP Checkout Settings

Navigate to Merchant Tools > AI & Social Integrations > UCP to configure the protocol. The fields on this screen are what B2C Commerce writes into the business profile and checkout session responses.

Mandatory URLs

URL	Description
Storefront URL	Your live site’s base domain
Privacy Policy URL	Direct link to your legal privacy terms
Order Lookup URL	Direct link to order lookup page
Continue URL (Handoff Path)	URL returned on checkout session responses when a session cannot finish on the platform (such as age verification or complex promotions)

Continue URL - Limitations

Salesforce returns this URL on checkout session responses when a session cannot finish on the platform. Whether the platform shows it, how it is labeled, and when the shopper is sent there is up to the platform. You cannot control that UX.

If a platform does send the shopper to your Continue URL:

Without a storefront plugin, they land with an empty cart and must re-add items. Avoid that handoff when you can by handling the case in hooks. If you cannot, use a landing page that explains why they are on your site and links to the products they were buying.
With the SFRA plugin plugin_universal_commerce_protocol, the UCP basket is promoted onto the storefront so they land on checkout with their items intact. See the plugin README for installation, hybrid auth, cartridge path, service credentials, and extension hooks.

When you use the plugin, the Continue URL field in Merchant Tools > AI & Social Integrations > UCP must point to the plugin’s route with the basketId and usid placeholders. UCP substitutes those values at handoff time. If they are missing, the plugin has nothing to promote and the buyer lands with an empty cart.

1https://{storefrontDomain}/on/demandware.store/Sites-{SiteId}-Site/{locale}/UCPContinue-Start?basketId={basketId}&usid={usid}

Replace {storefrontDomain}, {SiteId}, and {locale} with values for your site. Leave {basketId} and {usid} literal — those are UCP’s substitution tokens, not values you fill in.

Payment Provider Setup

In the “Payment Setup” section of the UCP Configuration screen, choose which Payment Provider you will be using for UCP checkout:

Salesforce Payments (default) — the platform assembles the Google Pay / Salesforce Payments handler automatically from the Payment Zone, Google Pay Merchant ID, and Google Pay Merchant Name fields.
Third Party Provider (DIY) — hides the Salesforce Payments fields and expects your custom hook implementation to provide the payment configuration. See Third-Party Payment Providers.

For this release, Google Pay is the only payment method the native Salesforce Payments handler advertises, whether you choose Salesforce Payments or a third-party payment provider. Google as a platform still expects Google Pay today.

Salesforce Payments

If you choose to use Salesforce Payments as your UCP payment engine (the default), the Salesforce Payments SKU is required. You can use Adyen via Salesforce Payments or Stripe Salesforce Payments. Because the native Salesforce Payments path uses Google Pay, Google Pay must be active in your gateway dashboard.

Locate your Google Pay Merchant ID and Merchant Name from the Google Pay Console to enter into Business Manager.
For Adyen via Salesforce Payments, the ID must match the Google Pay Merchant ID listed as the MID in your Live Adyen Customer Area.
For Stripe via Salesforce Payments, Google Pay must be enabled on the Stripe account used by the payment zone.

Auto-Fail Orders

Navigate to Merchant Tools > Site Preferences > Order and set Auto-Fail Orders (in minutes). Salesforce Payments places orders asynchronously; set this long enough for the Adyen or Stripe webhook to arrive.

Adyen 3rd Party Cartridge Users

If you’re using the Adyen 3PP cartridge for processing adyenNotifications, configure the Process job to run more frequently than the AutoFail order job’s timeout. This ensures webhooks are processed before orders become eligible for auto-failing. Under normal conditions, only orders that receive no webhook within the timeout window will be auto-failed. If a webhook arrives later, the AUTHORISATION handler attempts recovery as designed.

Additionally, consider these site preferences to make the recovery process more resilient:

OversellWhenUndoFailOrder - prevents inventory contention from blocking order recovery
SkipCouponRedemptionLimitWhenUndoFailOrder - prevents coupon limits from blocking order recovery

Note

Security

Upon saving, the system automatically generates signing keys (private/public) to secure Order lifecycle event delivery to the platform. Checkout Session APIs are authorized with a SLAS shopper token; see Checkout Session Authentication.

Order Management System (OMS) Integration

Properly setting up your OMS to work with UCP enables customers to receive automatic shipping updates or status changes within the platform experience. This is in addition to other provided order tracking through existing channels (email, your website).

Salesforce OMS integration is optional for UCP:

With Salesforce OMS: Out of the box full order lifecycle event tracking to the platform (shipping confirmations, cancellations, status updates)
Third Party OMS: You can connect an external Order Management System so it serves order data through the same Shopper Orders and Shopper Customers SCAPIs. See Connect a Third-Party OMS.

Disabling or Rolling Back UCP

To temporarily disable UCP or roll back the integration:

Disabling UCP

To disable UCP while keeping your configuration intact:

Navigate to Merchant Tools > AI & Social Integrations > UCP in Business Manager
Turn UCP Active off
Save the settings

Effect

New orders from the platform fail to initiate
The system aborts in-flight checkout sessions
If using Google, your product feed in GMC remains active but products aren’t available for purchase through Google
All configuration is preserved for when you re-enable