# About the SEO Patterns API

The SEO Patterns API allows you to read and write a Wix site's SEO patterns: the templates that generate SEO tags for every item of a page type. A pattern is written once for a page type, such as every store product or every blog post, and its tags contain variables, such as `{{product.name}}`, that are filled in with each item's own values when its page renders. Changing one pattern therefore changes the tags of every page of that type that doesn't have SEO tags set for the item itself.

With the SEO Patterns API, you can:

- Retrieve the pattern in effect for a page type, along with the Wix default it started from.
- Retrieve the variables a page type offers, so you know what a pattern for it may reference.
- Create a pattern for a page type that's still on its Wix default.
- Change a pattern, or reset a page type back to its Wix default.
- Retrieve the patterns a site has stored.

## How patterns fit with a site's other SEO tags

Wix builds the tags a page renders with by combining several sources, where a later source takes precedence:

1. The site's tags, which apply to every page. See the [Site SEO Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/introduction).
1. The pattern Wix provides for the page type.
1. The pattern the Wix user customized for that page type, which this API manages.
1. The tags of the page that displays the item.
1. The tags set for the item itself. See the [Item SEO Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/introduction).

So a pattern decides an item's tags only where the item has none of its own. To see the tags a specific item is expected to render with, and which source each one came from, read `resolvedTags` on that item with the [Item SEO Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/introduction).

A pattern is stored where the live site reads it, so a change takes effect without a site publish.

## Concurrent changes

A pattern has no revision, and a Wix user editing SEO patterns in the dashboard writes to the same patterns as this API. If both change a pattern at once, whichever lands second overwrites the other, with no conflict error. When a Wix user may be editing at the same time, retrieve the pattern immediately before writing it.

## Patterns for a single dynamic page

Pages built from a Wix Data collection are the one case where a page type holds more than one pattern: each such page can have a pattern of its own. To address one of them, specify its ID in `pageId`, with a page type of `WIX_DATA_PAGE_ITEM`.

Every other page type has a single pattern for the whole type, and specifying a page ID for one of those fails rather than being ignored. `collectionName` isn't supported yet, so address a dynamic page by its ID instead.

## Page types

Send one of the known page type names. An unknown name fails with `UNSUPPORTED_PAGE_TYPE`. That error message lists every name the method accepts.

Send `STATIC_PAGE` for Editor pages, never `STATIC_PAGE_V2`. 

App pages added with a site page extension don't have their own page type. They use the `STATIC_PAGE` pattern, the same as Home or About.

A page type provided by a Wix business solution is only available when that business solution is installed on the site. Get, List SEO Pattern Variables, and Create fail with `PAGE_TYPE_NOT_ON_SITE` when it isn't.

These are the page types sites commonly customize:

| `pageType` | What it is |
|---|---|
| `STATIC_PAGE` | Pages created in the Editor, such as Home or About |
| `WIX_DATA_PAGE_ITEM` | A page built from a Wix Data collection. Specify `pageId` to address one page |
| `BLOG_POST` | Blog posts |
| `BLOG_CATEGORY` | Blog categories |
| `BLOG_TAGS` | Blog tags |
| `BLOG_ARCHIVE` | Blog archive pages |
| `STORES_PRODUCT` | Store products |
| `STORES_CATEGORY` | Store categories |
| `STORES_SUB_CATEGORY` | Store subcategories |
| `BOOKINGS_SERVICE` | Bookings services |
| `EVENTS_PAGE` | Event pages |
| `FORUM_POST` | Forum posts |
| `FORUM_CATEGORY` | Forum categories |
| `GROUPS_PAGE` | Group pages |
| `GROUPS_POST` | Group posts |
| `MEMBERS_AREA_PROFILE` | Member profiles |
| `MEMBERS_AREA_AUTHOR_PROFILE` | Author profiles in the members area |
| `PORTFOLIO_COLLECTIONS` | Portfolio collections |
| `PORTFOLIO_PROJECTS` | Portfolio projects |
| `PRICING_PLANS` | Pricing plans |
| `PRO_GALLERY_ITEM` | Pro Gallery items |
| `CHALLENGES_PAGE` | Online programs |
| `RESTAURANTS_MENU_PAGE` | Restaurant menus |
| `RESTAURANTS_MENU_ITEM` | Restaurant menu items |
| `TABLE_RESERVATIONS_EXPERIENCE` | Table reservation experiences |

The API also accepts names for some page components and platform pages, such as `SEARCH_PAGE` or `BREADCRUMBS_COMPONENT`. Those names appear in that error message. They aren't the page types a site customizes in SEO settings.

Page types aren't the same set as the item types of the [Item SEO Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/introduction). A page type can support a pattern without supporting tags set per item, and the other way round.

## Before you begin

It's important to note the following points before starting to code:

