--- schema_version: "1" id: 15256de95c396bbb6c903e2128ef3877059f977c820561d2d7de22bb84e74195 title: Shopper SEO collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-seo.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo source_site: developer.salesforce.com content_type: documentation content_hash: f92ef044c89e45eba559524efdc97ee000647647f7c63d8fd63a0d15b0695fb2 products: - B2C Commerce API - Salesforce APIs --- Shopper SEO # Shopper SEO [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-seo/shopper-seo-oas-v1-public.yaml) ## API Overview The Shopper SEO API Provides access to SEO-related information, such as URL mapping information. ### Authentication & Authorization The Shopper SEO API requires a shopper access token from the [Shopper Login and API Access Service (SLAS).](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) You must include the relevant scope(s) in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides. ### Customization #### Hooks For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) ### Response Details #### Personalization Responses from this API are not personalized via the Shopper Context API. #### Caching Caching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) #### Timeouts Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html) #### Error Handling Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html) ### Use Cases #### Resolve a URL Resolve a URL path to its resource type (product, category, or content page). ```sh curl "https://{shortCode}.api.commercecloud.salesforce.com/site/shopper-seo/v1/organizations/{organizationId}/url-mapping?urlSegment=new-arrivals-tops&siteId=RefArch" \ -H "Authorization: Bearer {access_token}" ``` #### URL Resolution For information on setting up URL rules and URL redirects in Business Manager, see [URL Resolution.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-resolution.html) ### Related APIs * [SEO (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/seo?meta=Summary) — Manage SEO URL rules and redirects. **Version:** 1.3.1 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/site/shopper-seo/v1` * `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)` ## Security * `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-seo: Allows read operations on shopper seo. * OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-seo: Allows read operations on shopper seo. * `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context) * Scope sfcc.shopper-seo: Allows read operations on shopper seo. ## Operations ### GET Get URL mapping information for a URL segment. `GET /organizations/{organizationId}/url-mapping` Operation ID: `getUrlMapping`. Security: ShopperToken (sfcc.shopper-seo); ShopperClientContextToken (sfcc.shopper-seo). The mapping information is based on URL rules and redirects that are set up in Business Manager. For more information about prerequisites and sample usage, see [URL Resolution](/docs/commerce/commerce-api/guide/url-resolution.html). You can customize the behavior of this endpoint by using hooks. For details, refer to the [Hook List](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook_list.html). #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `urlSegment` (query, string, required) The part of the requested URL that comes after the domain name. For example, the urlSegment for "www.abc.com/blue/new-arrivals/tops" is "blue/new-arrivals/tops". There's no limit on the length of the urlSegment. However, for this endpoint, the maximum allowed length of the URL (after URL encoding) is 2047 characters. Make this field URL-encoded so that it properly handles special values such as whitespace. If a urlSegment includes a query string, a 404 error code is returned. Minimum length: 1. Maximum length: 2047. Example: `mens/clothing/shorts`. * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` * `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified. _Example: LanguageCountry_ ``` en-US ``` _Example: CountryCode_ ``` US ``` * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. * `personalized` (query, string) Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer. When set to `none`, the server skips applying personalization to the response. Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html). Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Returns URL mapping information for a URL that a shopper entered or selected. Media type: `application/json`. Schema: `UrlMapping`. _Example: UrlMappingCategory_ URL mapped to a category with refinements. ``` { "resourceType": "CATEGORY", "resourceId": "new-arrivals-tops", "refinements": { "refinementColor": "Blue" } } ``` _Example: UrlMappingProduct_ URL mapped to a product. ``` { "resourceType": "PRODUCT", "resourceId": "25695327M" } ``` _Example: UrlMappingContentAsset_ URL mapped to a content asset. ``` { "resourceType": "CONTENT_ASSET", "resourceId": "about-us" } ``` * **400** The locale is invalid. Make sure you provide a locale using the correct format: ISO 639-1 for the language code and ISO 3166-1 for the country code. For example, en-US. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getUrlMapping400_ ``` { "title": "Unknown Locale", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unknown-locale", "detail": "The locale 'ab-CD' is unknown.", "locale": "ab-CD" } ``` * **401** The user making the call isn't authorized to make this request. For example, the correct scope wasn't added to an SLAS API Client or the access token is invalid or missing. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getUrlMapping401_ ``` { "title": "Invalid Access Token", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token", "detail": "The request is unauthorized, the access token is invalid.", "accessToken": "hbGciOiJIUzI1NiIsInR5cCI6Ikp" } ``` * **404** No mapping information for the requested URL exists because there's no corresponding URL rule in Business Manager. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getUrlMapping404_ ``` { "title": "Seo Url Mapping Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/seo-url-mapping-not-found", "detail": "black/mens/accessories/luggage", "urlSegment": "black/mens/accessories/luggage", "locale": "en_US" } ``` ## Schemas ### OrganizationId An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### SiteId The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### LocaleCode A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified. One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`. ### UrlMapping The URL mapping information for a URL that a shopper clicked or typed in. * `resourceType` (_string_) The type of resource that corresponds to the requested URL. If you set up a URL redirect in Business Manager, resourceType returns the corresponding destination type value from the redirect. If there's a URI redirect, resourceType isn't returned. The URL redirect feature is available from B2C Commerce version 24.3. Allowed values: `CATEGORY`, `PRODUCT`, `CONTENT_ASSET`. Minimum length: 1. Maximum length: 256. Example: `CATEGORY`. * `resourceSubType` (_string_) If the resourceType is CONTENT\_ASSET, this field tells you whether the resource is a standard content asset or a Page Designer content asset. This output is available from B2C Commerce version 24.2. Allowed values: `STANDARD_CONTENT_ASSET`, `PAGE_DESIGNER_CONTENT_ASSET`. Minimum length: 1. Maximum length: 256. Example: `STANDARD_CONTENT_ASSET`. * `resourceId` (_string_) The identifier for the resource that corresponds to the requested URL. If you set up a URL redirect in Business Manager, resourceId returns the corresponding destination ID value from the redirect. If there's a URI redirect, resourceId isn't returned. The URL redirect feature is available from B2C Commerce version 24.3. Minimum length: 1. Maximum length: 256. Example: `mens-clothing-shorts`. * `refinements` (_object_) The refinement filters that correspond to the URL and resourceType. Refinements are returned only if all of these conditions are met - a) the resourceType is CATEGORY, b) refinements are included in the urlSegment, and c) the refinements are configured in Business Manager. This field returns a key-value pair of refinement name and refinement value. If there’s a matching URL redirect for the requested URL. the refinements output isn’t returned. The URL redirect feature is available from B2C Commerce version 24.3. * `statusCode` (_integer (int32)_) This field is populated only if you set up a URL redirect in Business Manager. It specifies whether the redirect is temporary (302 or 307) or permanent (301). See [Create a Redirect from a B2C Commerce URL.](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_redirect_from_a_digital_url.htm&type=5) This parameter is available from B2C Commerce version 24.3. Example: `301`. * `destinationUrl` (_string_) This field is populated if the urlSegment resolves to a redirect. Specifies the URL you want to redirect to as an absolute or relative URL. The destinationUrl is based on your configuration in Business Manager. It's either a calculated value indicating the Commerce Cloud object (product, category, or content asset) URL or your specified URL. Note that an object's path may not necessarily match your headless storefront URLs but can be used as a reference for calculating the destinationUrl. See [Create a Redirect from a B2C Commerce URL.](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_redirect_from_a_digital_url.htm&type=5). Available from B2C Commerce 24.3. Minimum length: 1. Maximum length: 2048. Example: `mens/clothing/shorts`. * `copySourceParams` (_boolean_) This field is populated only if you set up a URL redirect in Business Manager. It’s a flag that shows whether the parameters of the source URL have been copied to the destination URL. This parameter is available from B2C Commerce version 24.3. Example: `true`. * `additionalUrlParams` (_string_) This field is populated only if you set up a URL redirect in Business Manager. It returns the parameters you want to add to the end of the URL. This parameter is available from B2C Commerce version 24.3. Minimum length: 1. Maximum length: 2048. Example: `&cgid=womens-accessories-scarves&prefn1=displaySize`. * `productCategoryId` (_string_) This field is populated only if you set up a URL redirect in Business Manager. It identifies the destination product's category ID. This field is returned only when the destination type is product. This parameter is available from B2C Commerce version 24.3. Minimum length: 1. Maximum length: 256. * `onlineFrom` (_string (date-time)_, nullable) The date and time from which the URL redirect is active. If null, the redirect has no start date constraint. This field is populated only if you set up a URL redirect in Business Manager. This parameter is available from B2C Commerce version 26.8. Example: `2025-06-01T00:00:00.000Z`. * `onlineTo` (_string (date-time)_, nullable) The date and time until which the URL redirect is active. If null, the redirect has no end date constraint. This field is populated only if you set up a URL redirect in Business Manager. This parameter is available from B2C Commerce version 26.8. Example: `2025-12-31T23:59:59.000Z`. ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### LanguageCountry A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'. Type: `string`. Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`. ### LanguageCode A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). Type: `string`. Pattern: ^\[a-z\]\[a-z\]$. Example: `en`. ### DefaultFallback A specialized value indicating the system default values for locales. Type: `string`. Default: `default`. Pattern: ^default$. Example: `default`.