BigCommerce AI Agents: API Accounts, Webhooks, and Writes (2026)
Quick summary: Call the REST Management API with X-Auth-Token and a store hash. Webhook destinations must be port 443. One API account should not hold both read-orders and modify-orders for a week-one agent.
Key Takeaways
- Call the REST Management API with X-Auth-Token and a store hash
- Webhook destinations must be port 443
- One API account should not hold both read-orders and modify-orders for a week-one agent
- On 25 September 2026, a BigCommerce agent is an API account plus a few REST reads
- Our take: one API account, read scopes, webhooks you created at deploy
Table of Contents
On 25 September 2026, a BigCommerce agent is an API account plus a few REST reads. It is not a staff user in the control panel and not a native AgentCore app. Shared rules for ERP and WMS sit in the integration post.
Who this is for. An engineer wiring AgentCore or another runtime to a BigCommerce store. The support workflow those tools should serve is the customer support agent.
Our take: one API account, read scopes, webhooks you created at deploy. Modify-orders is a second account you do not create in week one.
The token
BigCommerce’s API accounts guide says most REST and GraphQL Admin calls authenticate with X-Auth-Token set to the account’s access token. The store hash is in the path: https://api.bigcommerce.com/stores/{store_hash}/....
Create an account for the agent. Record the scopes you tick. Typical week-one reads are orders, products, and inventory — use the scope names in the current guide, not a screenshot from 2023. Do not also tick modify. If a scope is modify-only, leave it off.
Some resources are visible only to the account that created them (webhooks, metafields, scripts). If you later revoke the agent account, those subscriptions go with it. That is a reason to keep webhook ownership on a deploy-time account you understand, and to keep the model off the create-webhook API.
The B2B API is a different product: host https://api-b2b.bigcommerce.com, plus X-Store-Hash. Do not point storefront tools at it.
Webhooks
Create webhook is POST /stores/{store_hash}/v2/hooks with scope, destination, and is_active. Constraints that are easy to miss:
- One webhook per request
- Destination URL on port 443, returns 200, custom ports unsupported
- Optional headers for the receiver to validate the call
- Managing hooks uses the API account’s default scope
Verify the payload with the secret or header you configured. Treat a repeated delivery as normal. Your handler keys off the event id and does not double-apply.
Use the event to refresh a cache the getOrder tool reads. The model never sees the raw webhook body as a tool argument from the internet.
Tools
| Tool | Calls | Week one |
|---|---|---|
getOrder | Orders REST, fixed fields | Yes |
getShipment | Shipments for that order | Yes |
getVariantInventory | The inventory endpoint you enabled | Yes, include a timestamp |
createRefund | Not exposed | No |
createHook | Not exposed | No |
Rate limits are yours to surface. On 429, stop the turn with a busy message. Do not ask the model to try the B2B host instead.
Idempotency matters the day you allow a write. Store your key. BigCommerce will not invent one for a retry the model made up.
What broke — A tool builder passed through any path under
/v3/if the model supplied it. A test prompt requested a POST to a refund route the token still allowed from an older scope set. Detection: the trace showed a path the allow-list did not name. Fix: delete path-passthrough; rotate the token; reissue read-only. Lesson: an HTTP client is not a tool catalog.
If you only do one thing
In the API account UI, read the scope list out loud. Modify scopes mean you are not in week one.
What to do this week
- Create a dedicated API account. Store the token in a secret manager the model cannot read.
- Implement two GET tools with explicit fields.
- Register one order webhook on 443 and replay it.
- Confirm you are not calling
api-b2bby accident. - Read Shopify only as a contrast in token style.
- Discuss the architecture. The engagement is eCommerce AI agents. Pricing shape for the runtime is the AgentCore calculator.
What this post doesn’t cover
- Stencil theme code.
- A published BigCommerce marketplace app from FactualMinds. There isn’t one.
- Multi-storefront channel quirks beyond “pass the channel you mean.” Verify against the current REST reference before you assume a field exists.
AWS Cloud Architect & AI Expert
AWS-certified cloud architect and AI expert with deep expertise in cloud migrations, cost optimization, and generative AI on AWS.
