# BigCommerce

BigCommerce is a leading e-commerce platform for building online stores. The Sling BigCommerce connector extracts data from the BigCommerce REST Management API, supporting products, orders, customers, channels, and more.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `access_token` **(required)** -> Your BigCommerce API access token
* `store_hash` **(required)** -> Your BigCommerce store hash (found in the API path or store URL)

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your API Credentials

1. Log in to your BigCommerce admin dashboard
2. Go to **Settings** > **API** > **API accounts**
3. Click **Create API account** > **Create V2/V3 API Token**
4. Enter a name (e.g., "Sling Integration")
5. Set the following scopes to **Read-only**:
   * Content
   * Customers
   * Information & settings
   * Orders
   * Order transactions
   * Products
   * Channel settings
   * Sites & routes
6. Click **Save**
7. Copy the **Access Token** — it is only shown once
8. Your **Store Hash** can be found in the API path URL (e.g., `stores/abc123def` → store hash is `abc123def`)

{% hint style="warning" %}
**Important:** The Access Token is only displayed once after creation. Make sure to copy it immediately.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set BIGCOMMERCE type=api spec=bigcommerce secrets='{ access_token: xxxx, store_hash: your_store_hash }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export BIGCOMMERCE='{ type: api, spec: bigcommerce, secrets: { access_token: "xxxx", store_hash: "your_store_hash" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  BIGCOMMERCE:
    type: api
    spec: bigcommerce
    secrets:
      access_token: "xxxx"
      store_hash: "your_store_hash"
```

**With anchor date for historical data:**

```yaml
connections:
  BIGCOMMERCE:
    type: api
    spec: bigcommerce
    secrets:
      access_token: "xxxx"
      store_hash: "your_store_hash"
    inputs:
      anchor_date: "2023-01-01"
```

## Replication

Here's an example replication configuration to sync BigCommerce data to a PostgreSQL database:

```yaml
source: BIGCOMMERCE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: bigcommerce.{stream_name}

streams:
  # sync all endpoints
  '*':
```

**Full refresh example for reference data:**

```yaml
source: BIGCOMMERCE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: bigcommerce.{stream_name}

streams:
  store_information:
  categories:
  brands:
  channels:
  pages:
```

## Endpoints

### Store

| Endpoint            | Description                | Incremental |
| ------------------- | -------------------------- | ----------- |
| `store_information` | Store details and settings | No          |

### Catalog

| Endpoint     | Description                 | Incremental |
| ------------ | --------------------------- | ----------- |
| `products`   | All products in the catalog | Yes         |
| `categories` | Product categories          | No          |
| `brands`     | Product brands              | No          |

### Customers

| Endpoint    | Description              | Incremental |
| ----------- | ------------------------ | ----------- |
| `customers` | All registered customers | Yes         |

### Orders

| Endpoint             | Description                         | Incremental |
| -------------------- | ----------------------------------- | ----------- |
| `orders`             | All orders                          | Yes         |
| `order_products`     | Line items for each order           | No (child)  |
| `order_transactions` | Payment transactions for each order | No (child)  |

### Other

| Endpoint   | Description                            | Incremental |
| ---------- | -------------------------------------- | ----------- |
| `channels` | Sales channels (storefront, POS, etc.) | No          |
| `pages`    | Store content pages                    | No          |

To discover available endpoints:

```bash
sling conns discover BIGCOMMERCE
```

## Incremental Sync

The BigCommerce connector uses `date_modified` for incremental sync on supported endpoints:

* **First run:** Fetches all records from `anchor_date` (default: 1 year ago) to present
* **Subsequent runs:** Only fetches records modified after the last sync timestamp

### Child Endpoints

The `order_products` and `order_transactions` endpoints are child endpoints that iterate over order IDs from the `orders` stream. They automatically fetch data for all orders returned in the current sync.

## Rate Limiting

BigCommerce rate limits vary by plan (150–450 requests per 30 seconds). The connector uses conservative defaults:

* **5 requests per second**
* **3 concurrent requests**

## Common Use Cases

### Sync All E-commerce Data

```yaml
source: BIGCOMMERCE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: ecommerce.{stream_name}

streams:
  products:
  orders:
  customers:
```

### Sync Orders with Details

```yaml
source: BIGCOMMERCE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: orders.{stream_name}

streams:
  orders:
  order_products:
  order_transactions:
```

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).