Language and country SEO overrides

Set a storefront's title pattern and share image for one language, or one language in one country.

A storefront has one base title pattern (title_template) and the store has one share image, both set with Update page titles and share image. An override replaces either of them for one language, or for one language in one country. Reads require read_storefront; writes require write_storefront, plus read_site_assets when assigning a share image.

For a page shown in language L to a shopper in country C, each field comes from the first set value: the override for L in C, the override for L in every country (empty country_code), then the base setting. null inherits; an empty title_template means no pattern for that language. add_store_name_to_page_titles is store-wide: it applies wherever the effective pattern is empty and has no effect where a pattern is set, because a pattern replaces the automatic store-name suffix.

A pattern may use only {{ page_title }} and {{ shop_name }} (any spacing inside the braces), every {{ needs its }}, and it is at most 200 characters counted as Unicode code points. Patterns shape generated titles only: a title saved on a page, a translation or a country row is final. For example, keep {{ page_title }} – {{ shop_name }} as the base and set {{ shop_name }} | {{ page_title }} for ja.

The effective share image is the social image of every page that has neither its own social image nor an entity image, including content pages and policies; after it comes the store logo. Overrides take effect on the next render of each affected page.

Endpoints#

List SEO overrides

GET read_storefront

List a storefront's title pattern and share image overrides by language and country.

Each override applies to one locale and, when country_code is set, only to shoppers in that country; an empty country_code applies in every country. A null field uses the next broader setting. For a page in a language and country the storefront takes each field from the override for that language and country, then the override for that language, then the storefront's title_template and the store's share image. An empty title_template means no pattern for that language: generated titles then follow add_store_name_to_page_titles, which is store-wide. A pattern replaces the automatic store-name suffix. Patterns shape generated titles only; titles saved on a page are final. Images include share_image_url. locale_label and country_name are the language's and country's display names (country_name is empty for the every-country override), also for an override whose language the storefront no longer publishes.

Path parameters

Name	Type	Description
`storefrontId` required	`uuid`	Storefront id from List storefronts. Example: `0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41`

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 INVALID_INPUT
The storefront id is not a UUID.
404 STOREFRONT_NOT_FOUND
No storefront with this id belongs to the store.

curl 'https://api-store.tringify.com/api/2025-01/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides", {
  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/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"storefront_id":"0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41","overrides":[{"storefront_id":"0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41","locale":"de","locale_label":"German","country_code":"","country_name":"","title_template":"{{ page_title }} | {{ shop_name }}","share_image_id":null,"share_image_url":null,"created_at":"2026-10-26T06:00:00-04:00","updated_at":"2026-10-26T06:00:00-04:00"},{"storefront_id":"0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41","locale":"de","locale_label":"German","country_code":"CH","country_name":"Switzerland","title_template":"{{ shop_name }} | {{ page_title }}","share_image_id":"5b0f8f43-2f47-4c34-9a0f-0b7d3a3f8f21","share_image_url":"https://shop.example.com/cdn/site-assets/share-ch.jpg","created_at":"2026-10-26T06:15:00-04:00","updated_at":"2026-10-26T06:15:00-04:00"}]}}

Set an SEO override

PUT write_storefront; read_site_assets only when assigning share_image_id

Create or change the title pattern or share image for one language, or one language in one country.

Omit country_code, or send an empty string, for the language-wide override; send a country code for that country only. This is a patch: an omitted field keeps its value (a new override starts with both null). null makes a field use the next broader setting. An empty title_template sets no pattern for this language; an empty share_image_id is the same as null. At least one field must stay set, otherwise the request fails with SEO_OVERRIDE_EMPTY: remove the override with Delete an SEO override instead. title_template may use only {{ page_title }} and {{ shop_name }} and is at most 200 characters (Unicode code points). Assigning a share image requires read_site_assets and a site-asset image from this store. A change sends storefront/seo_overrides/update.

Path parameters

