Guide · Connecting your store

Connecting your store

The app talks to your store through BigCommerce's API, so it needs two things from you: a Store Hash and an Access Token. You create the token yourself inside BigCommerce, which means you decide exactly what the app is allowed to touch — and you can revoke it at any time without involving us.

1. Find your Store Hash

Log in to your BigCommerce control panel and look at the address bar. The URL contains /stores/<hash>/ — that short string is your store hash. It is the part after /stores/ and before the next slash.

2. Create an API account

In your control panel go to Settings → API → Store-level API accounts and create a new account. Give it a name you will recognise later, then set the scopes.

Scope names are the labels BigCommerce shows on that screen; match them by name. Everything listed above needs Modify rather than read-only, because each feature both reads the current state and writes the change — an export alone would work with read-only access.

When you save the account BigCommerce shows the token once and lets you download a text file. Take the Access Token value.

3. Save it in Settings

Open Settings, paste the store hash and the token, then press Test Connection. That makes one harmless read against your store and tells you whether the credentials work before you save them. Then press Save.

• The token is encrypted at rest and never sent back to the browser. After saving, Settings can only show you a masked hint of the last few characters — that is enough to tell which credential is stored, and nothing more.
• Because of that, the Access Token field may be left blank when you come back. Blank means "keep the token you already have". Paste a new one only when you want to replace it.
• The store hash can be changed without re-entering the token.
• One store per account. The sidebar footer shows which store is connected, and a red dot means nothing is.

Checking what the token can actually reach

Test Connection does not just ask whether the token works — it probes one read per feature and lists them individually, because a token can reach some and not others. That is the common mistake: granting Products and leaving Customers at None looks fine until a customer file fails on its first row, in a queued job, hours later.

Disconnecting, rotating, revoking

Three different things, in increasing order of finality:

• Disconnect — the button in Settings. It removes the store hash and the stored token from the app. Nothing here can reach your store afterwards, and your store data is untouched. Use it when you are done, or before handing the account to someone else. The token itself keeps working in BigCommerce, so this is not a substitute for revoking.
• Rotate — create a second API account with the same scopes, paste the new token into Settings, then delete the old account in BigCommerce. Doing it in that order means no import fails in the gap.
• Revoke — happens in BigCommerce, not here. Delete the API account under Settings → API and the token stops working immediately, everywhere, including anywhere else it was pasted.

Installing as an app instead

If you install Ottermerce from your control panel's app marketplace, none of the steps above apply: BigCommerce issues the token itself during the install and the app stores it in the same place a pasted one goes. Settings then shows the store as connected via app install, and there is nothing to copy or paste.

That token has no expiry and no refresh token. It lives until you uninstall the app, which is what revokes it — using Disconnect only drops our copy.

If a read starts failing

When BigCommerce refuses a request the app shows you the upstream message rather than a generic error, because the cause is almost always one of these:

• the token was deleted or regenerated in BigCommerce;
• the scope for that feature is still None — importing customers with only the Products scope granted fails on the first row;
• the store hash is wrong, or belongs to a store that no longer exists.

Test Connection tells you which of those it is: a rejected token fails every feature, a missing scope fails exactly one, and a wrong store hash fails everything without even a permission error.