Preferences

Read the store-wide favicon, permalink structure, and age gate and update them through the Store API.

Preferences apply across every storefront in the store. Permalink values are logical route segments; the storefront runtime combines them with the active domain, country, and language address. On a shared domain, the primary country and language live at the root, another language for that country uses /{locale}, and another country uses /{locale}-{country}. A country-pinned domain serves that country's default language at the root and its other languages under /{locale}.

Changing a permalink and creating its compatibility redirects are one transaction. Either the complete route change commits or nothing changes.

The age gate asks visitors to confirm a minimum age when they enter any storefront in the store. It is a confirmation, not an identity check. Store Admin and the mobile app show it under Settings > Compliance. Every storefront page includes the gate while the page content stays in the HTML, so search engines and advertising crawlers still see the store. A visitor's answer is kept in a first-party cookie for the browser session or for remember_days days. The visitor country is the one the consent banner uses; in selected-countries mode a visitor whose country is unknown sees the gate. Age gate changes publish no webhook event.

Endpoints#

Preferences limits

GET read_storefront

Get live Preferences limits.

Returns the current maximum length for every permalink segment.

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.

curl 'https://api-store.tringify.com/api/2025-01/preferences/limits' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/preferences/limits", {
  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/preferences/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"permalink_max_length":50}}

Get preferences

GET read_storefront

Get the store-wide favicon and permalink structure.

These settings apply to every storefront in the store.

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.

curl 'https://api-store.tringify.com/api/2025-01/preferences' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/preferences", {
  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/preferences",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"favicon_file_id":null,"favicon_url":null,"permalinks":{"product":"product","collection":"collection","category":"category","page":"page","policy":"policy","blog":"blog","vendor":"vendor","brand":"brand","shop":"shop","blog_category":"blog-category","search":"search","vendor_list":"vendors","brand_list":"brands","collection_list":"collections","category_list":"categories","blog_list":"blogs"}}}

Set favicon

PUT write_storefront

Set or remove the store-wide favicon.

Pass a site asset image id, or null to remove the favicon. Assigning an image also requires read_site_assets.

Headers

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

Body parameters

Name	Type	Description
`favicon_file_id` required	`string\|null`	Site asset image id, or null to remove the favicon. Example: `null`

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 id is malformed, the file is not an image, or it is not a site asset.
404 NOT_FOUND
The file does not exist in this store.
400 STORE_API_INVALID_REQUEST_BODY
The body has an unknown field or is missing favicon_file_id.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/preferences/favicon' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "favicon_file_id": null
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/preferences/favicon", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "favicon_file_id": null
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/preferences/favicon",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "favicon_file_id": None,
    },
)
data = res.json()

Response

200

Sample response

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

Get permalinks

GET read_storefront

Get every storefront permalink segment.

Returns all detail and listing route segments used by the storefront URL resolver.

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.

curl 'https://api-store.tringify.com/api/2025-01/preferences/permalinks' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/preferences/permalinks", {
  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/preferences/permalinks",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"permalinks":{"product":"product","collection":"collection","category":"category","page":"page","policy":"policy","blog":"blog","vendor":"vendor","brand":"brand","shop":"shop","blog_category":"blog-category","search":"search","vendor_list":"vendors","brand_list":"brands","collection_list":"collections","category_list":"categories","blog_list":"blogs"}}}

Update permalinks

PUT write_storefront

Replace the full storefront permalink structure.

Send all permalink fields. Values must be unique unless the corresponding detail and listing routes are allowed to share a segment. Unknown fields are rejected. Renames create URL redirects transactionally.

Headers

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

Body parameters

Name	Type	Description
`permalinks` required	`object`	Complete permalink object returned by the read endpoint. Example: `{"product":"product","collection":"collection","category":"category","page":"page","policy":"policy","blog":"blog","vendor":"vendor","brand":"brand","shop":"shop","blog_category":"blog-category","search":"search","vendor_list":"vendors","brand_list":"brands","collection_list":"collections","category_list":"categories","blog_list":"blogs"}`

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 STORE_API_INVALID_REQUEST_BODY
The body has an unknown field or is missing required permalinks.
400 STOREFRONT_PERMALINK_EMPTY
A permalink value is empty.
400 STOREFRONT_PERMALINK_TOO_LONG
A permalink value exceeds the live maximum.
400 STOREFRONT_PERMALINK_INVALID_CHARS
A permalink contains characters outside lowercase letters, numbers, and hyphens.
400 STOREFRONT_PERMALINK_RESERVED
A permalink uses a reserved route or locale code.
400 STOREFRONT_PERMALINK_DUPLICATE
Two incompatible routes use the same permalink.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/preferences/permalinks' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "permalinks": {
    "blog": "blog",
    "blog_category": "blog-category",
    "blog_list": "blogs",
    "brand": "brand",
    "brand_list": "brands",
    "category": "category",
    "category_list": "categories",
    "collection": "collection",
    "collection_list": "collections",
    "page": "page",
    "policy": "policy",
    "product": "product",
    "search": "search",
    "shop": "shop",
    "vendor": "vendor",
    "vendor_list": "vendors"
  }
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/preferences/permalinks", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "permalinks": {
      "blog": "blog",
      "blog_category": "blog-category",
      "blog_list": "blogs",
      "brand": "brand",
      "brand_list": "brands",
      "category": "category",
      "category_list": "categories",
      "collection": "collection",
      "collection_list": "collections",
      "page": "page",
      "policy": "policy",
      "product": "product",
      "search": "search",
      "shop": "shop",
      "vendor": "vendor",
      "vendor_list": "vendors"
    }
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/preferences/permalinks",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "permalinks": {
            "blog": "blog",
            "blog_category": "blog-category",
            "blog_list": "blogs",
            "brand": "brand",
            "brand_list": "brands",
            "category": "category",
            "category_list": "categories",
            "collection": "collection",
            "collection_list": "collections",
            "page": "page",
            "policy": "policy",
            "product": "product",
            "search": "search",
            "shop": "shop",
            "vendor": "vendor",
            "vendor_list": "vendors",
        },
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"permalinks":{"product":"product","collection":"collection","category":"category","page":"page","policy":"policy","blog":"blog","vendor":"vendor","brand":"brand","shop":"shop","blog_category":"blog-category","search":"search","vendor_list":"vendors","brand_list":"brands","collection_list":"collections","category_list":"categories","blog_list":"blogs"}}}

