Docs navigation
Home / Docs / SEO metadata

SEO metadata

Meta titles and descriptions on products, categories, and brands — with smart fallbacks, per-channel overrides, and explicit push to external platforms.

Products, categories, and brands each carry a metaTitle and metaDescription. Foundry serves them to storefronts, lets you override them per channel, and can push them to external platforms that support it.

Fallbacks are resolved, not stored

Leave a meta field blank and Foundry derives one:

FieldFalls back to
metaTitleThe record’s name
metaDescriptionAn excerpt of its description

The important part: fallbacks are resolved at read time and never written into the record. A blank metaTitle stays blank in the database.

That’s what makes renaming safe. Rename a category and its derived title updates everywhere automatically. Had the fallback been materialized on create, you’d be hunting stale titles for years — and you’d never be able to tell an author-written title from a generated one.

The practical consequence: only fill these in when you have something better than the fallback. A metaTitle identical to the name is worse than blank, because it’s now frozen.

Per-channel overrides

The same product can present different metadata on different storefronts. A channel SEO override sets metaTitle, metaDescription, and slug for one entity on one channel.

Resolution order for a given channel:

  1. Channel override, if one exists
  2. The base field on the record
  3. The computed fallback

Use overrides where the audience genuinely differs — a trade storefront and a consumer one want different language for the same part. Don’t use them to work around a base value that’s simply wrong; fix the base.

Overrides also cover slug, so a product can live at different URLs on different storefronts without duplicating the catalog record.

Channel support

Not every platform accepts SEO metadata, so each channel adapter declares whether it supports it:

ChannelSEO push
BigCommerceYes
ShopifyYes
MedusaYes
ThrottleYes
Headless (Storefront API)Yes
WooCommerceNo

WooCommerce is the exception. Core WooCommerce has no native SEO fields — they come from a plugin like Yoast or Rank Math, each with its own storage. Rather than guess which one you run and write to its meta keys, Foundry doesn’t push. Manage SEO in your plugin, or read the values from the Storefront API and render them yourself.

Pushing is explicit

SEO metadata is not pushed on every listing update. It goes out when you explicitly ask for it.

This is deliberate. Merchants commonly hand-tune metadata on the platform itself, and a background sync that silently overwrote that work would destroy hours of effort with no signal. Making the push explicit means the overwrite is always someone’s decision.

If you want Foundry to be the source of truth for metadata, push after edits. If you want the platform to own it, never push, and Foundry’s values just serve your headless surfaces.

Headless storefronts

For channels served by the Storefront API, metadata comes back on the product, category, and brand payloads with overrides and fallbacks already resolved. Your frontend renders what it’s given — no fallback logic to reimplement, and it stays correct when someone edits a name in the admin.

Category and brand pages are where this pays off. A category with two rich descriptions plus resolved metadata is a landing page that can rank, rather than a bare product grid.

Practical notes

Length. Search engines truncate around 60 characters for titles and 155–160 for descriptions. Foundry doesn’t enforce a limit — that’s a moving target set by search engines, not a data constraint — but write to those numbers.

Don’t template everything. {Product Name} | {Brand} | Buy Online across 5,000 products produces 5,000 near-identical titles, which is worse than the plain fallback. Hand-write metadata for the pages that matter: top categories, brand pages, best sellers.

Changing slugs breaks links. A slug change changes the URL. Foundry doesn’t manage your storefront’s routing, so set up redirects on the frontend before changing slugs on indexed pages.