List-page SEO

Read, update, translate, and subscribe to SEO metadata for the Brands, Vendors, Categories, and Collections list pages.

Manage SEO metadata for the pages listing brands, vendors, categories, or collections. These settings are separate from an individual resource's SEO. Address each list by page_type: brand_list, vendor_list, category_list, or collection_list.

Reads require read_products; writes require write_products. Translation calls also require the matching translation scope. Assigning a non-empty social image requires read_site_assets.

Updates preserve omitted fields. Empty text clears a field; social_image_id: null clears the image. Remove a field's translations before clearing its source text. Source edits mark translations as outdated but keep serving them until replaced or removed. Missing translations use the source value. List URLs follow the store's permalink settings. See List-page SEO translations for single-page and batch operations.

Endpoints#

Get list-page SEO

GET read_products

Get source SEO for a catalog list page.

pageType is the stable public identity. Tringify resolves the store-scoped row and never exposes its numeric database id.

Path parameters

Name	Type	Description
`pageType` required	`string`	Catalog list page. Example: `brand_list`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 PAGE_SEO_PAGE_TYPE_INVALID
pageType must be brand_list, vendor_list, category_list, or collection_list.
400 PAGE_SEO_META_TITLE_INVALID_CHARS
A title contains unsupported control characters.
400 PAGE_SEO_META_TITLE_TOO_LONG
A title exceeds the configured maximum.
400 PAGE_SEO_META_DESCRIPTION_INVALID_CHARS
A description contains unsupported control characters.
400 PAGE_SEO_META_DESCRIPTION_TOO_LONG
A description exceeds the configured maximum.
409 TRANSLATION_SOURCE_FIELD_HAS_TRANSLATIONS
Remove the field's translations before clearing its source value.
400 INVALID_INPUT
The social image id is malformed, not an image, outside this store, or not a site asset.

curl 'https://api-store.tringify.com/api/2025-01/list-page-seo/brand_list' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/list-page-seo/brand_list", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/list-page-seo/brand_list",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"page_seo":{"page_type":"brand_list","store_id":"74e634ea-84ec-43b8-b66b-986214c2c5a3","storefront_id":null,"seo_title":"Shop all brands","seo_title_is_default":false,"seo_title_default":"Brands – Acme","seo_description":"Explore every brand available in our store.","seo_description_is_default":false,"seo_description_default":"Browse all brands at Acme.","social_title":"Shop all brands","social_title_is_default":true,"social_title_default":"Shop all brands","social_description":"Explore every brand available in our store.","social_description_is_default":true,"social_description_default":"Explore every brand available in our store.","social_image_id":null,"social_image_is_default":true,"social_image_default_id":null,"robots_index":true,"robots_index_is_default":true,"robots_index_default":true,"robots_follow":true,"robots_follow_is_default":true,"robots_follow_default":true}}}

Update list-page SEO

PUT write_products; read_site_assets only when assigning social_image_id

Update source SEO for a catalog list page.

This is a patch: omitted fields remain unchanged and an empty string clears a text field. To return a field to its generated default, send null for it or set its *_is_default flag to true; the flag wins over a value sent with it. The GET response carries the same flags, so sending it back unchanged keeps generated defaults generated instead of saving their current text. A source field with stored translations cannot be cleared until those translations are removed. Changing source text marks that field's translations outdated. Setting a non-empty social_image_id additionally requires read_site_assets and an image from this store's site-asset namespace.

Path parameters

