> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/ecom-platforms/bigcommerce.md).

# BigCommerce

BigCommerce is an enterprise-focused ecommerce platform with a comprehensive REST API and advanced webhook support. Merchants connect to Violet by providing API credentials either through an OAuth app flow or directly via Store Level API credentials.

## Connection

BigCommerce supports two connection paths:

**OAuth (Recommended)** — Merchants authorize through the BigCommerce App Marketplace. Violet receives a token exchange with `client_id`, `access_token`, and `store_hash` automatically.

**Store Level API** — Merchants generate credentials directly in their BigCommerce store admin and provide them manually. This requires the store URL (e.g. `https://store-{hash}.mybigcommerce.com`), Client ID, Client Secret, and Access Token.

### Required API Scopes

When connecting via Store Level API, Violet validates that all of the following scopes are present:

| Scope                            | Access Level                  |
| -------------------------------- | ----------------------------- |
| `store_v2_default`               | Default store access          |
| `store_v2_customers`             | Customers (modify)            |
| `store_cart`                     | Carts (modify)                |
| `store_v2_orders`                | Orders (modify)               |
| `store_v2_information_read_only` | Store information (read-only) |
| `store_checkout`                 | Checkout (modify)             |
| `store_v2_products_read_only`    | Products (read-only)          |

Violet will return an error listing any missing scopes during the connection attempt.

## Webhooks

Webhooks are registered automatically when a merchant connects. Violet listens for order and product lifecycle events. Webhook signatures are validated on all inbound requests.

## Notable Behavior

* **Coupon codes**: BigCommerce supports coupon codes natively. Use `Coupon Codes` (not `Promotions`) when creating discount codes for use with Violet-submitted orders.
* **Refunds**: Refunds submitted through Violet may appear as "offline" in BigCommerce — this is expected behavior.
* **Rate limits**: BigCommerce enforces rate limits of approximately 450 requests per 30 seconds. Violet handles retries with exponential backoff.
* **Product variants**: BigCommerce uses a named option/value system for variants. Violet maps these to its unified variant model automatically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/ecom-platforms/bigcommerce.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.