Storefronts

Returns the storefront limits Store Admin uses, including password_min_length (the shortest new storefront password, in characters) and password_max_bytes (the longest storefront password, in UTF-8 bytes) and the storefront modes. custom_pixels gives the custom pixel limits: at most max_per_storefront per storefront (disabled ones included), a name of 1 to name_max_length characters (at most 100) and code of at most code_max_length characters (at most 65536), both in Unicode code points, and the allowed consent_categories. Manage custom pixels with List custom pixels and Create a custom pixel.

Returns every storefront with its mode, password protection, domains and primary_url (empty until a primary domain is active). Read a storefront's languages with Get storefront languages. urls is an array of active, HTTPS-ready public domain names, primary first, including the permanent mytringify address on the primary storefront. No schemes or paths are included. public_contact_email is the store’s explicitly public contact email, or empty when unset; it never falls back to a private login, sender or reply-to address. Both fields require read_storefront. Refresh urls on domains/create, domains/update and domains/delete; those events also include default_country, default_locale, retired_country, retired_locale, public_ready and address_revision. Read Country URLs for complete canonical addresses and diagnostics. The mytringify subdomain cannot be renamed.

Adds the store's add_store_name_to_page_titles and share image to the storefront. Next to storefront (not inside it), data carries go_live: whether the store can go live (ready) and, if not, the blockers to fix first, each with its code, its message in the request language, the record to fix (target, a kind and id) and, for an incomplete primary-location address, missing_fields: each blank field as field (line1, city, postal_code or country) and its label in the request language (a location in India names its postal code "PIN code"); and cache: when the storefront cache was last cleared (last_cleared_at, null if never), when it can be cleared again (next_available_at, null if never cleared), whether it can be cleared now (can_clear, the server's verdict) and the wait between clears in hours (cooldown_hours); and mode_options: the three modes in order, each value with its label and description in the request language (English by default; live says so when a password protects the storefront), and for the offline modes offline_notice, what shoppers see once a live storefront is switched to it. Times are RFC 3339 in the store's timezone with its offset. urls is an array of active, HTTPS-ready public domain names, primary first, including the permanent mytringify address on the primary storefront. No schemes or paths are included. public_contact_email is the store’s explicitly public contact email, or empty when unset; it never falls back to a private login, sender or reply-to address. Both fields require read_storefront. Refresh urls on domains/create, domains/update and domains/delete; those events also include default_country, default_locale, retired_country, retired_locale, public_ready and address_revision. Read Country URLs for complete canonical addresses and diagnostics. The mytringify subdomain cannot be renamed.

mode is live, maintenance or coming_soon; the current one is mode in Get a storefront. Maintenance and coming soon take the storefront offline at once: shoppers see the maintenance or coming-soon page instead of the store. Taking a live storefront offline needs confirmation. The first request returns HTTP 409 CONFIRMATION_REQUIRED with error.details: warnings (English), confirmation_token, action, current_mode and target_mode. Show the change to the merchant and, after approval, repeat the same mode with confirmed: true and that confirmation_token. The token is single use, valid for five minutes and good only for this storefront and this target mode; a request that fails does not use it up. Switching to live, or between maintenance and coming soon, needs no confirmation. Going live is refused with STOREFRONT_NOT_READY_TO_GO_LIVE until the store is ready: error.details.blockers lists what to fix, the same list as go_live in Get a storefront. Sending the current mode changes nothing. If the status changed after you read it, the request returns STOREFRONT_MODE_CONFLICT: read the storefront again and decide anew. Password protection is separate and stays as it is. The response has the same shape as Get a storefront (storefront, go_live, cache, mode_options). A change sends storefronts/update.

These are the defaults for pages that have no title or image of their own. title_template is required: send the complete template, or an empty string for no pattern. It may use only the tokens returned in tokens ({{ page_title }} and {{ shop_name }}), every {{ needs its }}, and it is at most 200 characters (Unicode code points). The pattern formats generated titles only: a title saved on a page, translation or country row is final, and the home page's generated title is the store name. A non-empty pattern replaces the automatic store-name suffix, so add_store_name_to_page_titles has no effect while one is set; without a pattern, the store name is appended to generated titles when it is on. Omit add_store_name_to_page_titles or share_image_id to keep them. share_image_id takes a site asset image id; an empty string or null removes the image, and assigning an image also requires read_site_assets. The store-name suffix and share image apply to every storefront in the store. This pattern and share image are the base for every language and country; set a different pattern or image for one language, or one language in one country, with Set an SEO override. The response includes preview for the saved settings in the storefront primary language. Each preview.samples item has kind, page_name, title and description; description is the computed plain-text meta description, with HTML removed, entities decoded and whitespace collapsed before limiting it to 160 Unicode code points (including the closing ellipsis when shortened). The samples are a generated example product, Shop and Home.