Name	Type	Description
`pageType` required	`string`	Catalog list page. Example: `brand_list`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`seo_title`	`string\|null`	Search-result title. Empty or null returns it to the generated default. Example: `Shop all brands`
`seo_title_is_default`	`boolean`	`true` returns the search-result title to the generated default. Example: `false`
`seo_description`	`string\|null`	Search-result description. Empty or null returns it to the generated default. Example: `Explore every brand available in our store.`
`seo_description_is_default`	`boolean`	`true` returns the search-result description to the generated default. Example: `false`
`social_title`	`string\|null`	Social-share title. Empty or null returns it to the generated default. Example: `Our brands`
`social_title_is_default`	`boolean`	`true` returns the social-share title to the generated default. Example: `false`
`social_description`	`string\|null`	Social-share description. Empty or null returns it to the generated default. Example: `Discover the brands we carry.`
`social_description_is_default`	`boolean`	`true` returns the social-share description to the generated default. Example: `false`
`social_image_id`	`string\|null`	Site-asset image UUID. Empty string or null returns it to the default share image. Example: `8f2a1c2b-9d4e-4a56-b789-0123456789ab`
`social_image_is_default`	`boolean`	`true` returns the social image to the default share image. Example: `false`
`robots_index`	`boolean\|null`	Whether search engines may index the page. Null returns it to the default, which is `false` while the page lists nothing. Example: `true`
`robots_index_is_default`	`boolean`	`true` returns indexing to the default. Example: `false`
`robots_follow`	`boolean\|null`	Whether search engines may follow links on the page. Null returns it to the default. Example: `true`
`robots_follow_is_default`	`boolean`	`true` returns link following to the default. Example: `false`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 PAGE_SEO_PAGE_TYPE_INVALID
pageType must be brand_list, vendor_list, category_list, or collection_list.
400 PAGE_SEO_META_TITLE_INVALID_CHARS
A title contains unsupported control characters.
400 PAGE_SEO_META_TITLE_TOO_LONG
A title exceeds the configured maximum.
400 PAGE_SEO_META_DESCRIPTION_INVALID_CHARS
A description contains unsupported control characters.
400 PAGE_SEO_META_DESCRIPTION_TOO_LONG
A description exceeds the configured maximum.
409 TRANSLATION_SOURCE_FIELD_HAS_TRANSLATIONS
Remove the field's translations before clearing its source value.
400 INVALID_INPUT
The social image id is malformed, not an image, outside this store, or not a site asset.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/list-page-seo/brand_list' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "robots_follow": true,
  "robots_follow_is_default": false,
  "robots_index": true,
  "robots_index_is_default": false,
  "seo_description": "Explore every brand available in our store.",
  "seo_description_is_default": false,
  "seo_title": "Shop all brands",
  "seo_title_is_default": false,
  "social_description": "Discover the brands we carry.",
  "social_description_is_default": false,
  "social_image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
  "social_image_is_default": false,
  "social_title": "Our brands",
  "social_title_is_default": false
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/list-page-seo/brand_list", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "robots_follow": true,
    "robots_follow_is_default": false,
    "robots_index": true,
    "robots_index_is_default": false,
    "seo_description": "Explore every brand available in our store.",
    "seo_description_is_default": false,
    "seo_title": "Shop all brands",
    "seo_title_is_default": false,
    "social_description": "Discover the brands we carry.",
    "social_description_is_default": false,
    "social_image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "social_image_is_default": false,
    "social_title": "Our brands",
    "social_title_is_default": false
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/list-page-seo/brand_list",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "robots_follow": True,
        "robots_follow_is_default": False,
        "robots_index": True,
        "robots_index_is_default": False,
        "seo_description": "Explore every brand available in our store.",
        "seo_description_is_default": False,
        "seo_title": "Shop all brands",
        "seo_title_is_default": False,
        "social_description": "Discover the brands we carry.",
        "social_description_is_default": False,
        "social_image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
        "social_image_is_default": False,
        "social_title": "Our brands",
        "social_title_is_default": False,
    },
)
data = res.json()

Response

200

Sample response

{"code":"PAGE_SEO_UPDATED","data":{"page_seo":{"page_type":"brand_list","robots_follow":true,"robots_follow_default":true,"robots_follow_is_default":true,"robots_index":true,"robots_index_default":true,"robots_index_is_default":true,"seo_description":"Explore every brand available in our store.","seo_description_default":"Browse all brands at Acme.","seo_description_is_default":false,"seo_title":"Shop all brands","seo_title_default":"Brands – Acme","seo_title_is_default":false,"social_description":"Explore every brand available in our store.","social_description_default":"Explore every brand available in our store.","social_description_is_default":true,"social_image_default_id":null,"social_image_id":"8f2a1c2b-9d4e-4a56-b789-0123456789ab","social_image_is_default":false,"social_title":"Shop all brands","social_title_default":"Shop all brands","social_title_is_default":true,"store_id":"74e634ea-84ec-43b8-b66b-986214c2c5a3","storefront_id":null}},"message":"SEO saved.","success":true}

