A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The BigCommerce API is how an app or AI agent works with an online store: listing and creating products, reading and updating orders, managing customers, and building carts and checkouts. Access is granted through a store access token carrying a set of OAuth scopes, where most areas offer a modify scope and a read-only scope, and the token reaches only the store and scopes it was issued for. A state change can push an event to a registered webhook, and BigCommerce also ships a first-party server that exposes storefront shopping tools to agents.
How an app or AI agent connects to BigCommerce determines what it can reach. There is a route for making calls, a route for receiving events, and a first-party server that exposes storefront shopping tools to agents, and each is governed by the token behind it and the OAuth scopes that token carries.
The REST API answers at https://api.bigcommerce.com/stores/{store_hash}, with each store identified by its store hash in the path. The newer V3 endpoints cover the catalog, customers, carts, checkouts, price lists, and webhooks; the older V2 endpoints still serve areas like orders. A call authenticates with a store API account access token sent in the X-Auth-Token header.
BigCommerce POSTs an event to a registered callback URL when a subscribed event fires, such as store/order/created or store/product/updated. The receiver verifies the request, and BigCommerce retries deliveries that do not return a fast 2xx response.
BigCommerce's first-party Storefront MCP server exposes guest shopping tools to an AI agent over the Model Context Protocol: searching the product catalog, reading product details and variants, building and managing a cart, and generating a checkout URL. It reached general availability in May 2026 and is enabled per store from Settings then Early Access in the control panel. Authenticated B2B shopping is on the roadmap.
A store API account issues a long-lived access token scoped to a set of OAuth scopes chosen when the account is created. The token is sent in the X-Auth-Token header, and the store is identified by its store hash in the request path. This is the standard way a backend integration authenticates to a single store.
A published BigCommerce app uses the OAuth flow: the merchant installs the app, BigCommerce returns an authorization code, and the app exchanges it for an access token carrying the scopes the merchant approved. The token then authenticates the same way, in the X-Auth-Token header. This is how an app distributed to many merchants gets per-store tokens.
The BigCommerce API is split into areas an agent can act on, like the product catalog, orders, customers, carts, and checkouts. Each area has its own methods and its own OAuth scope, and a scope comes in a modify form and a read-only form so an agent can be held to reading alone.
List, read, create, update, and delete products in the V3 catalog.
List, create, and update the variants of a product, each with its own SKU.
Read category trees and bulk create, update, and delete the categories within a tree.
List, read, create, update, and delete brands in the catalog.
List, read, create, update, and delete price lists that override catalog pricing per customer group or channel.
List, read, create, update, and delete orders through the V2 Orders API.
List, create, update, and delete customers through the V3 Customers API.
Read, create, and delete server-side carts and add line items to them.
Read a checkout and convert a completed checkout into an order.
List, read, create, update, and delete the webhooks that subscribe to store events.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Catalog — ProductsList, read, create, update, and delete products in the V3 catalog.5 | ||||||
| GET | /v3/catalog/products | Get a list of products in the catalog. | read | store_v2_products_read_only | Current | |
Read uses the read-only scope store_v2_products_read_only; the modify scope store_v2_products also satisfies it. The webhook link reflects that product changes fire store/product events, not this read call. Acts onproduct Permission (capability) store_v2_products_read_onlyVersionAvailable since the API’s base version Webhook event product-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/catalog/products | Create a product in the catalog. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. The UI calls this scope Products. Acts onproduct Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook event product-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/catalog/products/{product_id} | Get a single product by its ID. | read | store_v2_products_read_only | Current | |
Read-only. Acts onproduct Permission (capability) store_v2_products_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/catalog/products/{product_id} | Update a product by its ID. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts onproduct Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook event product-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/catalog/products/{product_id} | Delete a product by its ID. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Deletion is permanent. Acts onproduct Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook event product-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Catalog — VariantsList, create, and update the variants of a product, each with its own SKU.3 | ||||||
| GET | /v3/catalog/products/{product_id}/variants | Get the variants of a product. | read | store_v2_products_read_only | Current | |
Read-only. A variant is a version of a product with its own SKU. Acts onvariant Permission (capability) store_v2_products_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/catalog/products/{product_id}/variants | Create a variant on a product. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts onvariant Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook event product-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/catalog/products/{product_id}/variants/{variant_id} | Update a single variant on a product. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. A batch PUT on the collection path updates many variants at once. Acts onvariant Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook event product-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Catalog — CategoriesRead category trees and bulk create, update, and delete the categories within a tree.5 | ||||||
| GET | /v3/catalog/trees | Get the catalog's category trees. | read | store_v2_products_read_only | Current | |
Read-only. Category trees are the modern replacement for the deprecated flat categories endpoints. Acts oncategory tree Permission (capability) store_v2_products_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/catalog/trees/{tree_id}/categories | Get the categories within a category tree. | read | store_v2_products_read_only | Current | |
Read-only. The webhook link reflects that category writes fire store/category events. Acts oncategory Permission (capability) store_v2_products_read_onlyVersionAvailable since the API’s base version Webhook event category-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/catalog/trees/{tree_id}/categories | Bulk create categories within a tree. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Categories share the Products scope. Acts oncategory Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook event category-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/catalog/trees/{tree_id}/categories | Bulk update categories within a tree. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts oncategory Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook event category-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/catalog/trees/{tree_id}/categories | Bulk delete categories from a tree. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts oncategory Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook event category-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Catalog — BrandsList, read, create, update, and delete brands in the catalog.4 | ||||||
| GET | /v3/catalog/brands | Get a list of brands. | read | store_v2_products_read_only | Current | |
Read-only. Brands share the Products scope. Acts onbrand Permission (capability) store_v2_products_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/catalog/brands | Create a brand. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts onbrand Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/catalog/brands/{brand_id} | Update a brand by its ID. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts onbrand Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/catalog/brands | Delete brands by a filter. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts onbrand Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Price listsList, read, create, update, and delete price lists that override catalog pricing per customer group or channel.4 | ||||||
| GET | /v3/pricelists | Get all price lists. | read | store_v2_products_read_only | Current | |
Read-only. Price lists are governed by the Products scope. Acts onprice list Permission (capability) store_v2_products_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/pricelists | Create a price list. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Bulk upserts of price records run one at a time per store, or a second returns 429. Acts onprice list Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/pricelists/{price_list_id} | Update a price list by its ID. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts onprice list Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/pricelists/{price_list_id} | Delete a price list by its ID. | write | store_v2_products | Current | |
Needs the modify scope store_v2_products. Acts onprice list Permission (capability) store_v2_productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrdersList, read, create, update, and delete orders through the V2 Orders API.5 | ||||||
| GET | /v2/orders | Get a list of orders, filtered by query parameters. | read | store_v2_orders_read_only | Current | |
Orders are served by the older V2 API. Read uses store_v2_orders_read_only; the modify scope store_v2_orders also satisfies it. Acts onorder Permission (capability) store_v2_orders_read_onlyVersionAvailable since the API’s base version Webhook event order-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/orders/{order_id} | Get a single order by its ID. | read | store_v2_orders_read_only | Current | |
Read-only. Acts onorder Permission (capability) store_v2_orders_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orders | Create an order. | write | store_v2_orders | Current | |
Needs the modify scope store_v2_orders. The UI calls this scope Orders. Acts onorder Permission (capability) store_v2_ordersVersionAvailable since the API’s base version Webhook event order-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/orders/{order_id} | Update an order, including its status. | write | store_v2_orders | Current | |
Needs the modify scope store_v2_orders. Changing status fires store/order/statusUpdated. Acts onorder Permission (capability) store_v2_ordersVersionAvailable since the API’s base version Webhook event order-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/orders/{order_id} | Archive an order by its ID. | write | store_v2_orders | Current | |
Needs the modify scope store_v2_orders. This archives the order rather than erasing it. Acts onorder Permission (capability) store_v2_ordersVersionAvailable since the API’s base version Webhook event order-archivedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersList, create, update, and delete customers through the V3 Customers API.4 | ||||||
| GET | /v3/customers | Get all customers, filtered by query parameters. | read | store_v2_customers_read_only | Current | |
Read uses store_v2_customers_read_only; the modify scope store_v2_customers also satisfies it. Acts oncustomer Permission (capability) store_v2_customers_read_onlyVersionAvailable since the API’s base version Webhook event customer-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/customers | Create one or more customers. The fields email, first_name, and last_name are required. | write | store_v2_customers | Current | |
Needs the modify scope store_v2_customers. The UI calls this scope Customers. Acts oncustomer Permission (capability) store_v2_customersVersionAvailable since the API’s base version Webhook event customer-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/customers | Update one or more customers by ID in the request body. | write | store_v2_customers | Current | |
Needs the modify scope store_v2_customers. Customers V3 batches updates on the collection path. Acts oncustomer Permission (capability) store_v2_customersVersionAvailable since the API’s base version Webhook event customer-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/customers | Delete customers selected by a query filter. | write | store_v2_customers | Current | |
Needs the modify scope store_v2_customers. Acts oncustomer Permission (capability) store_v2_customersVersionAvailable since the API’s base version Webhook event customer-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CartsRead, create, and delete server-side carts and add line items to them.4 | ||||||
| POST | /v3/carts | Create a server-side cart with line items. | write | store_cart | Current | |
Needs the modify scope store_cart. The UI calls this scope Carts. Acts oncart Permission (capability) store_cartVersionAvailable since the API’s base version Webhook event cart-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/carts/{cartId} | Get a cart by its ID. | read | store_cart_read_only | Current | |
Read uses store_cart_read_only; the modify scope store_cart also satisfies it. Acts oncart Permission (capability) store_cart_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/carts/{cartId}/items | Add line items to an existing cart. | write | store_cart | Current | |
Needs the modify scope store_cart. Acts oncart line item Permission (capability) store_cartVersionAvailable since the API’s base version Webhook event cart-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/carts/{cartId} | Delete a cart by its ID. | write | store_cart | Current | |
Needs the modify scope store_cart. Acts oncart Permission (capability) store_cartVersionAvailable since the API’s base version Webhook event cart-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CheckoutsRead a checkout and convert a completed checkout into an order.2 | ||||||
| GET | /v3/checkouts/{checkoutId} | Get a checkout by its ID. | read | store_checkout_read_only | Current | |
Read uses store_checkout_read_only; the modify scope store_checkout also satisfies it. The UI calls this scope Checkouts. Acts oncheckout Permission (capability) store_checkout_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/checkouts/{checkoutId}/orders | Create an order from a completed checkout. | write | store_checkout | Current | |
Needs the modify scope store_checkout. This commits the checkout to a real order. Acts oncheckout Permission (capability) store_checkoutVersionAvailable since the API’s base version Webhook event order-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList, read, create, update, and delete the webhooks that subscribe to store events.4 | ||||||
| GET | /v3/hooks | Get all webhooks for the store. | read | store_v2_information_read_only | Current | |
Webhook management is governed by the Information & Settings scope; read uses store_v2_information_read_only. Acts onwebhook Permission (capability) store_v2_information_read_onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/hooks | Create a webhook subscribing to an event scope, posting to a destination URL. | write | store_v2_information | Current | |
Needs the modify scope store_v2_information. A webhook's scope, like store/order/created, names the event it listens for. Acts onwebhook Permission (capability) store_v2_informationVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/hooks/{id} | Update a webhook by its ID. | write | store_v2_information | Current | |
Needs the modify scope store_v2_information. Acts onwebhook Permission (capability) store_v2_informationVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/hooks/{id} | Delete a webhook by its ID. | write | store_v2_information | Current | |
Needs the modify scope store_v2_information. Acts onwebhook Permission (capability) store_v2_informationVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BigCommerce can notify an app or AI agent when something happens in a store, like an order being created or a product being updated, instead of the app repeatedly asking. A webhook subscribes to an event scope, such as store/order/created, and BigCommerce posts the event to a registered callback URL.
| Event | What it signals | Triggered by |
|---|---|---|
store/order/created | Fires when a new order is created in the store. | /v2/orders/v3/checkouts/{checkoutId}/orders |
store/order/updated | Fires when an order is updated. | /v2/orders/{order_id} |
store/order/archived | Fires when an order is archived. | /v2/orders/{order_id} |
store/product/created | Fires when a product is created in the catalog. | /v3/catalog/products |
store/product/updated | Fires when a product or one of its variants is updated. | /v3/catalog/products/{product_id}/v3/catalog/products/{product_id}/variants/v3/catalog/products/{product_id}/variants/{variant_id} |
store/product/deleted | Fires when a product is deleted from the catalog. | /v3/catalog/products/{product_id} |
store/category/created | Fires when a category is created. | /v3/catalog/trees/{tree_id}/categories |
store/category/updated | Fires when a category is updated. | /v3/catalog/trees/{tree_id}/categories |
store/category/deleted | Fires when a category is deleted. | /v3/catalog/trees/{tree_id}/categories |
store/customer/created | Fires when a customer is created. | /v3/customers |
store/customer/updated | Fires when a customer is updated. | /v3/customers |
store/customer/deleted | Fires when a customer is deleted. | /v3/customers |
store/cart/created | Fires when a cart is created. | /v3/carts |
store/cart/updated | Fires when a cart's contents change. | /v3/carts/{cartId}/items |
store/cart/deleted | Fires when a cart is deleted. | /v3/carts/{cartId} |
BigCommerce limits how fast an app or AI agent can call through a request quota that refreshes on a short rolling window and depends on the store's plan, and it reports the remaining quota on every response.
BigCommerce meters API requests by a per-store quota that refreshes on a short rolling window, not by a per-method cost. The quota depends on the store's plan: Standard and Plus stores get 20,000 requests per hour, which works out to about 150 in each 30-second window, and Pro stores get 60,000 per hour, about 450 per 30 seconds. Enterprise quotas vary by plan, and an Enterprise store can be placed on an unlimited-rate plan with no request limit. Every response reports the state through four headers: X-Rate-Limit-Requests-Quota is how many requests the window allows, X-Rate-Limit-Requests-Left is how many remain, X-Rate-Limit-Time-Window-Ms is the window size, and X-Rate-Limit-Time-Reset-Ms is how long until the quota resets. Exhausting the quota returns HTTP 429, and the reset header says how long to wait.
V3 list endpoints page with the page and limit query parameters and return a meta.pagination object with the total count, current page, and links to the next and previous pages. The limit parameter sets the page size, defaulting to 50, with a documented maximum that varies by endpoint and commonly tops out at 250. The older V2 list endpoints also use page and limit but return a flat array rather than a pagination envelope.
A V3 list page commonly returns up to 250 records where the endpoint allows it, and 50 by default. Some bulk operations, such as a price-list record upsert, must run one at a time per store, and starting a second in parallel returns HTTP 429.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication failed: the access token is missing, malformed, or not sent in the X-Auth-Token header. | Send a valid store access token in the X-Auth-Token header for the store named by the store hash in the path. |
| 403 | Forbidden | The token is valid but lacks the OAuth scope the request needs, for example calling a write endpoint with a read-only scope. | Grant the modify scope the endpoint requires, such as store_v2_products for a catalog write, then reissue the token. |
| 404 | Not Found | The resource does not exist, or the path or store hash is wrong. | Confirm the resource ID, the path, and the store hash, then retry. |
| 422 | Unprocessable Entity | The request was well-formed but a field failed validation, such as a missing required field on a customer create. | Read the errors object in the response, correct the named fields, and resend. |
| 429 | Too Many Requests | The store's request quota for the current window was exhausted. | Read the X-Rate-Limit-Time-Reset-Ms header and wait that long before retrying, increasing the wait if it recurs. |
| 500 | Internal Server Error | An error on BigCommerce's side. It is uncommon. | Retry with backoff, and contact BigCommerce support if it persists. |
BigCommerce runs two REST generations side by side. The newer V3 API covers the catalog, customers, carts, checkouts, price lists, and webhooks, while the older V2 API still serves areas like orders, and neither uses a dated version string.
V3 is the current REST generation, covering the catalog, customers, carts, checkouts, price lists, and webhooks. It returns a consistent data and meta envelope with pagination metadata, and is the path an integration should prefer wherever it exists. BigCommerce does not pin REST behavior to a dated version string; it ships dated, additive changelog entries instead, and keeps the older V2 API for the areas V3 has not replaced.
A dated, additive changelog cut. BigCommerce ships changes as dated entries rather than minting a new version string, so existing integrations keep working. This entry is an example of the ongoing timeline.
V2 is the older REST generation, kept in service for the areas V3 has not yet replaced, most notably Orders. Its responses are flatter than V3's and its list endpoints return a plain array. New work uses V3 where available and V2 only where it must.
An integration picks V3 where it exists and falls back to V2 for the areas V3 does not yet cover.
BigCommerce API changelog ↗Bollard AI sits between a team's AI agents and BigCommerce. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.