Name	Type	Description
`storefrontId` required	`uuid`	Storefront id from List storefronts. Example: `0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41`
`locale` required	`string`	A language the storefront publishes, including its primary language. Example: `de`

Headers

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

Body parameters

Name	Type	Description
`country_code`	`string`	ISO 3166-1 alpha-2 country code. Omit or send an empty string for every country. Example: `CH`
`title_template`	`string\|null`	Title pattern for this language or country. Empty for no pattern; null to use the next broader setting. Example: `{{ shop_name }} \| {{ page_title }}`
`share_image_id`	`string\|null`	Site-asset image shared by pages without their own image. Empty or null to use the next broader setting. Example: `5b0f8f43-2f47-4c34-9a0f-0b7d3a3f8f21`

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. Assigning a share image also requires read_site_assets.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 INVALID_INPUT
The storefront id is not a UUID. share_image_id is malformed, not an image, outside this store, or not a site asset.
404 STOREFRONT_NOT_FOUND
No storefront with this id belongs to the store.
400 STORE_API_INVALID_REQUEST_BODY
The body has an unknown field or a field has the wrong type.
400 SEO_TITLE_TEMPLATE_UNBALANCED
title_template has an unmatched {{ or }}.
400 SEO_TITLE_TEMPLATE_UNKNOWN_TOKEN
title_template uses a placeholder other than page_title and shop_name.
400 SEO_TITLE_TEMPLATE_TOO_LONG
title_template is longer than 200 characters (Unicode code points).
400 SEO_OVERRIDE_EMPTY
The override would have neither a title pattern nor a share image. Delete it instead.
400 STOREFRONT_LANGUAGE_NOT_SERVED
The storefront does not publish this language, or does not serve it in this country.
400 STOREFRONT_COUNTRY_INVALID
country_code is not an ISO 3166-1 alpha-2 country code.
400 STOREFRONT_COUNTRY_NOT_SERVED
The storefront does not serve this country.
400 STORE_API_BODY_PROPERTY_UNKNOWN
The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
400 STORE_API_BODY_PROPERTY_INVALID
A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides/de' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "country_code": "CH",
  "share_image_id": "5b0f8f43-2f47-4c34-9a0f-0b7d3a3f8f21",
  "title_template": "{{ shop_name }} | {{ page_title }}"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides/de", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "country_code": "CH",
    "share_image_id": "5b0f8f43-2f47-4c34-9a0f-0b7d3a3f8f21",
    "title_template": "{{ shop_name }} | {{ page_title }}"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides/de",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "country_code": "CH",
        "share_image_id": "5b0f8f43-2f47-4c34-9a0f-0b7d3a3f8f21",
        "title_template": "{{ shop_name }} | {{ page_title }}",
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"override":{"storefront_id":"0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41","locale":"de","locale_label":"German","country_code":"CH","country_name":"Switzerland","title_template":"{{ shop_name }} | {{ page_title }}","share_image_id":"5b0f8f43-2f47-4c34-9a0f-0b7d3a3f8f21","share_image_url":"https://shop.example.com/cdn/site-assets/share-ch.jpg","created_at":"2026-10-26T06:15:00-04:00","updated_at":"2026-10-26T06:15:00-04:00"}}}

Delete an SEO override

DELETE write_storefront

Remove the title pattern and share image override for one language, or one language in one country.

Pass country_code to remove that country's override; omit it to remove the language-wide override. Removing the language-wide override keeps its country overrides. Pages then use the next broader setting. A removal sends storefront/seo_overrides/delete.

Path parameters

Name	Type	Description
`storefrontId` required	`uuid`	Storefront id from List storefronts. Example: `0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41`
`locale` required	`string`	A language the storefront publishes, including its primary language. Example: `de`

Query parameters