- **A page type always has a pattern in effect, and the Wix default is returned alongside it every time.** [Get SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/get-seo-pattern) returns `pattern`, the pattern in effect, together with `defaultPattern`, the Wix default for that page type. Both are present on every call, including for a page type the site has customized. `source` says which of the two is in effect: `PATTERN_SOURCE_USER` when the page type has a pattern of its own, `PATTERN_SOURCE_DEFAULT` when it doesn't. So to see what [Reset SEO Pattern To Default](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/reset-seo-pattern-to-default) would restore, read `defaultPattern`. There's no need to reset the pattern to find out.
- **Create and Set aren't interchangeable.** [Create SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/create-seo-pattern) works only on a page type that has no pattern of its own. [Set SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/set-seo-pattern) changes a pattern that already exists.
- **A pattern may reference only the variables its page type offers, and variable names differ by page type.** A store product offers `{{product.name}}`, for example, while a page built from a Wix Data collection offers `{{wix-data-page-item.main-collection-primary-field}}`. Call [List SEO Pattern Variables](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/list-seo-pattern-variables) for each page type rather than reusing a name.
- **Setting `pattern` replaces the page type's tag templates in full.** Retrieve the pattern first and send back the complete set you want it to have.
- For a page type provided by a Wix business solution, such as `BLOG_POST` or `STORES_PRODUCT`, **that business solution must be installed on the site.** Get SEO Pattern, List SEO Pattern Variables, and Create SEO Pattern fail when it isn't. Set SEO Pattern and Reset SEO Pattern To Default don't apply that check, so a pattern stored before a business solution was uninstalled stays readable and editable.

## Use cases

- [Apply a title convention to a whole page type](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/sample-flows#apply-a-title-convention-to-a-whole-page-type)
- [Audit which page types a site has customized](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/sample-flows#audit-which-page-types-a-site-has-customized)
- [Return a page type to the Wix default](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/sample-flows#return-a-page-type-to-the-wix-default)

## Terminology

- **Pattern:** A template of SEO tags defined for one page type, whose variables are filled in per item.
- **Page type:** A known name for a category of page that shares a pattern, such as `STORES_PRODUCT` or `BLOG_POST`. See [Page types](fallback::#page-types).
- **Variable:** A placeholder such as `{{product.name}}`, written in double braces, that's replaced with an item's own value when its page renders. Each page type offers its own set.
- **Wix default:** The pattern Wix supplies for a page type, which applies until a site defines one of its own.

@sdk_package_setup

# SEO Patterns API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Apply a title convention to a whole page type

A Wix user may want every product page to carry the site name after the product name, without setting a title on each product.

Because a page type may have a pattern already, and because Create and Set aren't interchangeable, this flow reads the pattern before deciding which one to call.

To apply a title convention to a page type:

1. Call [List SEO Pattern Variables](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/list-seo-pattern-variables) for the page type, and confirm that the variables you plan to use are offered. A pattern referencing anything else is rejected.
1. Call [Get SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/get-seo-pattern) for the page type and read `source`:
    - `PATTERN_SOURCE_DEFAULT` means the site has no pattern of its own. Build your tag list from `defaultPattern` and call [Create SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/create-seo-pattern).
    - `PATTERN_SOURCE_USER` means the site already has one. Build your tag list from `pattern` and call [Set SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/set-seo-pattern) with `pattern` in the `fieldMask`.
1. Add or replace the title template in that list. For example:

    ```json
    {
      "type": "title",
      "children": "{{product.name}} | {{site.name}}"
    }
    ```

1. Check the response: `source` is now `PATTERN_SOURCE_USER`, and the pattern you sent is returned in `pattern`.

The change reaches the live site without a site publish. It applies to every page of that type that doesn't have SEO tags set for the item itself, so a product with its own title keeps it. To find those products, read `hasOverride` with the [Item SEO Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/introduction).

## Audit which page types a site has customized

Before changing anything, it's useful to know which page types a Wix user has already customized, so an import doesn't overwrite deliberate choices.

To audit a site's patterns:

1. Call [List SEO Patterns](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/list-seo-patterns). The response isn't paged, so one call returns everything the site has stored.
1. For each entry, read `source`. `PATTERN_SOURCE_USER` means the page type is customized; `PATTERN_SOURCE_DEFAULT` means it was reset back to the Wix default and its `pattern` is empty.
1. Write only to the page types where `source` is `PATTERN_SOURCE_DEFAULT`, leaving customized page types untouched.

Note that this list isn't an inventory of the site's page types. A page type that has never had a pattern stored isn't returned at all, even though it does have a pattern in effect. To check one of those, call [Get SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/get-seo-pattern) for the page type.

## Return a page type to the Wix default

A convention that no longer suits a site can be removed, so the page type generates tags the way it did before.

To reset a page type:

1. Call [Get SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/get-seo-pattern) for the page type and keep `defaultPattern`, so you know what the pages will generate afterwards.
1. Call [Reset SEO Pattern To Default](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/reset-seo-pattern-to-default) for the page type.
1. Check the response: `pattern` is empty and `source` is `PATTERN_SOURCE_DEFAULT`.

The page type remains in the response of [List SEO Patterns](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/list-seo-patterns) after a reset, with the same empty pattern. To customize it again later, call [Create SEO Pattern](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/seo-pattern-v1/create-seo-pattern) rather than Set SEO Pattern, because the site no longer has a pattern of its own for it.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

Create Seo Pattern