---
schema_version: "1"
id: a827ab2ae8e159d2089a4ef9fe00e24177cf770796e842d350e5f9ee41630370
title: 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/seo.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/seo
source_site: developer.salesforce.com
content_type: documentation
content_hash: f4e8639a1aa97a6ee8fc0e5d739130f3c5a12892f4976861489ce094e2669a45
products:
  - B2C Commerce API
  - Salesforce APIs
---
SEO

# SEO

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/seo/seo-oas-v1-public.yaml)

## API Overview

This API uploads a custom sitemap and triggers the sitemap generation process.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the `Authorization` header of your API request.

You must include the relevant scope(s) in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html) guide.

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. 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)

### Related APIs

*   [Shopper SEO](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=Summary) — Resolve SEO-friendly URLs for shoppers.

**Version:** 1.0.12

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/site/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

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.seo.rw: Allows write operations on seo.
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### PUT Upload a custom sitemap and trigger sitemap generation process.

`PUT /organizations/{organizationId}/sitemap`

Operation ID: `uploadCustomSitemapAndTriggerSitemapGeneration`. Security: AmOAuth2 (sfcc.seo.rw).

This API uploads a custom sitemap and triggers the sitemap generation process.

#### 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
    ```
    
*   `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
    ```
    

#### Request body (required)

Media type: `multipart/form-data`. Schema: `SitemapRequest`.

_Example: sitemapRequestBody_

```
{
  "customSitemapFile": "sitemap.xml",
  "hostname": "secure.sitegenesis.com"
}
```

#### Responses

*   **202** The site generation process runs asynchronously and takes a few minutes to complete. The generated sitemap is available at the location specified in the location header.
    
    Headers:
    
    *   `Location` (Location) The generated sitemap location url
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: putSitemap400_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The custom sitemap must be an XML file."
    }
    ```
    
*   **404** The given hostname was not found in the alias file.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: putSitemap404_
    
    ```
    {
      "title": "The given hostname was not found in the alias file.",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors",
      "detail": "The hostname was not found in the alias file.",
      "hostname": "www.abc.com"
    }
    ```
    
*   **409** The requested action could not be completed because the job is currently running and its state is being updated.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: putSitemap409_
    
    ```
    {
      "title": "Sitemap Generation In Progress",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The previous generate sitemap request has not completed."
    }
    ```
    

## 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`.

### SitemapRequest

*   `customSitemapFile` (_string_, required) The custom sitemap file to be uploaded. Must conform to the [Sitemap Protocol](https://www.sitemaps.org/protocol.html), with a root `<urlset>` element and well-formed `<url>` entries.The filename must not start with `sitemap` nor contain forward or backward slashes. The file must contain valid xml content and the filename must have an .xml extension.  
    Maximum length: 4000. Example: `custom-sitemap.xml`.
*   `hostname` (_string_, required) The hostname for which the sitemap will be generated. The hostname must be listed in the aliases file in Business Manager  
    Minimum length: 1. Maximum length: 4000. Example: `www.abc.com`.

### Location

URL where the resource is located.

Type: `string`.

Maximum length: 2048. Example: `/index.html`.

### 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`.