> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/commerce/sitemap-configuration.md).

# Sitemap Configuration

Sitemaps are crucial for enhancing website accessibility and search engine optimization (SEO). They provide a structured overview of website content, ensuring that important pages are discoverable by both users and search engines. The sitemap configuration process allows precise control over which pages are indexed and how they appear, ensuring relevance and compliance with SEO best practices.

A sitemap is an XML file that defines the content structure of a website and provides information about its pages to search engines. Sitemaps are especially useful for large websites as they help search engine bots discover all pages efficiently, speeding up indexing.

**Purpose of Using a Sitemap:**

* **Search Engine Optimization (SEO):** Enables faster and more comprehensive crawling of content by search engines, improving SEO performance.
* **Simplifying Site Structure Discovery:** For large or complex websites where not all pages are interlinked or easily accessible, a sitemap aids search engines in discovering content.
* **Adding New Pages and Updates:** Informs search engines about newly added or updated pages, ensuring the site remains current.

## <mark style="color:red;">Sitemap File Structure</mark>

A sitemap is created in XML format and includes the following elements:

* `<loc>`: This element specifies the **URL** of a page or resource that is included in the sitemap. This is the most essential part of the sitemap as it directly informs the search engine about the exact location of the page.
* `<lastmod>`: This element indicates the **last modification date** of the page listed in the sitemap. It is used to tell search engines when the page was last updated or changed.
* `<changefreq>`: This element specifies how often the content on the page is expected to **change**. This helps search engines understand the **update frequency** of the page, and decide how often it should revisit the page to check for updates.
* `<priority>`: This element reflects the **importance** of a page relative to other pages on the site. It is used to guide search engines about how much importance they should assign to the page when deciding how frequently to crawl it.

For example:

<div align="left"><figure><img src="https://2911598027-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlQinVPnOffBiOp126ldR%2Fuploads%2Fgit-blob-687f4cb268e50ab3adc74ef0ec5682ca96beee7f%2Fimage.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

## <mark style="color:red;">Sitemap Configuration</mark>

This section delves into the sitemap configuration options, focusing on key page types, configuration parameters, filtering options, and advanced customization techniques. By leveraging these features, businesses can tailor their sitemaps to reflect their unique content strategy, prioritize high-value pages, and exclude irrelevant or outdated content.

{% hint style="warning" %}
Sitemaps are updated every 6 hours automatically.
{% endhint %}

<figure><img src="https://2911598027-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlQinVPnOffBiOp126ldR%2Fuploads%2Fgit-blob-3c4acaf2bf3a08dd6f9d9a0eba0105df6d7d9fa1%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

The sitemap configuration supports five primary page types, each serving a distinct purpose within the overall structure of the site. These page types ensure that key areas of the website are indexed and accessible to search engines and users.

**1. Landing Page:** Represents high-level entry points or home page links, often serving as gateways to other sections of the site.

* *Common Examples:*
  * Homepage (e.g., `https://example.com`)
  * Campaign landing pages (e.g., `https://example.com/summer-sale`)
* *Key Features:*
  * Typically prioritize user engagement and search visibility.
  * Can include promotional pages or pages designed to drive traffic to specific areas of the website.

**2. Category:** Represents category or collection pages, often used in e-commerce or content-heavy websites to group related items.

* *Common Example:*
  * Product categories (e.g., `https://example.com/electronics`)
* *Key Feature:*
  * Organizes content hierarchically, aiding navigation and SEO.

**3. Flat Page:** Static content pages that provide information not frequently updated.

* *Common Examples:*
  * About Us (e.g., `https://example.com/about`)
  * Terms of Service (e.g., `https://example.com/terms`)
* *Key Features:*
  * Focuses on presenting evergreen content.
  * Excludes pages requiring user authentication by default (e.g., registration-only content).

**4. Special Page:** Dedicated to unique or custom pages that don’t fit traditional content categories but are essential to the user experience or business goals.

* *Common Examples:*
  * Custom campaign pages with interactive content.
  * Microsites for specific promotions or events.
* *Key Features:*
  * Requires activation and a pretty URL to be included in the sitemap.
  * Often tailored for marketing purposes or specific user interactions.

