Platform capabilities
Not every signal Clione generates can be written to every platform on every entity type. Each platform's catalog API has its own quirks — what fields are writable, what types they accept, what's read-only, where JSON-LD lives.
This page documents the capability matrix so you can predict what to expect when you enrich a BC category vs a Shopify page.
Signal-by-signal matrix
| Signal | BC Products | BC Categories | BC Pages | Shopify Products | Shopify Collections | Shopify Pages |
|---|---|---|---|---|---|---|
| meta_title | Yes | Yes | Yes | Yes | Yes | Yes |
| meta_description | Yes | Yes | Yes | Yes (255 char cap) | Yes (255 char cap) | Yes (255 char cap) |
| meta_keywords | Yes (array) | Yes (array) | Yes (string!) | N/A | N/A | N/A |
| search_keywords (BC internal site search) | Yes | Yes | Yes | N/A | N/A | N/A |
| canonical_url | Yes | Read-only via sync | Yes | Yes | Yes | Yes |
| JSON-LD | Yes (Schema Injector) | Planned | Planned | Yes (theme app block) | Planned | Planned |
| OG tags | Yes | Planned | Planned | Yes (metafield) | Planned | Planned |
Quirks you should know about
meta_keywords types differ within the same platform
On BigCommerce:
- Products: array of strings.
- Categories: array of strings.
- Pages: a single string, comma-separated.
Using the wrong type returns a 422 from the platform API. Clione handles this internally, but anyone building a custom integration must respect it.
On Shopify, meta_keywords does not exist as a field. Google has ignored it since 2009, so the absence is not a loss for SEO — but it does mean Clione's bilingual keywords go only into JSON-LD on Shopify, not into a meta tag.
canonical_url shape
On BigCommerce, custom URL is stored as { url: "/path/", is_customized: false } in our metadata. Not as a plain string. After updating mappers to read this, existing entities need a re-sync to populate the new shape — that's the #1 false negative for "canonical URL missing" verifications.
On Shopify, canonical_url is a simple string, but Shopify's storefront renders the canonical from the product's primary URL automatically. Clione's write here is a confirmation, not a creation.
JSON-LD delivery is platform-specific
| Platform | Mechanism | Server-rendered? |
|---|---|---|
| BC Stencil | Schema Injector script tag (registered via BC Scripts API) | No (JS-rendered at runtime) |
| BC Catalyst / headless | @clione/seo SDK or direct API | Yes (you control rendering) |
| Shopify Liquid theme | Theme app extension (Liquid block) | Yes (rendered server-side) |
| Shopify Hydrogen / headless | @clione/seo SDK or direct API | Yes (you control rendering) |
JSON-LD for products works on both platforms. JSON-LD for categories/collections/pages is on the roadmap but not shipped yet on either platform.
Shopify metafield character limit
The single_line_text_field metafield type Shopify uses for meta description caps at 255 characters. Clione may enrich up to 320 characters; on Shopify, the value is truncated at a sentence boundary and Verification flags this as Warn (not Fail).
If you need the full 320 chars on Shopify, the only path today is headless: use the @clione/seo SDK and render Clione's full meta description directly in your head, bypassing the metafield mirror.
OG tags
On BC, OG fields (open_graph_type, open_graph_title, open_graph_description, open_graph_use_meta_description, open_graph_use_product_name, open_graph_use_image) are mapped into platform_metadata.seo and propagated normally.
On Shopify, OG tags are stored in metafields. The theme's <head> Liquid must read them, which the Clione theme app extension handles.
BC store-level data
BC requires the Information & Settings scope on the API token to read store currency and time zone. Without it, JSON-LD may fall back to USD (a real bug we shipped and fixed — task #39). This is documented in Connect BigCommerce.
Webhook handling
BC products have webhook handling for store/product/updated events that triggers a per-product sync. Shopify webhook handling is partial today — sync is mostly pull-based on a schedule.
What's intentionally not yet supported
| Capability | Why not yet |
|---|---|
| Variant-level meta for Shopify | Variants don't have meta fields in Shopify's API. We'd have to render variant JSON-LD as separate Product schemas — planned. |
| Multi-currency JSON-LD | A single product on a multi-region store has different prices per region. Today JSON-LD is written with the store's primary currency. The decision (Offers array vs request-aware) is open — task #40. |
| BC headless metafield mode | The @clione/seo metafield mode works for Shopify but not yet for BC. Planned. |
| FAQ signal full pipeline | The FAQ JSON-LD generator exists (generateFaqJsonLd() in semantic-core), but LLM auto-generation of Q&A pairs + propagation to storefront via per-platform mechanisms is partial. The embed widget renders FAQs and FAQ JSON-LD client-side today, which works for crawlers that execute JS. Full server-side FAQ injection is roadmap. |
Practical guidance
- Enrich everything Clione lets you enrich. Even when a signal isn't fully propagated yet (e.g. JSON-LD on categories), the underlying data is stored and will start propagating the moment we ship the adapter.
- Treat meta description length the same on both platforms — under 255 chars is the safe length. Going longer works on BC (and on Shopify headless) but is truncated in Shopify metafield mode.
- For headless deployments, prefer the API + SDK over the metafield mirror. Fewer surprises, no character limits, easier debugging.
- Run Verification after every bulk enrich. A green Verify is the only ground truth that the live storefront has the new signals.
See also:
- Signal propagation — what happens between Enrich and the live storefront.
- Verification — how to confirm signals landed.
- Schema Injector — the BC + Shopify JSON-LD delivery mechanisms in detail.