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.

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 guide gives Clione the access it needs to read your BigCommerce catalog, enrich it, publish the optimized signals back, and install the Schema Injector on your storefront. Every UI path is spelled out, every field name is what you'll see in the BigCommerce admin, and every scope is explained.

Clione reads your product catalog (stock levels included), your content pages and a small set of read-only settings. If you also grant the optional Orders — Read-only scope, it reads your orders for Attribution (Pro and Agency). Clione never sees customer accounts or payment information.

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

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

Clione connects to BigCommerce through a Store API Account you create 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 BigCommerce admin and every Clione request to your store is refused.

Step 1 — Open the API Accounts panel​

  1. Log in to your BigCommerce store admin. The store hash is the alphanumeric segment in your admin URL (store-<hash>.mybigcommerce.com) — you'll need it in Step 5.
  2. From the left sidebar, click Settings.
  3. Scroll to the API section and click API Accounts.
  4. Click Create API Account → choose V2/V3 API token (not Stencil-CLI Token).

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.

Step 3 — Set the scopes​

Clione needs three scopes, plus one optional scope for Attribution. The rest must stay at None.

ScopeRequired levelWhy Clione needs it
ProductsModifyRead products, categories, brands, variants and options. Write the meta title, meta description and meta keywords back, and the search keywords of categories (products never get search keywords). Read-only is not enough.
ContentModifyRead and update content pages (About, Shipping, custom pages), write the structured-data widgets through BigCommerce's Widget API, and install or remove the Schema Injector script through BigCommerce's Scripts API.
Information & SettingsRead-onlyRead your store name and storefront domain. Clione never writes here.
Orders (optional)Read-onlyOnly for Attribution (Pro and Agency): read your orders to compare AI-referred and enriched sales with the rest. Leave it at None if you don't use Attribution.

Scopes you must NOT enable​

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

  • Customers, Customer logins
  • Order Transactions
  • Carts, Checkout content, Shipping
  • Themes, Sites & Routes, Channel Settings, Storefront API Tokens
  • Payments, Marketing, Promotions

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