**5. Product:** Showcases individual product pages, critical for e-commerce websites.

* *Common Examples:*
  * Product detail pages (e.g., `https://example.com/product/12345`)
  * Variations or configurations of products (e.g., `https://example.com/red-shirt`)
* *Key Features:*
  * Focuses on ensuring discoverability of active, listable products.
  * Includes stock visibility settings to determine whether out-of-stock items are listed.

Sitemap configuration is used to structure, filter, and activate or deactivate specific page types in the sitemap. Defined in **Dynamic Settings** as `SITEMAP_CONFIGURATION`, it is stored in JSON format.

<figure><img src="https://2911598027-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlQinVPnOffBiOp126ldR%2Fuploads%2Fgit-blob-1a52ad0528ea3b8dff94b1a8798d7ac658bf4491%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

This configuration allows only active content types to be reported to search engines. Configuration details for each page type are outlined in the **Pages** section.

### Configuration Parameters and Filtering Options

This section provides an overview of the configuration parameters for `SITEMAP_CONFIGURATION` dynamic setting and their filtering options available for sitemap objects. These parameters define the behavior, structure, and content of sitemaps, enabling precise control over what gets included or excluded.

***Configuration Parameters for Dynamic Setting:***

| Key                          | Description                                                                                                                                                                                                                                                                              | Type          |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `excludes`                   | Specifies conditions used to filter out items that should not appear in the sitemap. It takes a dictionary format where the key-value pairs define the criteria for exclusion.                                                                                                           | Dict          |
| `filters`                    | Specifies conditions to include items in the sitemap. Uses a dictionary format where the keys are field names and the values define the conditions for inclusion.                                                                                                                        | Dict          |
| `should_generate`            | Controls whether a specific item should be generated and included in the sitemap file. When **true**: the item is generated and included. When **false**: the item is excluded.                                                                                                          | Boolean       |
| `enabled`                    | Determines whether an item is actively included in the sitemap. When **true**: the item is included. When **false**: the item is excluded.                                                                                                                                               | Boolean       |
| `priority`                   | Indicates the importance level of a page relative to others in the sitemap, helping search engines understand which pages are most important.                                                                                                                                            | Float         |
| `limit`                      | Specifies the maximum number of items (URLs) to include in the sitemap. (min: 1, max: 50,000).                                                                                                                                                                                           | Integer       |
| `template`                   | Defines the template used when generating the sitemap. Defaults to `sitemap.xml`.                                                                                                                                                                                                        | String        |
| `i18n`                       | Indicates whether the item supports multiple languages. If `true`, the sitemap includes links to pages in various languages. If `false`, only the default language versions are included.                                                                                                | Boolean       |
| `changefreq`                 | Specifies how often the content of a page is expected to change. Possible values: `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`.                                                                                                                                   | Choice String |
| `include_stock_out_products` | Applies only to Product sitemaps. Controls whether out-of-stock products are included. If `true`, out-of-stock products are included. If `false`, only in-stock products appear.                                                                                                         | Boolean       |
| `max_image_count`            | Applies only to Product sitemaps using `sitemap_with_images.xml`. Specifies the maximum number of images to include per product. Defaults to `1`.                                                                                                                                        | Integer       |
| `include_seller_id_param`    | Applies only to Product sitemaps. When `true`, each product URL includes a `?seller_id=` query parameter pointing to the cheapest active seller (offer product) for that product. If no active offer exists for a product, the URL is listed without the parameter. Defaults to `false`. | Boolean       |

Filters define criteria for inclusion or exclusion in the sitemap. These filters are used for the "`excludes`" and "`filters`" parameters in the above Configuration Parameters.

Both the "`excludes`" and "`filters`" fields accept data in JSON format, as shown below. The key should follow the pattern `"{field}__{filter_key}"`, and the value should contain the expected value.

***Filtering Options:***