Takes effect at once, with no confirmation step. Send a non-empty password to protect the storefront with it: from then on every visitor must enter it, so a live storefront is hidden from shoppers immediately, and visitors who unlocked it with an earlier password must enter the new one. Send an empty string or null to remove protection and make the storefront public again. Leading and trailing spaces are removed; a password made only of spaces is rejected with INVALID_INPUT. A new password needs at least password_min_length (8) characters, counted as Unicode characters after removing those spaces; a shorter one is rejected with STOREFRONT_PASSWORD_TOO_SHORT. A password set before this minimum keeps working until it is changed. Sending the password already set, or removing protection that is not on, changes nothing. Development and transfer stores always stay password protected (password_locked). Password protection and the storefront's mode are separate; change the mode with Change storefront status. The password is never returned. The response has the same shape as Get a storefront (storefront with password_protected, go_live, cache, mode_options). A change sends storefronts/update.

Returns the storefront's primary_locale, the locales it publishes, the enabled store languages it can publish (available_locales) and its country language rules (country_locales). Adding a language to this set does not make it selectable by shoppers: use Set storefront country languages to assign it to active-market countries and choose each default. Without an explicit country assignment only storefront primary is served.

Send the complete list. It must include the storefront's primary language, and every code must be a language enabled for the store (enable it first with Set languages). Codes are matched without regard to case; blanks and repeats are ignored. An unchanged list changes nothing. A change publishes storefront/locales/update. Adding a language to this set does not make it selectable by shoppers: use Set storefront country languages to assign it to active-market countries and choose each default. Without an explicit country assignment only storefront primary is served. Merchant connections also need the online_store.storefronts:write staff permission. Changes return HTTP 409 CONFIRMATION_REQUIRED before committing. Show error.details.warnings and impact, including every country's previous/resulting language codes, default_locale and inherits_primary. language_labels supplies localized display names once per storefront; retired_address_units counts removed country/language pairs and urls.translated_slugs counts affected translated resource slugs. Repeat the identical request only after merchant approval with confirmed=true and confirmation_token. The five-minute single-use token is bound to the reviewed outcome; changed state requires a fresh preview. Success code/message and country/language labels are backend-owned and English on the Store API and localized to the merchant interface language on Admin and MCP. Unpublishing retains translations. Removed-language links resolve the original resource before redirecting to its current exact-language slug in the same served country; invalid countries and deleted resources return 404. A translated slug later taken by another resource belongs to that resource. Query strings are preserved.

The primary storefront's language always follows the store's default language; change that with Set default language. The language must be enabled for the store. Selecting the current primary language changes nothing. Merchant connections also need the online_store.storefronts:write staff permission. Changes return HTTP 409 CONFIRMATION_REQUIRED before committing. Show error.details.warnings and impact, including every country's previous/resulting language codes, default_locale and inherits_primary. language_labels supplies localized display names once per storefront; retired_address_units counts removed country/language pairs and urls.translated_slugs counts affected translated resource slugs. Repeat the identical request only after merchant approval with confirmed=true and confirmation_token. The five-minute single-use token is bound to the reviewed outcome; changed state requires a fresh preview. Success code/message and country/language labels are backend-owned and English on the Store API and localized to the merchant interface language on Admin and MCP. Unpublishing retains translations. Removed-language links resolve the original resource before redirecting to its current exact-language slug in the same served country; invalid countries and deleted resources return 404. A translated slug later taken by another resource belongs to that resource. Query strings are preserved.

Clears the cache of all the store's storefronts, not just one: each page is built again on its next visit, so the first visits after a clear are slower. Saved changes publish on their own; clear the cache only when shoppers still see outdated pages. The cache can be cleared once every 12 hours per store, whoever cleared it last (Store Admin, the mobile app, an app or this API). Read cache in Get a storefront to see whether it can be cleared now. A clear inside the 12 hours is refused with HTTP 429 STOREFRONT_CACHE_CLEAR_TOO_SOON, a Retry-After header and error.details: last_cleared_at, next_available_at and retry_after_seconds; do not retry before next_available_at. Send no body or an empty object. The response reports last_cleared_at, next_available_at, can_clear and cooldown_hours; times are RFC 3339 in the store's timezone with its offset.