BigCommerce's scope levels are nested — Modify implies Read-only. If you pick Read-only for Products or Content, sync works but publishing, the Schema Injector install and any other write fail with 403 Forbidden. Come back here, change the level and Save — the existing token keeps working, so there's nothing 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 dialog with your new credentials and offers a .txt file download.
  3. Download the .txt file and store it safely. BigCommerce never shows these credentials again. If you lose them, delete this API account and create a new one.

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 the store hash in the API Path matter for Clione. Confirm the hash matches the one in your admin URL — if you have several BigCommerce stores and copied the wrong one, the connection fails 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. Click + Add Store. The wizard opens with three steps: Platform, Details, Connect.
  3. Platform — click the BigCommerce card.
  4. Details:
    • Store Name — anything that helps you recognize it in the dashboard.
    • Store Hash — the alphanumeric hash from the API Path (e.g. abc123xyz). No store- prefix, no trailing slash.
    • Storefront URL — the public URL your shoppers visit. If you use a custom domain, paste it (https://shop.example.com); otherwise the mybigcommerce.com URL. Use the root domain only, never the api.bigcommerce.com URL. This is where Clione verifies your signals.
    • Currency — the same primary currency your BigCommerce store uses.
  5. Click Next.
  6. Connect — paste the Access Token from the .txt file into API Access Token. You can also skip this and add the token later from Store Settings → Credentials.
  7. Click Create & Connect.

If your plan's store limit is already reached, the wizard tells you and offers Upgrade plan or the add-on that connects one more store.

Step 6 — Install the Schema Injector​

Two separate things reach your BigCommerce storefront, and it helps to know which does what:

  • JSON-LD (structured data). When you publish an entity, Clione installs a BigCommerce Widget API placement for it. Stencil renders it into the HTML server-side, so crawlers that run no JavaScript see it on the first fetch. You don't install anything for this — publishing does it.
  • The Schema Injector script. A small script, named "Clione FAQ Renderer" in BigCommerce's Script Manager, that renders the visible FAQ accordion on your pages, applies your FAQ CSS and adds two discovery <link> tags for AI agents (llms-txt and agents-json). It emits no JSON-LD.

Install it (Stencil)​

  1. Open the store in Clione → Store Settings → Schema Injector tab.
  2. Click Install.

What Clione does when you click it:

  1. Checks your storefront for a Clione embed you added by hand. If it finds one, it stops and shows Manual Clione embed detected with Dismiss and Install anyway (force).
  2. Reads your BigCommerce channels to tell whether you're on Stencil, headless or both. A headless-only store gets the @clione/seo setup instead and nothing is installed. A store with Stencil plus a headless channel gets the script on Stencil and a note that the headless storefront needs @clione/seo.
  3. Generates a read-only API key for this storefront, restricted to your storefront's hostname. You don't paste anything.
  4. Registers the script through BigCommerce's Scripts API with location: head, load_method: async (it never blocks your page from rendering), visibility: storefront and consent_category: essential. The script loads from https://api.clione.ai/api/v1/public/embed/schema-injector/<your-store-id>.js.

The tab then shows Installed with the script's UUID, location, load method and visibility. Refresh status re-reads it.

If your storefront is headless (Catalyst, Next.js or any custom frontend), the Scripts API doesn't reach it: use the @clione/seo SDK instead.

Verify it​

  1. Open a published product page in an incognito window and view the source (Ctrl/Cmd + U).
  2. Search for data-clione="schema-graph". You should find a <script type="application/ld+json"> block with the @graph — Organization, WebSite, BreadcrumbList, Product, and FAQPage when the product has approved FAQs. If it is absent, that entity hasn't been published yet.
  3. Optionally, click Preview JSON-LD on the Schema Injector tab to see the store's JSON-LD without leaving the dashboard.

Uninstall​

Click Uninstall on the Schema Injector tab and confirm. Clione revokes the script's API key and removes the script from your store. Always uninstall from here rather than deleting the script in Script Manager, so Clione's records stay in sync.

See the Schema Injector reference for more detail.

Sanity check (optional)​

To check the token before pasting it into Clione, run this in a terminal (replace the two placeholders):

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. {"status":401,...} means the token was copied wrong — copy it again from the .txt file with no leading or trailing whitespace. {"status":404,...} means the store hash doesn't match the token.

Troubleshooting​

401 Unauthorized — The Access Token was copied wrong, or the API Account was deleted on the BigCommerce side. Copy the Access Token again exactly — no spaces, no quotes — and paste it under Store Settings → Credentials.

403 Forbidden when Clione reads products — Products scope is at None. In BigCommerce admin → Settings → API Accounts, edit the Clione account, set Products to Modify and save.

403 Forbidden only when Clione writes — Products or Content is at Read-only. Raise it to Modify and save. The existing token keeps working.

404 Not Found — The Store Hash doesn't match the store. Check the API Path in the .txt file against your admin URL.

The Schema Injector install fails — Check that Content is at Modify, then click Install again.

No JSON-LD in page source — The entity hasn't been published yet. Open its Publish tab and publish it. See Publish.

Verification can't reach a sandbox or password-protected store — On the entity's Publish tab, enter your BigCommerce Preview Code (BigCommerce admin → Storefront → My Themes → Advanced on your active theme → copy the Preview Code). See Verify signals.

Sync runs but some products are missing — Some products may be hidden or in an inactive channel. Compare like with like in BigCommerce's product listing.

429 Too Many Requests — BigCommerce rate-limits per token and Clione backs off automatically. If you see this repeatedly, another integration is probably sharing the same API Account — create a separate API Account for Clione.

Revoking access​

  1. In Clione, uninstall the Schema Injector first (Store Settings → Schema Injector → Uninstall). Once the API Account is gone, Clione can no longer remove the script for you.
  2. BigCommerce admin → Settings → API Accounts.
  3. Find the Clione account → three-dot menu → Delete.

From then on every Clione request to your store is refused. If you skipped step 1, remove the Clione FAQ Renderer script by hand in Storefront → Script Manager.

To also delete the store and its enriched data from Clione, use Remove Store on the Danger Zone tab of Store Settings. See Store settings — Danger zone.

What happens next​

  1. First sync. Clione pulls your products, categories and pages. See Sync your catalog.
  2. First enrichment. Enrichment always asks for confirmation before it spends credits — sync never enriches on its own. See Enrich your catalog.
  3. Publish. Enrichment writes nothing to your storefront. Publishing does: see Publish.
  4. Verify. On Growth and above, open Verification in the store sidebar to confirm the live storefront matches Clione. See Verify signals.

See Platform capabilities for the full per-signal matrix.