<table><thead><tr><th width="148.4140625">Filter</th><th>Description</th></tr></thead><tbody><tr><td><code>exact</code></td><td>Filters for an exact match of the value. The value must match exactly with the field’s content. e.g., "field_name__exact": "value" (Matches records where the field is exactly "value")</td></tr><tr><td><code>iexact</code></td><td>Filters for an exact match, but case-insensitive. e.g., "field_name__iexact": "value" (Matches records where the field is "value", "VALUE", "VaLuE", etc.)</td></tr><tr><td><code>contains</code></td><td>Filters for records where the field contains a specific substring. e.g., "field_name__contains": "value" (Matches "value", "some value", "the value is here", etc.)</td></tr><tr><td><code>icontains</code></td><td>Filters for records where the field contains a specific substring, case-insensitive. e.g., "field_name__icontains": "value" (Matches "value", "VALUE", "Some VALUE here", etc.)</td></tr><tr><td><code>gt/lt</code></td><td>Filters for values greater than / less than the specified value. e.g., "field_name__gt": 10 (Matches records where the field is greater than "10")</td></tr><tr><td><code>gte/lte</code></td><td>Filters for values greater than or equal / less than or equal to the specified value. e.g., "field_name__gte": 10 (Matches records where the field is greater than or equal to "10")</td></tr><tr><td><code>in</code></td><td>Filters for values that are contained within a given list of values. e.g., "field_name__in": [value1, value2, value3] (Matches records where the field is "value1", "value2", or "value3")</td></tr><tr><td><code>isnull</code></td><td>Filters for fields that are either null or not null. e.g., "field_name__isnull": true (Matches records where the field is null)</td></tr><tr><td><code>startswith</code></td><td>Filters for records where the field starts with a specified substring. e.g., "field_name__startswith": "value" (Matches records where the field starts with "value", e.g., "value123", "valueabc", etc.)</td></tr><tr><td><code>istartswith</code></td><td>Filters for records where the field starts with a specified substring, case-insensitive. e.g., "field_name__istartswith": "value" (Matches "value", "VALUEabc", "VaLuE123", etc.)</td></tr><tr><td><code>endswith</code></td><td>Filters for records where the field ends with a specified substring. e.g., "field_name__endswith": "value" (Matches records where the field ends with "value", e.g., "endvalue", "testvalue")</td></tr><tr><td><code>iendswith</code></td><td>Filters for records where the field ends with a specified substring, case-insensitive. e.g., "field_name__iendswith": "value" (Matches "value", "VALUE", "endVALUE", etc.)</td></tr></tbody></table>

