# WooCommerce

WooCommerce is an open-source e-commerce platform built on WordPress. The Sling WooCommerce connector extracts data from the WooCommerce REST API v3, supporting products, orders, customers, coupons, 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:**

* `consumer_key` **(required)** -> Your WooCommerce REST API Consumer Key
* `consumer_secret` **(required)** -> Your WooCommerce REST API Consumer Secret
* `store_url` **(required)** -> Your WooCommerce store URL (e.g., `https://mystore.com`)

**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 WordPress admin dashboard
2. Go to **WooCommerce** > **Settings** > **Advanced** > **REST API**
3. Click **Add key**
4. Enter a description (e.g., "Sling Integration")
5. Set **Permissions** to **Read**
6. Click **Generate API key**
7. Copy the **Consumer key** and **Consumer secret**

{% hint style="warning" %}
**Important:** The Consumer secret is only shown once. Make sure to copy it immediately after generating.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set WOOCOMMERCE type=api spec=woocommerce secrets='{ consumer_key: ck_xxxx, consumer_secret: cs_xxxx, store_url: "https://mystore.com" }'
```

{% 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 WOOCOMMERCE='{ type: api, spec: woocommerce, secrets: { consumer_key: "ck_xxxx", consumer_secret: "cs_xxxx", store_url: "https://mystore.com" } }'
```

{% 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:
  WOOCOMMERCE:
    type: api
    spec: woocommerce
    secrets:
      consumer_key: "ck_xxxx"
      consumer_secret: "cs_xxxx"
      store_url: "https://mystore.com"
```

**With anchor date for historical data:**

```yaml
connections:
  WOOCOMMERCE:
    type: api
    spec: woocommerce
    secrets:
      consumer_key: "ck_xxxx"
      consumer_secret: "cs_xxxx"
      store_url: "https://mystore.com"
    inputs:
      anchor_date: "2023-01-01"
```

## Replication

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

```yaml
source: WOOCOMMERCE
target: MY_POSTGRES

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

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

**Full refresh example for reference data:**

```yaml
source: WOOCOMMERCE
target: MY_POSTGRES

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

streams:
  product_categories:
  product_tags:
  product_attributes:
  tax_classes:
  shipping_zones:
  shipping_methods:
  payment_gateways:
```

## Endpoints

### Products

| Endpoint                   | Description                            | Incremental |
| -------------------------- | -------------------------------------- | ----------- |
| `products`                 | All products in the store              | Yes         |
| `product_variations`       | Variations for variable products       | No (child)  |
| `product_categories`       | Product categories                     | No          |
| `product_tags`             | Product tags                           | No          |
| `product_attributes`       | Product attributes (e.g., Color, Size) | No          |
| `product_reviews`          | Customer reviews on products           | Yes         |
| `product_shipping_classes` | Shipping classes for products          | No          |

### Orders

| Endpoint        | Description            | Incremental |
| --------------- | ---------------------- | ----------- |
| `orders`        | All orders             | Yes         |
| `order_notes`   | Notes on each order    | No (child)  |
| `order_refunds` | Refunds for each order | No (child)  |

### Customers & Coupons

| Endpoint    | Description          | Incremental |
| ----------- | -------------------- | ----------- |
| `customers` | Registered customers | No          |
| `coupons`   | Discount coupons     | Yes         |

### Tax & Shipping

| Endpoint           | Description                    | Incremental |
| ------------------ | ------------------------------ | ----------- |
| `tax_rates`        | Tax rates                      | No          |
| `tax_classes`      | Tax classes                    | No          |
| `shipping_zones`   | Shipping zones                 | No          |
| `shipping_methods` | Available shipping methods     | No          |
| `payment_gateways` | Payment gateway configurations | No          |

To discover available endpoints:

```bash
sling conns discover WOOCOMMERCE
```

## Incremental Sync

The WooCommerce connector uses `modified_after` 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

Incremental endpoints track the `date_modified_gmt` field (or `date_created_gmt` for reviews) to determine the sync boundary.

### Child Endpoints

The `product_variations`, `order_notes`, and `order_refunds` endpoints are child endpoints that iterate over parent IDs from the `products` and `orders` streams. They automatically fetch data for all parent records returned in the current sync.

## Rate Limiting

The WooCommerce REST API rate limits depend on your hosting provider. The connector uses conservative defaults:

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

These settings work well for most hosting environments. If you experience rate limiting, consider reducing the concurrency in your replication configuration.

## Common Use Cases

### Sync All E-commerce Data

```yaml
source: WOOCOMMERCE
target: MY_POSTGRES

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

streams:
  products:
  orders:
  customers:
  coupons:
```

### Sync Product Catalog

```yaml
source: WOOCOMMERCE
target: MY_POSTGRES

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

streams:
  products:
  product_variations:
  product_categories:
  product_tags:
  product_attributes:
```

### Sync Orders with Details

```yaml
source: WOOCOMMERCE
target: MY_POSTGRES

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

streams:
  orders:
  order_notes:
  order_refunds:
```

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).