Skip to main content

Create a BigCommerce API account for 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 is the BigCommerce half of connecting a store: the API account you create inside your own store, the exact scope levels, and the Schema Injector. For the whole path end to end, including the Clione side, start at Connect your BigCommerce store and come back here for the token.

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. Three scopes are required and three are optional, one per feature — Step 3 below is the only place that says which, and at what level. If you also grant the optional Orders — Read-only scope and you are on Pro or Agency, it reads your orders from the last 30 days, once a day, for Attribution. On Starter and Growth no order is read, even with the scope granted. BigCommerce sends the whole order, including the buyer's contact details; Clione keeps only the order-level fields and line items, and never stores a customer's name, email, phone, address, customer account or payment information. Order data is kept for 13 months from the order date, then deleted automatically.

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. Three more are optional, and each one switches on exactly one feature. Everything else stays at None.

The three required scopes​

ScopeRequired levelWhy Clione needs it
ProductsModifyRead products, categories, brands, variants, options and their price lists (that is where B2B and multi-currency prices live). 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.

The three optional scopes​

Leave one at None and that feature is simply off. Nothing else breaks, and Clione tells you in the dashboard when a feature is waiting on a scope.

ScopeLevelWhat it switches onIf you leave it at None
OrdersRead-onlyAttribution on Pro and Agency: Clione reads your orders to compare AI-referred and enriched sales with the rest. It is also how Clione confirms that a coupon handed to an AI agent was actually redeemed. On Starter and Growth no order is read even with the scope granted.Clione reads no orders on any plan.
Channel SettingsRead-onlyLets Clione read your channel list and tell a Stencil storefront from a headless one before it installs the Schema Injector.The install assumes Stencil, which is correct for the large majority of stores. If yours is headless, use the @clione/seo SDK instead.
MarketingModifyAI offers only: Clione creates the coupon promotion and its code in your store through BigCommerce's Promotions API, and deletes them again when the offer ends. BigCommerce requires Modify here — its Marketing — Read-only level does not cover the Promotions API.Clione creates no promotion and hands out no coupon code. Every other feature is unaffected.

Nothing else needs a scope row. Webhooks — how Clione hears about a product you edited in BigCommerce — run on BigCommerce's default scope, which every API account carries, so there is nothing to enable for them.

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 Listings, Storefront API Tokens
  • Payments

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.

Get the scopes right now — they cannot be changed later

BigCommerce's own documentation is explicit: "You can't change store-level access tokens or OAuth scopes." There is no screen that raises a level on an API account that already exists. Fixing a wrong scope means creating a new API Account with the right scopes (Steps 1–4 again), pasting its token into Clione under Store Settings → Credentials, and then deleting the old account. Two minutes of work — but it is a new token, not an edit.


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. A store API account's scopes cannot be changed, so create a new API Account (Steps 1–4) with Products at Modify, paste its token under Store Settings → Credentials, then delete the old account.

403 Forbidden only when Clione writes — Products or Content is at Read-only. Same fix: a new API Account with that scope at Modify, its token pasted into Clione, then delete the old one. There is no way to raise the level in place.

403 Forbidden on the Promotions API — Marketing is at None, or at Read-only, which BigCommerce does not accept for Promotions. Only AI offers need it; everything else 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 — Content must be at Modify. If it is, click Install again. A missing Channel Settings scope never blocks the install: Clione falls back to assuming Stencil.

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.