Name	Type	Description
`country_code`	`string`	ISO 3166-1 alpha-2 country code of the override to remove. Omit for the language-wide override. Example: `CH`

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 INVALID_INPUT
The storefront id is not a UUID.
404 STOREFRONT_NOT_FOUND
No storefront with this id belongs to the store.
404 SEO_OVERRIDE_NOT_FOUND
The storefront has no override for this language and country.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides/de?country_code=CH' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides/de?country_code=CH", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/storefronts/0b7c2f0e-6a43-4f7e-9d1c-3f2a8e5b9c41/seo/overrides/de?country_code=CH",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"deleted":true}}

Webhook events#

Subscribe when an integration mirrors per-language or per-country titles and share images. Each event identifies the storefront, locale and country_code, and is sent after the change commits. Base pattern and share image changes send storefronts/update.

Storefront SEO override updated

EVENT storefront/seo_overrides/update App scope: read_storefront Staff permission: online_store.storefronts:write

Fired when a storefront's title pattern or share image for one language, or one language in one country, is saved. The payload carries the complete override: a null field uses the next broader setting.

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.

share_image_id title_template

Payload fields

Field	Type	Description
`storefront_seo_override.storefront_id`	`string`	Always present The storefront this override belongs to.
`storefront_seo_override.locale`	`string`	Always present The language the override applies to.
`storefront_seo_override.country_code`	`string`	Selectable in the Payload builder The country the override applies to, as an ISO 3166-1 alpha-2 code. Empty when it applies in every country.
`storefront_seo_override.title_template`	`string`	Selectable in the Payload builder The title pattern for this language or country, or null to use the next broader setting. An empty string means no pattern: titles use the automatic store-name suffix setting.
`storefront_seo_override.share_image_id`	`string`	Selectable in the Payload builder The site-asset image shared by pages without their own image, or null to use the next broader setting.
`storefront_seo_override.updated_at`	`string`	Selectable in the Payload builder When the override last changed, in the store's time zone with its offset.
`changed_fields`	`array`	Always present The override fields changed by this event: title_template or share_image_id.

Payload shape

Sample payload

{
  "changed_fields": [
    "title_template"
  ],
  "storefront_seo_override": {
    "country_code": "CH",
    "locale": "de",
    "share_image_id": null,
    "storefront_id": "c2ee5620-e43e-405b-899a-b90c212ce9e8",
    "title_template": "{{ shop_name }} | {{ page_title }}",
    "updated_at": "2026-10-26T10:15:00-04:00"
  }
}

Storefront SEO override deleted

EVENT storefront/seo_overrides/delete App scope: read_storefront Staff permission: online_store.storefronts:write

Fired when a storefront's title pattern and share image override for one language, or one language in one country, is removed. The payload carries the override as it was before removal.

Payload fields

Field	Type	Description
`storefront_seo_override.storefront_id`	`string`	Always present The storefront this override belongs to.
`storefront_seo_override.locale`	`string`	Always present The language the override applies to.
`storefront_seo_override.country_code`	`string`	Selectable in the Payload builder The country the override applies to, as an ISO 3166-1 alpha-2 code. Empty when it applies in every country.
`storefront_seo_override.title_template`	`string`	Selectable in the Payload builder The title pattern for this language or country, or null to use the next broader setting. An empty string means no pattern: titles use the automatic store-name suffix setting.
`storefront_seo_override.share_image_id`	`string`	Selectable in the Payload builder The site-asset image shared by pages without their own image, or null to use the next broader setting.
`storefront_seo_override.updated_at`	`string`	Selectable in the Payload builder When the override last changed, in the store's time zone with its offset.

Payload shape

Sample payload

{
  "storefront_seo_override": {
    "country_code": "CH",
    "locale": "de",
    "share_image_id": null,
    "storefront_id": "c2ee5620-e43e-405b-899a-b90c212ce9e8",
    "title_template": "{{ shop_name }} | {{ page_title }}",
    "updated_at": "2026-10-26T10:15:00-04:00"
  }
}

Endpoints#

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Query parameters

Headers

Errors

Webhook events#

Possible changed_fields values

Payload fields

Payload fields

Possible `changed_fields` values