Age gate limits

GET read_storefront

Get the allowed age gate values.

Returns the minimum age and remember-days ranges, the copy length limits, the country limit, the allowed modes, and default_copy: the platform text an empty copy field shows, with {age} standing for min_age.

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.

curl 'https://api-store.tringify.com/api/2025-01/preferences/age-gate/limits' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/preferences/age-gate/limits", {
  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/preferences/age-gate/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"min_age_lowest":13,"min_age_highest":25,"remember_days_lowest":1,"remember_days_highest":30,"heading_max_length":120,"body_max_length":600,"label_max_length":40,"decline_url_max_length":2048,"max_countries":249,"show_to_options":["all","selected_countries"],"remember_options":["session","days"],"decline_action_options":["message","redirect"],"default_copy":{"heading":"Confirm your age","body":"You must be {age} or older to enter this store.","confirm_label":"I am {age} or older","decline_label":"I am under {age}","declined_heading":"Sorry, you can’t enter yet","declined_body":"Come back when you are {age}."}}}

Get age gate

GET read_storefront

Get the store-wide age gate.

The age gate is shown on every storefront in the store when a visitor enters, to all visitors or to visitors from countries. A visitor whose country is unknown sees it in selected-countries mode. Empty copy fields use the platform text in the shopper's language. revision changes on every saved change.

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.

curl 'https://api-store.tringify.com/api/2025-01/preferences/age-gate' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/preferences/age-gate", {
  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/preferences/age-gate",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"age_gate":{"enabled":true,"min_age":18,"show_to":"selected_countries","countries":["DE","FR"],"remember_mode":"days","remember_days":30,"decline_action":"message","decline_url":"","heading":"","body":"","confirm_label":"","decline_label":"","revision":"9f2c4f3b7d1e0a6c5b8e2d4f1a3c6e9b0d2f4a6c8e1b3d5f7a9c0e2b4d6f8a1c"}}}

Update age gate

PUT write_storefront

Replace the store-wide age gate.

Send every field of age_gate; unknown fields are rejected. Country codes are ISO 3166-1 alpha-2, upper-cased and deduplicated; they are cleared when show_to is all. remember_days is used when remember_mode is days. decline_url is required when decline_action is redirect; it must be an absolute https:// address. {age} in the copy is replaced with min_age. Send expected_revision to refuse the change when someone saved in between. Storefront pages show the change at once.

Headers

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

Body parameters