Read-only, under read_storefront; apps need no domain or email-settings scopes. Returns one row per country of the storefront's active markets: host (the public host its addresses use; empty when none is available), domain_id (only for a dedicated country domain), currency_code, default_language and default_language_label, language_source (country, or storefront_primary when no language selection is saved for the country), languages (localized labels), mode (shared or dedicated), status (ready or configuration_error), configuration_issues (stable codes), configuration_messages (backend wording for those codes), decisions (backend wording for the row's automatic choices) and addresses (locale, locale_name, url, is_default). A row with configuration issues returns no addresses; a dedicated country whose domain is not connected stays dedicated and is never given shared addresses. address_policy is one backend sentence on what a domain or default-language change does to a country's addresses. address_revision increases whenever any address of the storefront changes: if it changes between page reads, restart at page 1; refresh after storefronts/update and domains/* events. Counts reflect the search; total reflects the selected filter. No DNS records, tokens or connection secrets are returned. Use the returned URLs as they are; do not build addresses in an integration. Address grammar: on the shared host the store's primary country in the storefront's primary language is at the root, another language of that country is /{locale}, and every other country-language pair is /{locale}-{country}; a regional language always names the country, for example /pt-BR-us is Brazilian Portuguese in the US and /pt-br is Portuguese in Brazil. A dedicated country domain serves the country's default language at its root and other languages under /{locale}; changing the country's default language changes the language at that root. An address always selects its own country, whatever the shopper's session or location. Addresses for countries or country-language pairs never served return 404; an address in a language later removed from a country that is still served redirects (301) to the same resource in the language that country now uses, and returns 404 when the resource was deleted or when retained links match more than one resource. Links on a previous country domain that is still connected and assigned redirect to the country's current addresses, keeping the language (when still offered there), path and query.

Active Markets supply countries; each storefront owns its allowed languages and one default. A country without an explicit assignment serves only the storefront primary language. Enabling a store language and adding it to the storefront are prerequisites, not complete shopper publication. address_policy is one backend sentence on what a country default-language (or domain) change does to its addresses; show it before such a change.

mappings maps uppercase country codes to {locales:[...],default_locale:...}. Send null for a country to remove its override and serve only storefront primary. Countries omitted from mappings are unchanged. Languages must already belong to this storefront. Writes are set-wise and atomic; a change publishes storefront/locales/update. Changes return HTTP 409 CONFIRMATION_REQUIRED before committing. Show error.details.warnings and impact, including every country's previous/resulting language codes, default_locale and inherits_primary. language_labels supplies localized display names once per storefront; retired_address_units counts removed country/language pairs and urls.translated_slugs counts affected translated resource slugs. Repeat the identical request only after merchant approval with confirmed=true and confirmation_token. The five-minute single-use token is bound to the reviewed outcome; changed state requires a fresh preview. Success code/message and country/language labels are backend-owned and English on the Store API and localized to the merchant interface language on Admin and MCP. Unpublishing retains translations. Removed-language links resolve the original resource before redirecting to its current exact-language slug in the same served country; invalid countries and deleted resources return 404. A translated slug later taken by another resource belongs to that resource. Query strings are preserved. Merchant connections also need the online_store.storefronts:write staff permission.

Other allowed languages remain available; country_codes must belong to active Markets. Returns updated country count. Publishes storefront/locales/update. Changes return HTTP 409 CONFIRMATION_REQUIRED before committing. Show error.details.warnings and impact, including every country's previous/resulting language codes, default_locale and inherits_primary. language_labels supplies localized display names once per storefront; retired_address_units counts removed country/language pairs and urls.translated_slugs counts affected translated resource slugs. Repeat the identical request only after merchant approval with confirmed=true and confirmation_token. The five-minute single-use token is bound to the reviewed outcome; changed state requires a fresh preview. Success code/message and country/language labels are backend-owned and English on the Store API and localized to the merchant interface language on Admin and MCP. Unpublishing retains translations. Removed-language links resolve the original resource before redirecting to its current exact-language slug in the same served country; invalid countries and deleted resources return 404. A translated slug later taken by another resource belongs to that resource. Query strings are preserved. Merchant connections also need the online_store.storefronts:write staff permission.

The backend resolves current coverage and shows it for approval. Other allowed languages remain available. Returns updated country count. Publishes storefront/locales/update. Changes return HTTP 409 CONFIRMATION_REQUIRED before committing. Show error.details.warnings and impact, including every country's previous/resulting language codes, default_locale and inherits_primary. language_labels supplies localized display names once per storefront; retired_address_units counts removed country/language pairs and urls.translated_slugs counts affected translated resource slugs. Repeat the identical request only after merchant approval with confirmed=true and confirmation_token. The five-minute single-use token is bound to the reviewed outcome; changed state requires a fresh preview. Success code/message and country/language labels are backend-owned and English on the Store API and localized to the merchant interface language on Admin and MCP. Unpublishing retains translations. Removed-language links resolve the original resource before redirecting to its current exact-language slug in the same served country; invalid countries and deleted resources return 404. A translated slug later taken by another resource belongs to that resource. Query strings are preserved. Merchant connections also need the online_store.storefronts:write staff permission.

Suggestions do not override an explicit country/language URL. Manual switching uses currently served country languages.

Send the complete settings. mode is off, suggest_country or manual_selector_only; dismissal_days must be within limits.dismissal_days_min and limits.dismissal_days_max from the read. This does not enable languages, assign countries or redirect shoppers automatically. Returns localized backend success wording. Merchant connections also need the online_store.storefronts:write staff permission.