# BigCommerce

## Prerequisites

* A BigCommerce store with admin access
* A BigCommerce store-level API account

## Getting Your API Credentials

### Step 1: Create a Store-Level API Account

1. Log in to your **BigCommerce Admin Panel**
2. Go to **Settings > API > API Accounts**
3. Click **Create API Account > Create V2/V3 API Token**

### Step 2: Configure API Scopes

Give the API account the following permissions:

| Resource               | Permission Level |
| ---------------------- | ---------------- |
| **Products**           | Read-only        |
| **Orders**             | Modify           |
| **Customers**          | Read-only        |
| **Order Transactions** | Read-only        |
| **Store Information**  | Read-only        |
| **Marketing**          | Read-only        |

{% hint style="info" %}
**Orders (Modify)** is required for order cancellation. If you only need order lookup, Read-only is sufficient.

**Store Information** allows Alhena to auto-detect your store name, URL, and currency — no manual entry needed.

**Marketing** enables discount code lookup and gift card balance checking.
{% endhint %}

Leave all other scopes at their default (None) setting.

### Step 3: Save and Copy Credentials

1. Click **Save** to create the API account
2. A dialog will appear with your credentials. **Copy these immediately** — the Access Token is only shown once:
   * **Store Hash** — Found in the API Path URL (e.g., in `https://api.bigcommerce.com/stores/abc1d2ef/v3/`, the store hash is `abc1d2ef`)
   * **Access Token** — The API token for authentication

{% hint style="warning" %}
The Access Token is only displayed once when you create the API account. If you lose it, you'll need to create a new API account.
{% endhint %}

***

## Setup

### Step 1: Enable BigCommerce in Alhena

1. In Alhena, go to **Settings > Integrations**
2. Find **BigCommerce** and click **Enable**
3. You'll be taken to the BigCommerce configuration page

### Step 2: Connect Your Store

Enter your BigCommerce API credentials:

1. **Store Hash** — The unique identifier for your store (e.g., `abc1d2ef`). You can find this in your BigCommerce API Path URL between `/stores/` and `/v3/`.
2. **Access Token** — The API token from your store-level API account

Click **Connect** to complete the setup.

{% hint style="info" %}
Alhena automatically detects your store name, storefront URL, and default currency from BigCommerce — you don't need to enter these manually.

If you accidentally paste the full BigCommerce dashboard URL (e.g., `https://store-abc1d2ef.mybigcommerce.com/manage/dashboard`) into the Store Hash field, Alhena will automatically extract the store hash for you.
{% endhint %}

***

## Enabled Agents and Tools

When you connect your BigCommerce store, the following agents and tools are automatically enabled:

### Order Management

| Tool                        | Description                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------- |
| **Get Order Information**   | Look up order details by order number or email — status, line items, shipment tracking |
| **Cancel Order**            | Cancel an order on behalf of the customer (if not yet shipped)                         |
| **Check Gift Card Balance** | Check the remaining balance on a BigCommerce gift certificate                          |

### Product Expert

| Tool                        | Description                                                          |
| --------------------------- | -------------------------------------------------------------------- |
| **Get Product Information** | Provide product details, pricing, availability, and variant options  |
| **Lookup Discount Code**    | Look up a coupon code to check validity, discount amount, and expiry |
| **List Active Promotions**  | Show currently active promotions and coupons                         |

You can enable or disable individual tools in **AI Settings > Agents**.

### What your customers can ask

Once connected, your AI assistant can help customers with:

* **Order status** — "Where is my order #12345?"
* **Shipment tracking** — "Has my order shipped yet?"
* **Order cancellation** — "I'd like to cancel my order"
* **Product details** — "What sizes does this come in?"
* **Product availability** — "Is this item in stock?"
* **Pricing** — "How much does the Premium Boxing Gloves cost?"
* **Discount codes** — "Is the code SAVE20 still valid?"
* **Gift cards** — "What's the balance on my gift card?"
* **Active sales** — "Do you have any promotions right now?"

***

## Product Crawling

Alhena automatically syncs your BigCommerce product catalog, including:

* Product names, descriptions, and images
* All variant options (size, color, etc.)
* Pricing (regular and sale prices)
* Custom fields
* Product videos (YouTube)
* Stock availability

Only **visible** and **in-stock** products are synced. Products with zero inventory across all variants are automatically excluded. Products restricted to wholesale or specific customer groups are also filtered out when the Customers scope is enabled.

***

## Disconnecting

To disconnect your BigCommerce store:

1. Go to **Settings > Integrations > BigCommerce**
2. Click **Disconnect**
3. Confirm the disconnection

This will disable all BigCommerce-connected agents and tools, and revoke access to your store data.

***

## Troubleshooting

### "Invalid access token" error

* Make sure you're using the Access Token from a **store-level** API account (not an account-level token)
* Verify the token hasn't been revoked in BigCommerce Admin > Settings > API > API Accounts

### "Access forbidden" error

* Check that your API account has the required scopes (see the table above)
* You may need to create a new API account with the correct permissions

### Products not appearing

* Only **visible** products with at least one in-stock variant are synced
* Products marked as hidden in BigCommerce will not appear
* Products restricted to wholesale customer groups are automatically excluded
* After connecting, allow a few minutes for the initial product sync to complete

### Discount code lookup not working

* Ensure the **Marketing (Read-only)** scope is enabled on your API account
* The lookup searches BigCommerce coupons — promotions without coupon codes cannot be looked up by code

### Gift card balance check not working

* Ensure the **Marketing (Read-only)** scope is enabled on your API account
* BigCommerce calls these "Gift Certificates" — the code must match exactly