--- schema_version: "1" id: 1f127b10512a596497eb99723a3c6be73f8d4eadf89f3d962d57f796b3efd006 title: Configuration and Discovery collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-configuration.md canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.html source_site: developer.salesforce.com content_type: documentation content_hash: ddb1cbc89db82df657f665cb460a81bb2ff11da3d3ffc9a256d47192c3506632 products: - Composable Storefront - Salesforce APIs --- # Configuration and Discovery 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-google-gmc-configuration.md). To call Checkout Session APIs after the profile is published, see [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md). ## Business Profile Platforms don't 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md). 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 don't include `supported_versions` | ``` https://{shortCode}.api.commercecloud.salesforce.com/ucp/shopper-ucp/v1/organizations/{instanceId}/sites/{siteId}/.well-known/ucp https://{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 acquires 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](#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 doesn't support, `GET /.well-known/ucp/{version}` returns HTTP `422` with the UCP error code `version_unsupported`. **note:** **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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#third-party-payment-providers)—implement `sfcc.ucp.shopperBusinessProfiles.v1.businessProfile.modifyGETResponse`. Don't change `ucp.version` in that hook. ## UCP Checkout Settings Go 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 can't 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 can't 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 can't 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 can't, 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`](https://github.com/SalesforceCommerceCloud/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. ``` https://{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, select which **Payment Provider** you use 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#third-party-payment-providers). For this release, Google Pay is the only payment method the native Salesforce Payments handler advertises, whether you select Salesforce Payments or a third-party payment provider. Google as a platform still expects Google Pay today. #### Salesforce Payments If you 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 Go 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. **note:** **Adyen third-party cartridge users** If you're using the Adyen third-party cartridge for processing `adyenNotifications`, configure the Process job to run more frequently than the AutoFail order job's timeout. This makes sure webhooks are processed before orders become eligible for auto-failing. Under normal conditions, only orders that receive no webhook within the timeout window are auto-failed. If a webhook arrives later, the AUTHORISATION handler attempts recovery as designed. 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 ### Security When you save, the platform 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md). ## Order Management System (OMS) Integration Set up your OMS to work with UCP so customers can 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:** 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/commerce-apps/connect-third-party-oms.md). See [Order Post-Processing Events](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-order-post-processing-events.md) for how those events become signed UCP snapshots. ## Disable or Roll Back UCP Turn **UCP Active** off to disable UCP or roll back the integration. Your Business Manager settings stay in place. ### Disable UCP To disable UCP while keeping your configuration intact: 1. Go to **Merchant Tools > AI & Social Integrations > UCP** in Business Manager 2. Turn **UCP Active** off 3. 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