Name	Type	Description
`age_gate` required	`object`	The complete age gate, as returned by Get age gate without `revision`. Example: `{"enabled":true,"min_age":18,"show_to":"selected_countries","countries":["DE","FR"],"remember_mode":"days","remember_days":30,"decline_action":"message","decline_url":"","heading":"","body":"","confirm_label":"","decline_label":""}`
`expected_revision`	`string`	`revision` from Get age gate. A concurrent change returns `CONFLICT`. Example: `9f2c4f3b7d1e0a6c5b8e2d4f1a3c6e9b0d2f4a6c8e1b3d5f7a9c0e2b4d6f8a1c`

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 STORE_API_INVALID_REQUEST_BODY
The body has an unknown field, is missing age_gate, or a field has the wrong type.
400 AGE_GATE_SHOW_TO_INVALID
show_to is not all or selected_countries.
400 AGE_GATE_MIN_AGE_INVALID
min_age is outside 13 to 25.
400 AGE_GATE_REMEMBER_INVALID
remember_mode is not session or days.
400 AGE_GATE_REMEMBER_DAYS_INVALID
remember_days is outside 1 to 30.
400 AGE_GATE_DECLINE_ACTION_INVALID
decline_action is not message or redirect.
400 AGE_GATE_DECLINE_URL_REQUIRED
decline_action is redirect and decline_url is empty.
400 AGE_GATE_DECLINE_URL_INVALID
decline_url is not an absolute https address, has user information, or is longer than 2048 characters.
400 AGE_GATE_TEXT_INVALID
A copy field is longer than its limit or contains control characters.
400 AGE_GATE_COUNTRIES_REQUIRED
The gate is enabled for selected countries with no country.
400 AGE_GATE_COUNTRIES_TOO_MANY
More countries than max_countries.
400 AGE_GATE_COUNTRY_INVALID
A country code is not a known ISO 3166-1 alpha-2 code.
409 CONFLICT
expected_revision no longer matches: the age gate changed since it was read.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/preferences/age-gate' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "age_gate": {
    "body": "",
    "confirm_label": "",
    "countries": [
      "DE",
      "FR"
    ],
    "decline_action": "message",
    "decline_label": "",
    "decline_url": "",
    "enabled": true,
    "heading": "",
    "min_age": 18,
    "remember_days": 30,
    "remember_mode": "days",
    "show_to": "selected_countries"
  },
  "expected_revision": "9f2c4f3b7d1e0a6c5b8e2d4f1a3c6e9b0d2f4a6c8e1b3d5f7a9c0e2b4d6f8a1c"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/preferences/age-gate", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "age_gate": {
      "body": "",
      "confirm_label": "",
      "countries": [
        "DE",
        "FR"
      ],
      "decline_action": "message",
      "decline_label": "",
      "decline_url": "",
      "enabled": true,
      "heading": "",
      "min_age": 18,
      "remember_days": 30,
      "remember_mode": "days",
      "show_to": "selected_countries"
    },
    "expected_revision": "9f2c4f3b7d1e0a6c5b8e2d4f1a3c6e9b0d2f4a6c8e1b3d5f7a9c0e2b4d6f8a1c"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/preferences/age-gate",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "age_gate": {
            "body": "",
            "confirm_label": "",
            "countries": ["DE", "FR"],
            "decline_action": "message",
            "decline_label": "",
            "decline_url": "",
            "enabled": True,
            "heading": "",
            "min_age": 18,
            "remember_days": 30,
            "remember_mode": "days",
            "show_to": "selected_countries",
        },
        "expected_revision": "9f2c4f3b7d1e0a6c5b8e2d4f1a3c6e9b0d2f4a6c8e1b3d5f7a9c0e2b4d6f8a1c",
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"code":"AGE_GATE_UPDATED","message":"Age gate settings saved.","data":{"age_gate":{"enabled":true,"min_age":18,"show_to":"selected_countries","countries":["DE","FR"],"remember_mode":"days","remember_days":30,"decline_action":"message","decline_url":"","heading":"","body":"","confirm_label":"","decline_label":"","revision":"9f2c4f3b7d1e0a6c5b8e2d4f1a3c6e9b0d2f4a6c8e1b3d5f7a9c0e2b4d6f8a1c"}}}

Webhook events#

Subscribe when an integration mirrors the store-wide favicon or permalink structure.

Online Store preferences updated

EVENT storefront_preferences/update App scope: read_storefront Staff permission: online_store.preferences:write

Fired when the store-wide favicon or permalink structure changes.

Payload fields

Field	Type	Description
`preferences.favicon_file_id`	`string`	Selectable in the Payload builder
`preferences.permalinks.product`	`string`	Selectable in the Payload builder
`preferences.permalinks.shop`	`string`	Selectable in the Payload builder
`preferences.permalinks.category`	`string`	Selectable in the Payload builder
`preferences.permalinks.category_list`	`string`	Selectable in the Payload builder
`preferences.permalinks.collection`	`string`	Selectable in the Payload builder
`preferences.permalinks.collection_list`	`string`	Selectable in the Payload builder
`preferences.permalinks.vendor`	`string`	Selectable in the Payload builder
`preferences.permalinks.vendor_list`	`string`	Selectable in the Payload builder
`preferences.permalinks.brand`	`string`	Selectable in the Payload builder
`preferences.permalinks.brand_list`	`string`	Selectable in the Payload builder
`preferences.permalinks.blog`	`string`	Selectable in the Payload builder
`preferences.permalinks.blog_list`	`string`	Selectable in the Payload builder
`preferences.permalinks.blog_category`	`string`	Selectable in the Payload builder
`preferences.permalinks.page`	`string`	Selectable in the Payload builder
`preferences.permalinks.policy`	`string`	Selectable in the Payload builder
`preferences.permalinks.search`	`string`	Selectable in the Payload builder
`preferences.updated_at`	`string`	Selectable in the Payload builder
`changed_fields`	`array`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "changed_fields": [
    "title",
    "status"
  ],
  "preferences": {
    "favicon_file_id": null,
    "permalinks": {
      "blog": "...",
      "blog_category": "...",
      "blog_list": "...",
      "brand": "...",
      "brand_list": "...",
      "category": "...",
      "category_list": "...",
      "collection": "...",
      "collection_list": "...",
      "page": "...",
      "policy": "...",
      "product": "...",
      "search": "...",
      "shop": "...",
      "vendor": "...",
      "vendor_list": "..."
    },
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}