Webhook events#

Subscribe to source and translation events when your app mirrors list-page SEO. Source writes and their event commit in one transaction. Translation update and delete events identify the stable page_type and locale.

List-page SEO updated

EVENT list_page_seo/update App scope: read_products Staff permission: products:write

Fired when SEO settings change for the public brand, vendor, or category list page. The payload identifies the list with page_type and carries its current source snapshot.

Possible `changed_fields` values

The changed_fields array names exactly which of these changed in this event — use it to skip processing updates your integration doesn't care about.

robots_follow robots_index seo_description seo_title social_description social_image_id social_title

Payload fields

Field	Type	Description
`list_page_seo.id`	`integer`	Always present The stable storage id for this list-page SEO record.
`list_page_seo.page_type`	`string`	Always present The public catalog list being described: brand_list, vendor_list, category_list, or collection_list.
`list_page_seo.seo_title`	`string`	Selectable in the Payload builder The list page's SEO title in the store's default language.
`list_page_seo.seo_description`	`string`	Selectable in the Payload builder The list page's SEO description in the store's default language.
`list_page_seo.social_title`	`string`	Selectable in the Payload builder The default-language social sharing title override.
`list_page_seo.social_description`	`string`	Selectable in the Payload builder The default-language social sharing description override.
`list_page_seo.social_image_id`	`string`	Selectable in the Payload builder The assigned site-asset image id, or null when no override is assigned.
`list_page_seo.robots_index`	`boolean`	Selectable in the Payload builder Whether search engines may index this list page.
`list_page_seo.robots_follow`	`boolean`	Selectable in the Payload builder Whether search engines may follow links from this list page.
`list_page_seo.updated_at`	`string`	Selectable in the Payload builder When the source list-page SEO settings last changed, in the store's timezone.
`changed_fields`	`array`	Always present The source list-page SEO fields changed by this event.

Payload shape

Sample payload

{
  "changed_fields": [
    "seo_title",
    "seo_description"
  ],
  "list_page_seo": {
    "id": 42,
    "page_type": "brand_list",
    "robots_follow": true,
    "robots_index": true,
    "seo_description": "Browse every brand available in our store.",
    "seo_title": "Shop brands",
    "social_description": "Discover brands selected by our team.",
    "social_image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "social_title": "Our brands",
    "updated_at": "2026-08-27T09:30:00+05:30"
  }
}

List-page SEO translations updated

EVENT list_page_seo/translations/update App scope: read_products Staff permission: products:write

Fired when translated SEO fields are added or updated for the public brand, vendor, or category list page in a locale. The payload identifies the list with page_type and carries only the translated fields that changed.

Payload fields

Field	Type	Description
`list_page_seo.id`	`integer`	Always present The stable storage id for this list-page SEO record.
`list_page_seo.page_type`	`string`	Always present The public catalog list being described: brand_list, vendor_list, category_list, or collection_list.
`list_page_seo.seo_title`	`string`	Selectable in the Payload builder The list page's SEO title in the store's default language.
`list_page_seo.seo_description`	`string`	Selectable in the Payload builder The list page's SEO description in the store's default language.
`list_page_seo.social_title`	`string`	Selectable in the Payload builder The default-language social sharing title override.
`list_page_seo.social_description`	`string`	Selectable in the Payload builder The default-language social sharing description override.
`list_page_seo.social_image_id`	`string`	Selectable in the Payload builder The assigned site-asset image id, or null when no override is assigned.
`list_page_seo.robots_index`	`boolean`	Selectable in the Payload builder Whether search engines may index this list page.
`list_page_seo.robots_follow`	`boolean`	Selectable in the Payload builder Whether search engines may follow links from this list page.
`list_page_seo.updated_at`	`string`	Selectable in the Payload builder When the source list-page SEO settings last changed, in the store's timezone.
`locale`	`string`	Selectable in the Payload builder The locale whose list-page SEO translation changed.
`translation.seo_title`	`string`	Selectable in the Payload builder The translated SEO title; an empty string on the delete event means it was removed.
`translation.seo_description`	`string`	Selectable in the Payload builder The translated SEO description; an empty string on the delete event means it was removed.
`translation.social_title`	`string`	Selectable in the Payload builder The translated social title; an empty string on the delete event means it was removed.
`translation.social_description`	`string`	Selectable in the Payload builder The translated social description; an empty string on the delete event means it was removed.
`updated_at`	`string`	Selectable in the Payload builder When this locale's list-page SEO translation changed, in the store's timezone.