These filters can be combined to create complex queries tailored to specific requirements and pages. Below are some examples: (The use of filters along with fields specific to each page is provided in the [Pages](https://github.com/akinon/docs/tree/main/technicalguides/commerce/broken-reference/README.md) section.)

***Excluding Specific Pages:***

Exclude pages with a "draft" (exact) status and URLs starting with "help."

```javascript
{
  "excludes": {
    "status__exact": "draft",
    "url__startswith": "help"
  }
}
```

* Expected Outcome:
  * All pages with a "draft" status are excluded.
  * Pages with URLs starting with "help" are not included in the sitemap.

***Including Specific Pages:***

To filter records where the `title` field contains “page” (case-insensitive) and the `url` field contains “test” (case-insensitive):

```javascript
{
  "filters": {
  "title__icontains": "page",
  "url__icontains": "test"
  }
}
```

* Expected Outcome:
  * The query will return all records where:
    * The `title` field contains "page" (e.g., "landing page", "home PAGe").
    * The `url` field contains "test" (e.g., "<https://example.com/test-page>", "<https://example.com/page/TEST>").

### Configurations via Project Settings

This section details the configuration options defined in the related environment.

**STATICSITEMAPS\_ROOT\_DIR**\
Defines the directory where sitemap files are stored. This setting specifies the root directory for sitemap files, such as `'sitemaps/'`. While it can be updated via environment variables (ENV), rebuilding the project is required for changes to take effect.

**STATICSITEMAPS\_URL**\
Sets the base URL path for accessing the sitemap. Defaults to:\
<https://s3.eu-central-1.amazonaws.com/{ST\\_S3\\_BUCKET\\_NAME}/sitemaps/sitemaps/.\\>
If the files are stored locally, this URL must be updated accordingly. While it can be updated via environment variables (ENV), rebuilding the project is required for changes to take effect.

{% hint style="danger" %}
To store sitemaps under the domain specified in the `STATICSITEMAPS_URL` in the `.env` file, ensure that both the Shop URL and the subsequent path are correctly entered. For example, the URL could look like <https://www.yourshopdomain.com/sitemaps/> or [https://www.yourshopdomain.com/sitemap/](https://www.yourshopdomain.com/sitemaps/).

The `STATICSITEMAPS_URL` should include the full URL path where the sitemaps will be stored, and this may vary depending on the user's preferences or system setup. It's important that the URL and path match the expected structure for proper sitemap generation.

After updating the `.env` file with the correct Shop URL and path, rebuild the project for the changes to take effect and ensure that the sitemaps are stored in the correct location.
{% endhint %}

### Custom Sitemap Template

To create a custom template for sitemaps (e.g., including an image field for a product page), follow these steps:

**1.** Add sitemap template prefix to `DB_TEMPLATES_PREFIXES` in Dynamic Settings.

<figure><img src="https://2911598027-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlQinVPnOffBiOp126ldR%2Fuploads%2Fgit-blob-130e439ea18702ec1ef1804a06f959d1b31a8b98%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**2.** Create a new template via **Sales Channels>Content Management>Mailing Templates**, filling out fields appropriately. When the "Name" parameter is selected as the "Other", a field will appear allowing manual entry of the name. Here, you should enter the name of the XML file that starts with the sitemap template prefix added in step 1 under dynamic settings (Format: `{sitemap_template_prefix}/{template_name.xml}`). This name is important as it will be used in step

<div align="left"><figure><img src="https://2911598027-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlQinVPnOffBiOp126ldR%2Fuploads%2Fgit-blob-191dbe6405c1402cc91502198ca3f193e5596af3%2Fimage.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

**3.** Use a custom XML structure for **Content** field such as:

```xml
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n
<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\" xmlns:image=\"http://www.google.com/schemas/sitemap-image/1.1\">\n{%- for url in urlset -%}
    <url>
        <loc>{{ url.location }}</loc>{% if url.lastmod %}
        <lastmod>{{ url.lastmod.strftime('%Y-%m-%d') }}</lastmod>{% endif %}
        {% if url.changefreq %}<changefreq>{{ url.changefreq }}</changefreq>{% endif %}
        {% if url.priority %}<priority>{{ url.priority }}</priority>{% endif %} 
        {% for image in url.item.product.productimage_set.all() %}
        <image:image>
            <image:loc>{{ image.image.url }}</image:loc>
            <image:title>{{ (url.item.product.name.replace('ı','i')|slugify).split('-')|join(' ')|title }}</image:title>
        </image:image>{% endfor %}
    </url>
{%- endfor -%}\n
</urlset>
```

**4.** Update the `template` parameter in `SITEMAP_CONFIGURATION` with the name to the custom template (`{sitemap_template_prefix}/{template_name.xml}`) defined in step 2.

```json
{
    "excludes": {},
    "filters": {},
    "should_generate": true,
    "enabled": true,
    "priority": 0.5,
    "limit": 50000,
    "template": "sitemap/custom_product_sitemap.xml",
    "i18n": false,
    "include_stock_out_products": true,
    "changefreq": "daily"
}
```

### Manually Triggering the Sitemap

When an update is made and saved in the `SITEMAP_CONFIGURATION` form within Dynamic Settings, the sitemap is automatically updated.

### Accessing the Sitemap

If the sitemap has been generated, it can be accessed by `{commerce\_url/storefront\_url}/sitemap.xml`.

If you have multi-language support, your storefront URL may change depending on the language of the site. The storefront URL is linked to the URL path of the site in the specific language. For example, if your website supports both English and Spanish, the URLs for the sitemaps could look like:

* For English: `{commerce_url}/en/sitemap.xml`
* For Spanish: `{commerce_url}/es/sitemap.xml`

## <mark style="color:red;">Pages</mark> <a href="#pages" id="pages"></a>

This section outlines the filtering and configuration options for various pages included in a sitemap. Each page type —**Landing Page**, **Category**, **Flat Page**, **Special Page**, and **Product**— has specific criteria, default settings, and fields available for filtering.

### 1. Landing Page

During the filtering process for Landing Pages:

* **filters**: Landing Pages are included based on specified criteria.
* **excludes**: Landing Pages are excluded based on specified criteria.

***Default Settings:***

<table><thead><tr><th width="168.23828125">Key</th><th width="168.16796875">Default Value</th><th>Type</th></tr></thead><tbody><tr><td>excludes</td><td>{}</td><td>Dict</td></tr><tr><td>filters</td><td>{}</td><td>Dict</td></tr><tr><td>should_generate</td><td>true</td><td>Boolean</td></tr><tr><td>enabled</td><td>false</td><td>Boolean</td></tr><tr><td>priority</td><td>0.5</td><td>Float</td></tr><tr><td>limit</td><td>50000</td><td>Integer (Min:1, Max:50000)</td></tr><tr><td>template</td><td>sitemap.xml</td><td>String</td></tr><tr><td>i18n</td><td>false</td><td>Boolean</td></tr><tr><td>changefreq</td><td>daily</td><td>Choice String ['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']</td></tr></tbody></table>

***Fields:***

The following fields can be used for filtering:

* id
* created\_date
* modified\_date
* name
* url
* template
* is\_active

#### Example Configuration

```json
{
  "excludes": {
    "template__icontains": "test",
    "name__icontains": "temporary",
  },
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.5,
  "limit": 50000,
  "filters": {
    "is_active": true,
    "url__startswith": "/landing/",
  },
  "i18n": false,
  "changefreq": "daily"
}
```

`excludes` Field:

* `template__icontains: "test"`\
  Excludes landing pages using templates containing "test" in their names, as they are likely for staging or experimentation.
* `name__icontains: "temporary"`\
  Excludes landing pages with "temporary" in their names, as these are usually not relevant for long-term indexing.

`filters` Field:

* `is_active: true`\
  Includes only active landing pages to ensure they are relevant for users and search engines.
* `url__startswith: "/landing/"`\
  Includes landing pages where the URL begins with "/landing/", indicating that they are categorized as landing pages.

### 2. Category

During the filtering process for Categories:

* **filters**: Category Pages are included based on specified criteria.
* **excludes**: Category Pages are excluded based on specified criteria.

{% hint style="warning" %}
If `depth` is not defined in `excludes`, Categories with `depth=1` are excluded by default. *(*`depth` *refers to the level of hierarchy in a category tree, indicating how many layers or levels deep a category is within the structure.)*
{% endhint %}

***Default Settings:***

<table><thead><tr><th width="170.87109375">Key</th><th width="132.8203125">Default Value</th><th>Type</th></tr></thead><tbody><tr><td>excludes</td><td>{}</td><td>Dict</td></tr><tr><td>filters</td><td>{}</td><td>Dict</td></tr><tr><td>should_generate</td><td>true</td><td>Boolean</td></tr><tr><td>enabled</td><td>true</td><td>Boolean</td></tr><tr><td>priority</td><td>0.5</td><td>Float</td></tr><tr><td>limit</td><td>50000</td><td>Integer (Min:1,Max:50000)</td></tr><tr><td>template</td><td>sitemap.xml</td><td>String</td></tr><tr><td>i18n</td><td>false</td><td>Boolean</td></tr><tr><td>changefreq</td><td>daily</td><td>Choice String ['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']</td></tr></tbody></table>

{% hint style="warning" %}
The default value of `i18n` is taken from the `PRETTY_URL_MULTI_LANGUAGE` setting in the `ENV` file and is set to "False". This setting manages multilingual URL structures.
{% endhint %}

***Fields:***

The following fields can be used for filtering:

* id
* created\_date
* modified\_date
* uuid
* path
* depth
* numchild
* order
* name

#### Example Configuration

```json
{
  "excludes": {
    "name__icontains": "test",
  },
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.5,
  "limit": 50000,
  "filters": {
    "depth__lte": 3,
    "name__icontains": "sale",
  },
  "i18n": false,
  "changefreq": "weekly"
}
```

`excludes` Field:

* `name__icontains: "test"`\
  Excludes categories with "test" in their name (case-insensitive).

`filters` Field:

* `depth__lte: 3`\
  Includes only categories up to level 3 in the hierarchy.
* `name__icontains: "sale"`\
  Includes categories with "sale" in their name (case-insensitive).

### 3. Flat Page

To list Flat Pages, the following condition must be met:

* `registration_required=False` (Authentication): The `registration_required` attribute of the Flat Page must be set to `false`.

During the filtering process for Flat Pages:

* **filters**: Flat Pages are included based on specified criteria.
* **excludes**: Flat Pages are excluded based on specified criteria.

***Default Settings:***

<table><thead><tr><th width="176.0703125">Key</th><th width="155.04296875">Default Value</th><th>Type</th></tr></thead><tbody><tr><td>excludes</td><td>{}</td><td>Dict</td></tr><tr><td>filters</td><td>{}</td><td>Dict</td></tr><tr><td>should_generate</td><td>true</td><td>Boolean</td></tr><tr><td>enabled</td><td>true</td><td>Boolean</td></tr><tr><td>priority</td><td>0.5</td><td>Float</td></tr><tr><td>limit</td><td>50000</td><td>Integer (Min:1,Max:50000)</td></tr><tr><td>template</td><td>sitemap.xml</td><td>String</td></tr><tr><td>i18n</td><td>false</td><td>Boolean</td></tr><tr><td>changefreq</td><td>daily</td><td>Choice String ['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']</td></tr></tbody></table>

{% hint style="warning" %}
The default value of `i18n` is taken from the `PRETTY_URL_MULTI_LANGUAGE` setting in the `ENV` file and is set to "False". This setting manages multilingual URL structures.
{% endhint %}

***Fields:***

The following fields can be used for filtering:

* id
* url
* title
* content
* enable\_comments
* template\_name
* registration\_required

#### Example Configuration

```json
{
  "excludes": {
    "template_name__contains": "test",
    "content__exact": "draft"
  },
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.6,
  "limit": 10000,
  "filters": {
    "enable_comments": false,
    "registration_required": false,
    "url__startswith": "/public/",
    "title__icontains": "guide"
  },
  "i18n": false,
  "changefreq": "monthly"
}
```

`excludes` Field:

* `template_name__icontains: "test"`\
  Excludes pages using templates with "test" in their name (case-sensitive).
* `content__icontains: "draft"`\
  Excludes pages where the content is matched "draft" exactly.

`filters` Field:

* `enable_comments: false`\
  Includes pages where comments are disabled to focus on static, indexable content.
* `registration_required: false`\
  Includes only pages that do not require registration to ensure public accessibility.
* `url__startswith: "/public/"`\
  Includes pages where the URL starts with "/public/", indicating public-facing pages.
* `title__icontains: "guide"`\
  Includes pages with "guide" in their title.

### 4. Special Page

To list Special Pages, the following conditions must be met:

* The Special Page must be active.
* The Special Page must have a pretty URL.

During the filtering process for Special Pages:

* **filters**: Special Pages are included based on specified criteria.
* **excludes**: Special Pages are excluded based on specified criteria.

***Default Settings:***

<table><thead><tr><th width="188.96875">Key</th><th width="194.83203125">Default Value</th><th>Type</th></tr></thead><tbody><tr><td>excludes</td><td>{}</td><td>Dict</td></tr><tr><td>filters</td><td>{}</td><td>Dict</td></tr><tr><td>should_generate</td><td>true</td><td>Boolean</td></tr><tr><td>enabled</td><td>false</td><td>Boolean</td></tr><tr><td>priority</td><td>0.9</td><td>Float</td></tr><tr><td>limit</td><td>50000</td><td>Integer (Min:1,Max:50000)</td></tr><tr><td>template</td><td>sitemap.xml</td><td>String</td></tr><tr><td>i18n</td><td>false</td><td>Boolean</td></tr><tr><td>changefreq</td><td>daily</td><td>Choice String ['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']</td></tr></tbody></table>

***Fields:***

The following fields can be used for filtering:

* id
* created\_date
* modified\_date
* name
* url
* template
* banner
* banner\_mobile
* banner\_url
* banner\_description
* is\_active
* extraction\_strategy
* video\_embedded\_code

#### Example Configuration

```json
{
  "excludes": {
    "name__icontains": "test",
    "banner__isnull": true
  },
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.8,
  "limit": 1000,
  "filters": {},
  "i18n": true,
  "changefreq": "weekly"
}
```

`excludes` Field:

* `name__icontains: "test"`\
  Excludes pages with "test" in the name, often used for staging or testing purposes.
* `banner__isnull: true`\
  Excludes pages without a banner, as banners are a critical design element for special pages.

### 5. Product

When listing products, if the `is_hidden` attribute exists, only products where `is_hidden` is `None` or `false` are considered.

To list products, the following conditions must also be met:

* `is_active=True`: The product must be active.
* `is_listable=True`: The product must be listable.
* Stock transactions must have been performed within the last 30 days.

During the filtering process for products:

* **filters**: Product Pages are included based on specified criteria.
* **excludes**: Product Pages are excluded based on specified criteria.

***Default Settings:***

| Key                          | Default Value | Type                                                                                 |
| ---------------------------- | ------------- | ------------------------------------------------------------------------------------ |
| `excludes`                   | `{}`          | Dict                                                                                 |
| `filters`                    | `{}`          | Dict                                                                                 |
| `should_generate`            | `true`        | Boolean                                                                              |
| `enabled`                    | `false`       | Boolean                                                                              |
| `priority`                   | `0.5`         | Float                                                                                |
| `limit`                      | `50000`       | Integer (Min: 1, Max: 50000)                                                         |
| `template`                   | `sitemap.xml` | String                                                                               |
| `i18n`                       | `false`       | Boolean                                                                              |
| `include_stock_out_products` | `true`        | Boolean                                                                              |
| `include_seller_id_param`    | `false`       | Boolean                                                                              |
| `changefreq`                 | `daily`       | Choice String \[`always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`] |

{% hint style="warning" %}
The default value of `i18n` is taken from the `PRETTY_URL_MULTI_LANGUAGE` setting in the `ENV` file and is set to "False". This setting manages multilingual URL structures.
{% endhint %}

{% hint style="warning" %}
The default value of `include_stock_out_products` is taken from the `INCLUDE_STOCK_OUT_PRODUCTS_ON_SITEMAP` setting in the `ENV` file and is set to "True". This setting determines whether out-of-stock products are included in the sitemap.
{% endhint %}

***Fields:***

The following fields can be used for filtering. Product-related fields must be prefixed with `product__`:

* `product__name`
* `product__base_code`
* `product__sku`
* `product__listing_code`
* `product__is_seller_product`
* `product__is_form_required`
* `product__productstock__stock`
* `product__productprice__price`
* `product__attributes__{ATTRIBUTE_NAME}`

{% hint style="warning" %}
**Using `excludes` with `product__attributes`**

When using `excludes` with a `product__attributes__<key>` lookup, the specified attribute key must be defined on **all** products. Products that do not have the key in their attributes are also excluded from the sitemap.
{% endhint %}

#### Example Configurations

**Example 1: Exclude seller-managed products**

```json
{
  "excludes": {
    "product__is_seller_product": true
  },
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.7,
  "limit": 50000,
  "filters": {},
  "i18n": false,
  "include_stock_out_products": true,
  "changefreq": "daily"
}
```

* `product__is_seller_product: true` — Excludes products exclusively managed by sellers.

**Example 2: Only in-stock products with a specific base code prefix**

```json
{
  "excludes": {},
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.7,
  "limit": 50000,
  "filters": {
    "product__base_code__startswith": "PRD-",
    "product__productstock__stock__gte": 5
  },
  "i18n": false,
  "include_stock_out_products": false,
  "changefreq": "daily"
}
```

* `product__base_code__startswith: "PRD-"` — Includes only products whose base code starts with "PRD-".
* `product__productstock__stock__gte: 5` — Includes only products with at least 5 units in stock.
* `include_stock_out_products: false` — Out-of-stock products are excluded from the sitemap.

**Example 3: Filter by SKU prefix**

```json
{
  "excludes": {},
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.7,
  "limit": 50000,
  "filters": {
    "product__sku__startswith": "SKU-"
  },
  "i18n": false,
  "include_stock_out_products": true,
  "changefreq": "daily"
}
```

* `product__sku__startswith: "SKU-"` — Includes only products whose SKU starts with "SKU-".

**Example 4: Filter by minimum price**

```json
{
  "excludes": {},
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.7,
  "limit": 50000,
  "filters": {
    "product__productprice__price__gte": 10
  },
  "i18n": false,
  "include_stock_out_products": true,
  "changefreq": "daily"
}
```

* `product__productprice__price__gte: 10` — Includes only products with a price of 10 or above.

### 6. Product Sitemap with Images

The product sitemap supports an image sitemap template (`sitemap_with_images.xml`) that includes product images alongside URL entries. This is useful for improving product discoverability through Google Image Search.

To enable it, set the `template` parameter to `sitemap_with_images.xml` in the product sitemap configuration.

{% hint style="warning" %}
When using `sitemap_with_images.xml`, the `limit` parameter must be set to **20000 or below** to prevent the sitemap file from exceeding the allowed file size limit.
{% endhint %}

***Additional Parameters:***

<table><thead><tr><th width="200">Key</th><th width="400">Description</th><th>Type</th></tr></thead><tbody><tr><td><code>max_image_count</code></td><td>Specifies the maximum number of images to include per product. Defaults to 1.</td><td>Integer</td></tr></tbody></table>

#### Example Configuration

```json
{
  "excludes": {},
  "template": "sitemap_with_images.xml",
  "enabled": true,
  "priority": 0.7,
  "limit": 20000,
  "filters": {},
  "i18n": false,
  "include_stock_out_products": true,
  "max_image_count": 3,
  "changefreq": "daily"
}
```

* `template: "sitemap_with_images.xml"` — Enables the image sitemap template.
* `max_image_count: 3` — Includes up to 3 images per product.

#### Example Output

```xml
<url>
  <loc>https://www.example.com/product-name/</loc>
  <lastmod>2026-07-06</lastmod>
  <changefreq>daily</changefreq>
  <priority>0.5</priority>
  <image:image>
    <image:loc>https://cdn.example.com/products/image-1.jpg</image:loc>
  </image:image>
  <image:image>
    <image:loc>https://cdn.example.com/products/image-2.jpg</image:loc>
  </image:image>
  <image:image>
    <image:loc>https://cdn.example.com/products/image-3.jpg</image:loc>
  </image:image>
</url>
```

### 7. Product Sitemap with Seller ID

For marketplaces where product URLs include a seller identifier, the sitemap can be configured to append a `?seller_id=` query parameter to each product URL. When enabled, the cheapest active seller (offer product) for each listable product is selected and its ID is appended to the URL. If no active offer exists for a product, its URL is listed without the parameter.

{% hint style="info" %}
This feature is intended for sites where product pages are seller-aware — i.e., the URL `https://example.com/product-slug/?seller_id=5` resolves to a valid, indexable page showing that seller's offer.
{% endhint %}

***Additional Parameter:***

| Key                       | Description                                                                                                                  | Type    |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------- |
| `include_seller_id_param` | When `true`, appends `?seller_id=<id>` to each product URL using the cheapest active offer's seller ID. Defaults to `false`. | Boolean |

#### Example Configuration

```json
{
  "excludes": {},
  "template": "sitemap.xml",
  "enabled": true,
  "priority": 0.7,
  "limit": 50000,
  "filters": {},
  "i18n": false,
  "include_stock_out_products": true,
  "include_seller_id_param": true,
  "changefreq": "daily"
}
```

#### Example Output

```xml
<url>
  <loc>https://www.example.com/red-polo-shirt/?seller_id=42</loc>
  <lastmod>2026-07-06</lastmod>
  <changefreq>daily</changefreq>
  <priority>0.7</priority>
</url>
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.akinon.com/technical-guides/commerce/sitemap-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.