Skip to main content

Connect your BigCommerce store to Clione

Plans: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓

Time required: ~5–10 minutes (including the Schema Injector step if you're on Stencil).

You need: access to your BigCommerce admin as the store owner, OR as a user with the "Manage API Accounts" permission. If you don't see Settings → API Accounts in the admin sidebar, your user is missing that permission — ask the owner to add it via Settings → Users → [your name] → Permissions.

This is the end-to-end guide to giving Clione the access it needs to read your BigCommerce catalog, enrich it, propagate the optimized signals back, and install the JSON-LD Schema Injector on your storefront. It is written for non-technical merchants — every UI path is spelled out, every field name is what you'll actually see in BC admin, and every scope is explained.

Clione never sees customer data, orders, payment information, fulfillment data, inventory, or any PII. The scopes below grant access only to your product catalog, content pages, and a small set of read-only settings.

If you're connecting Shopify instead, see Connect Shopify.

Why a Store API Account and not the public app?​

Clione does not use BigCommerce OAuth or the public App Marketplace flow. Instead, you create a Store API Account inside your own store. Three concrete advantages:

  • Instant. No app-review queue, no approval wait.
  • Scoped narrowly. You grant exactly the scopes Clione needs (Step 3) — nothing more.
  • Revocable in one click. Delete the API Account from your BC admin and every Clione request to your store returns 401 within seconds.

The trade-off is one extra setup step. The rest of this guide is that step, spelled out exactly.

Step 1 — Open the API Accounts panel​

  1. Log in to your BigCommerce store admin: https://store-<your-hash>.mybigcommerce.com. (The "store hash" is the alphanumeric segment in your admin URL — copy it now, you'll need it in Step 5.)
  2. From the left sidebar, click Settings.
  3. Scroll the Settings page until you find the API section.
  4. Click API Accounts.
  5. Click Create API Account (top right) → choose V2/V3 API token.
    • (screenshot: BigCommerce admin → Settings → API → API Accounts → Create API Account dropdown)
    • You'll see two options: V2/V3 API token (this one) and Stencil-CLI Token. Pick V2/V3.

Step 2 — Name the account​

FieldValue
NameClione AI (any name works; this label is shown in the API Accounts list and in your audit trail).
OAuth scopesSet in Step 3 below.

Leave everything else at defaults. The name is for your own audit trail — pick something that lets you tell it apart from any other API account later (e.g. Clione AI — production).

Step 3 — Set the scopes​

Clione needs three scopes. The rest must stay at None.

ScopeRequired levelWhy Clione needs it
ProductsModifyRead all products, categories, brands, variants, and product options. Write the new meta_title (page_title), meta_description, meta_keywords, search_keywords, custom_url (canonical), and the structured-data widget configuration back. Modify covers both read and write — Read-only is not enough.
ContentModifyRead and update content pages (About, Shipping, custom pages). Install and remove the Schema Injector managed script via BC's Content > Scripts API. Without Modify the Schema Injector card in Settings will say "Cannot install — Content scope missing".
Information & SettingsRead-onlyRead store name, currency, time zone, channels. Needed for currency-aware JSON-LD (priceCurrency), the multi-channel detection used by the Schema Injector to detect headless storefronts (Catalyst, Next.js, custom), and the /v2/store lookup that fixes the storefront URL automatically. Clione never writes here.

Scopes you must NOT enable​

Granting these would expose data Clione never reads. Leave them at None:

  • Customers, Customer logins
  • Orders, Order Transactions
  • Carts, Checkout content, Shipping
  • Themes, Sites & Routes, Channel Settings, Storefront API Tokens
  • Payments, Marketing, Promotions (Promotions will be added in a future module with its own scope; today Clione does not use it.)

What "Modify" vs "Read-only" means in BC​

BigCommerce's scope levels are nested — Modify implies Read-only. There is no separate "Write" level. If you accidentally pick Read-only for Products or Content, sync will work but propagation, Schema Injector install, and any write operation will fail with 403 Forbidden. You'll then have to come back here, change the level, and Save — BC issues a new behavior, but the existing token is reused (no need to re-paste in Clione).

Step 4 — Save and download the credentials​

  1. Click Save at the top right.
  2. BigCommerce shows a one-time confirmation dialog with your new credentials and offers a .txt file download.
  3. Download the .txt file and store it safely. BigCommerce will never show these credentials again. If you lose them, you must delete this API account and create a new one from scratch.

The file contains four values:

Client ID:       <something like p9z4x...>          ← not used by Clione
Client Secret:   <long random string>               ← not used by Clione
Access Token:    <long random string — this is what Clione needs>
API Path:        https://api.bigcommerce.com/stores/<YOUR_STORE_HASH>/v3/

Only the Access Token and API Path matter for Clione. The Client ID and Client Secret are only used if you wanted to mint additional OAuth tokens later — Clione doesn't need them.

The store hash in the API Path is the same hash from your admin URL (Step 1). Confirm they match — if you have multiple stores on BC and copied the wrong one, the integration will fail later with 404 Not Found.

Step 5 — Add the store in the Clione dashboard​

  1. Log in to your Clione dashboard at app.clione.ai.
  2. From the left sidebar, click + Add Store (or open /stores/new directly). The 3-step wizard opens.
  3. Step 1 — Pick the platform: click the BigCommerce card.
  4. Step 2 — Store details:
    • Store name — anything that helps you recognize it in the sidebar (e.g. EgoShoes US).
    • Store Hash — paste the alphanumeric hash from Step 4 (the segment in the API Path, e.g. abc123xyz). No leading store- prefix, no trailing slash.
    • Storefront URL — the public URL your shoppers see. If you use a custom domain, paste it (https://shop.example.com). If you don't, paste the mybigcommerce.com URL (https://store-abc123xyz.mybigcommerce.com). Trailing slashes are stripped automatically. This URL is what Clione fetches during Verification and is the canonical reference for the Schema Injector's allowed-domain whitelist.
    • Currency — the same currency your BC store uses. Clione re-reads this on every sync via /v2/store (Information & Settings scope), but the value you enter here is the fallback if that read fails.
  5. Click Next.
  6. Step 3 — Credentials: paste the Access Token (from the .txt file) into the BigCommerce Access Token field.
  7. Click Create and Connect.

Within seconds the store appears in your sidebar. Open it to see the store overview. The Schema Injector card (covered below) shows the install status.

If you skip the Storefront URL field, Clione defaults to https://store-<hash>.mybigcommerce.com — fine for a sandbox, but if your real shoppers see a different domain you should set it now. Verification and the Schema Injector's domain whitelist both depend on this value being correct.

Step 6 — Install the Schema Injector (required for JSON-LD on Stencil storefronts)​

If your storefront runs on BigCommerce Stencil (the classic hosted theme — most stores), the Schema Injector is what puts Clione's enriched JSON-LD into your live storefront's <head>. Without it, the enriched data lives in Clione's DB but never reaches crawlers.

If your storefront is headless / Catalyst (Next.js storefront built separately), the Schema Injector doesn't apply — use the @clione/seo SDK instead. The Schema Injector card auto-detects this via the BigCommerce /v3/channels API and surfaces the right guidance.

One-click install (Stencil)​

  1. Open the store in Clione → Settings.
  2. Scroll to the Schema Injector card.
  3. Click Install Schema Injector.

What happens behind the scenes:

  1. Clione calls /v3/channels to detect whether you're on Stencil, headless, or mixed. Headless-only stores get a "use @clione/seo instead" panel and the install is skipped. Mixed stores (Stencil + a Next.js channel) install on Stencil and show a warning that the headless channel still needs the SDK.
  2. Clione probes your storefront homepage for an existing Clione embed (embed.clione.ai, data-clione-embed attribute, etc.). If a manual embed is already present, the install asks whether to coexist or replace — duplicate JSON-LD is penalized by search engines, so this preflight is intentional.
  3. Clione provisions an internal API key server-side (you don't paste anything). The key has scope products:read and is whitelisted to your store's storefront domain only.
  4. Clione calls BC's /v3/content/scripts API to register a script tag named "Clione Schema Injector" with:
    • location: head (renders in the <head> of every storefront page).
    • load_method: default (synchronous; runs before DOMContentLoaded).
    • visibility: storefront (every storefront page, not the admin).
    • consent_category: essential (not subject to cookie-banner gating).
    • kind: src with src pointing at https://api.clione.ai/api/v1/public/embed/schema-injector/<your-store-id>.js.
  5. BigCommerce starts serving that script tag on every page within seconds.

The script's job at runtime is to detect the current page context (product / category / page) from URL patterns plus the BC product_id hidden input, then fetch the enriched JSON-LD from Clione and inject it into <head> as <script type="application/ld+json" data-clione="injector">. Crawlers that execute JavaScript (Google, Bing modern, GPTBot, ClaudeBot, PerplexityBot) see the injected JSON-LD on the next page load. For curl-style crawlers that don't run JS, see Stencil — non-JS crawlers.

Verify the install​

  1. Open any enriched product page in an incognito window.
  2. View source (Ctrl/Cmd + U).
  3. Search for data-clione="injector". You should find a <script type="application/ld+json"> block with the enriched Product schema, including keywords, description, and (if reviews are enabled) aggregateRating.
  4. Optionally, open the Schema Injector card → Preview JSON-LD to see exactly what Clione would inject without leaving the dashboard.

Uninstall​

Click Uninstall on the card. Clione revokes the internal API key first, then calls BC's /v3/content/scripts/:uuid DELETE. The card returns to "Not installed" and the storefront stops serving Clione JSON-LD on the next page load.

If you've been on the dashboard for a while and the card still says "Not installed" right after a successful install, hard-refresh — the status endpoint is no-store and should be fresh, but rare browser caching layers (corporate proxies, service workers) can hold a stale response.

See the full Schema Injector reference for headless flows, the JSON-LD preview, and per-platform troubleshooting.

Sanity check (optional)​

If you want to verify the token works before pasting it into Clione, run this in any terminal (replace the two placeholders with your real values):

curl -s -H "X-Auth-Token: <ACCESS_TOKEN>" \
  "https://api.bigcommerce.com/stores/<STORE_HASH>/v3/catalog/products?limit=1"

Expected: a JSON response with one of your products. If you see {"status":401,...}, the token was copied wrong — re-open the .txt file from Step 4 and copy again with no leading/trailing whitespace. If you see {"status":404,...}, the store hash doesn't match the token.

Troubleshooting (BigCommerce-specific)​

401 Unauthorized — The Access Token was copied wrong, or the API Account was deleted/rotated on the BC side. Re-open the .txt file from Step 4 and copy the Access Token value exactly. No leading/trailing spaces, no quotes. Then re-paste under Store → Settings → Credentials in Clione. (The store hash is stored separately — saving only the token does not wipe the hash.)

403 Forbidden when Clione tries to read products — Products scope is at None. Open BC admin → Settings → API Accounts → edit the Clione AI account → set Products to Modify → Save.

403 Forbidden only when Clione tries to write metadata — Products scope is at Read-only. Bump it to Modify and save. The existing token is reused; no need to re-paste in Clione.

404 Not Found — The Store Hash doesn't match the actual store. Open the .txt from Step 4 and verify the API Path segment matches your admin URL. If you have multiple BC stores, you may have grabbed the wrong account.

Schema Injector says "Cannot install — Content scope missing" — Content scope is at Read-only or None. Set it to Modify in BC admin and click Install again.

Schema Injector install returns 422 invalid field [html] — Historical bug, fixed in the current implementation (uses kind=src instead of inline HTML). If you see this on a fresh install, your tenant may be pinned to an old release — open a support ticket.

Schema Injector installs but JSON-LD does not appear in page source — Two common causes:

  1. You're looking at a page where the JS hasn't run yet. The injection happens after the bootstrap's async fetch completes, so it lands shortly after the initial HTML. Hard refresh (Ctrl/Cmd + Shift + R) and check again. JS-capable crawlers wait for JS to settle, so this is not a crawler-visibility problem — only a "view-source-before-JS" optical issue.
  2. The page was loaded with a robots cache between you and your storefront (e.g. a corporate proxy stripping scripts). Try from a different network.

Currency in JSON-LD reverts to USD — Information & Settings scope is missing or None. The /v2/store endpoint that returns the store currency requires this scope. Set it to Read-only in BC admin and re-sync.

Custom URL (canonical) shows product-not-found-{id} on Verification — Stale platform_metadata from an older sync. Clione's BC propagation adapter falls back to a fresh getProduct() call to recover the URL — re-sync the product (open the product detail → Refresh from platform) and the canonical URL will appear correctly on the next verify.

Verification fails on a sandbox / password-protected store — Pass a preview code. Open the failing entity in Verification → the detail panel has a banner with "Storefront unreachable — looks like password-protected"; paste the preview code from BC admin → Settings → Storefront → Sandbox and click Retry verification. See Verify signals — BigCommerce for details.

Sync runs but only some products appear — Some products may be is_visible: false or in an inactive channel. Clione syncs everything the API returns; if your admin filter is "Visible only" the counts will differ. Compare like-with-like in BC's product listing.

429 Too Many Requests — BC's REST API rate-limits at 20 req/s per token for V2/V3. Clione has automatic backoff. If you see this repeatedly, you likely have a parallel integration on the same API Account — create a separate API Account for Clione to avoid contention.

Revoking access​

If you need to revoke Clione's access:

  1. BC admin → Settings → API Accounts.
  2. Find the Clione AI account.
  3. Click the three-dot menu → Delete.

Within seconds, every Clione request to your store returns 401 and the store stops appearing as healthy in the Clione dashboard.

If you also want to remove the Schema Injector script tag manually, you'd do that from Storefront → Script Manager, but this is usually unnecessary — when the API Account is deleted, the script is still there but Clione can no longer fetch JSON-LD for it (the bootstrap returns nothing on 401). The script becomes a no-op; you can clean it up at your leisure.

If you also want to delete the store and its enriched data from Clione, use Danger zone → Schedule deletion in Store → Settings in the Clione dashboard. See Store settings — Danger zone.

What's different on BigCommerce vs Shopify​

Quick reference if you're connecting your second platform:

AspectBigCommerceShopify
Token typeAccess Token + Store Hash from a V2/V3 API Account.Single shpat_ Admin API access token.
Where the token is createdSettings → API → API Accounts → Create API Account.Settings → Apps and sales channels → Develop apps → Create an app.
JSON-LD on the storefrontSchema Injector (script tag injected via BC Scripts API).Theme app embed (server-side Liquid block enabled in theme editor).
Variant modelProduct Options + generated SKUs (variants derived).First-class variants (each variant a separate SKU with own price/options).
Category equivalentCategories (tree-structured, parent IDs).Collections (manual + smart, rule-based).
Multi-currencyChannels + per-channel currencies.Markets + per-market prices.
Native reviewsSettings → Channels → Customer Reviews (built-in).Third-party only (Judge.me / Yotpo / Loox / Stamped).
Meta description max65535 chars (no practical limit).255 chars (metafield type limit; Clione truncates).
Sync speed per 1k entities30–60s (REST v3, 20 req/s).60–120s (GraphQL cost-based throttle).

See Platform capabilities for the full per-signal matrix.

What happens after Clione has the token​

  1. First sync (1–10 minutes depending on catalog size). Clione pulls your products, categories, and pages. Watch progress in the top-bar chip or under Sync in the store sidebar. See Sync your catalog.
  2. First enrichment. Pick a small batch from any listing and click Bulk enrich. Clione always asks for confirmation before spending enrichment credits — there is no auto-enrich on sync. See Enrich your catalog.
  3. Auto-propagation. As soon as the enrichment completes, signals are written back via BC's REST API in the background. You don't click anything for this. The Schema Injector script picks up the new JSON-LD on the next storefront page load — no separate "push" step.
  4. Verification. Open Verification in the store sidebar to confirm that what's in Clione matches what's on the live storefront. See Verify signals — BigCommerce.

Every write is logged with before/after values under each entity's Propagation tab. If a write was rejected by BC (e.g. malformed custom_url, too-long field), the propagation record shows the raw API response so you can diagnose it.