Payload shape

Sample payload

{
  "list_page_seo": {
    "id": 42,
    "page_type": "brand_list",
    "robots_follow": true,
    "robots_index": true,
    "seo_description": "Browse every brand available in our store.",
    "seo_title": "Shop brands",
    "social_description": "Discover brands selected by our team.",
    "social_image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "social_title": "Our brands",
    "updated_at": "2026-08-27T09:30:00+05:30"
  },
  "locale": "fr",
  "translation": {
    "seo_description": "Parcourez toutes les marques disponibles dans notre boutique.",
    "seo_title": "Découvrir nos marques",
    "social_description": "Découvrez les marques sélectionnées par notre équipe.",
    "social_title": "Nos marques"
  },
  "updated_at": "2026-08-27T09:30:00+05:30"
}

List-page SEO translations deleted

EVENT list_page_seo/translations/delete App scope: read_products Staff permission: products:write

Fired when translated SEO fields are cleared for the public brand, vendor, or category list page in a locale. The payload identifies the list with page_type and carries the cleared fields as empty strings.

Payload fields

Field	Type	Description
`list_page_seo.id`	`integer`	Always present The stable storage id for this list-page SEO record.
`list_page_seo.page_type`	`string`	Always present The public catalog list being described: brand_list, vendor_list, category_list, or collection_list.
`list_page_seo.seo_title`	`string`	Selectable in the Payload builder The list page's SEO title in the store's default language.
`list_page_seo.seo_description`	`string`	Selectable in the Payload builder The list page's SEO description in the store's default language.
`list_page_seo.social_title`	`string`	Selectable in the Payload builder The default-language social sharing title override.
`list_page_seo.social_description`	`string`	Selectable in the Payload builder The default-language social sharing description override.
`list_page_seo.social_image_id`	`string`	Selectable in the Payload builder The assigned site-asset image id, or null when no override is assigned.
`list_page_seo.robots_index`	`boolean`	Selectable in the Payload builder Whether search engines may index this list page.
`list_page_seo.robots_follow`	`boolean`	Selectable in the Payload builder Whether search engines may follow links from this list page.
`list_page_seo.updated_at`	`string`	Selectable in the Payload builder When the source list-page SEO settings last changed, in the store's timezone.
`locale`	`string`	Selectable in the Payload builder The locale whose list-page SEO translation changed.
`translation.seo_title`	`string`	Selectable in the Payload builder The translated SEO title; an empty string on the delete event means it was removed.
`translation.seo_description`	`string`	Selectable in the Payload builder The translated SEO description; an empty string on the delete event means it was removed.
`translation.social_title`	`string`	Selectable in the Payload builder The translated social title; an empty string on the delete event means it was removed.
`translation.social_description`	`string`	Selectable in the Payload builder The translated social description; an empty string on the delete event means it was removed.
`updated_at`	`string`	Selectable in the Payload builder When this locale's list-page SEO translation changed, in the store's timezone.

Payload shape

Sample payload

{
  "list_page_seo": {
    "id": 42,
    "page_type": "brand_list",
    "robots_follow": true,
    "robots_index": true,
    "seo_description": "Browse every brand available in our store.",
    "seo_title": "Shop brands",
    "social_description": "Discover brands selected by our team.",
    "social_image_id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "social_title": "Our brands",
    "updated_at": "2026-08-27T09:30:00+05:30"
  },
  "locale": "fr",
  "translation": {
    "seo_description": "",
    "seo_title": "",
    "social_description": "",
    "social_title": ""
  },
  "updated_at": "2026-08-27T09:30:00+05:30"
}

Endpoints#

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Webhook events#

Possible changed_fields values

Payload fields

Payload fields

Payload fields

Possible `changed_fields` values