WooCommerce adapter

The WooCommerce adapter calls the WC REST API (v3) with a read-only consumer key / consumer secret pair. It exposes products, categories, and tags.

Config shape

{
  "type": "woocommerce",
  "config": {
    "storeUrl": "https://example.com",
    "consumerKey": "ck_xxxxxxxxxxxxxxxxxxxx",
    "consumerSecret": "cs_xxxxxxxxxxxxxxxxxxxx",
    "version": "wc/v3"
  },
  "collections": {
    "products": {
      "source": "products",
      "searchable_fields": ["name", "sku", "short_description"],
      "filterable_fields": ["stock_status", "category", "tag"],
      "display_fields": ["id", "name", "price", "sku", "stock_status"]
    }
  }
}

Setup

1. Generate a read-only API key

   WooCommerce admin → Settings → Advanced → REST API → Add key.

   Field	Value
   Description	Spelo readonly
   User	any admin user
   Permissions	Read

   Click Generate API key. Copy both ck_... (consumer key) and cs_... (consumer secret). You won’t see the secret again.

2. Confirm REST API is accessible

   Visit https://your-store.com/wp-json/wc/v3/products?consumer_key=...&consumer_secret=... in a browser. You should get JSON. If you see a 404, your permalinks aren’t configured for WordPress REST — go to Settings → Permalinks and pick anything other than “Plain”.

3. Paste in the dashboard

   Dashboard → Data → WooCommerce → paste store URL, key, secret → Test connection.

4. Map collections

   Default setup: one collection mapping to products. If you want to expose categories/tags too, add additional collections with source: "products/categories" or source: "products/tags".

Operator translation

WC REST supports a fixed set of query params. The adapter translates:

Filter	WC query param
category eq	category=<id>
tag eq	tag=<id>
stock_status eq	stock_status=instock (or outofstock, onbackorder)
sku eq	sku=
on_sale eq	on_sale=true
free-text query	search=<q>
sort by price	orderby=price

For operators WC doesn’t natively support (contains on description, gt/lt on price), the adapter fetches and filters client-side. Expect slower responses for these.

Field type notes

• price / regular_price / sale_price are returned as strings (WooCommerce stores them that way). The adapter parses them to numbers for numeric comparisons.
• stock_quantity may be null for unmanaged stock.
• Images come back as an array of { src, alt }. Use image.src for the primary image URL.

Security notes

• The consumer key/secret pair is read-only — you selected “Read” permissions in step 1. An attacker with this pair can read your products but cannot change anything.
• WC uses HTTP Basic Auth with the key/secret. The adapter always uses HTTPS.
• All requests go through GET /wp-json/wc/v3/*. No POST/PUT/DELETE code paths exist.

WordPress hosting gotchas

• WP Engine / Kinsta / WPX — make sure the REST API isn’t blocked by a plugin like “Disable REST API”. If it is, allow the /wc/v3/* routes.
• Cloudflare — if you have aggressive caching rules, add a bypass for /wp-json/*.
• Jetpack Protect, Wordfence — their “brute force protection” can 403 REST calls. Allow-list Spelo’s egress IPs.

Rate limits

WC itself doesn’t rate-limit by default, but your host probably does. For traffic heavier than a few queries per second, migrate to a direct MySQL connection via the MySQL adapter pointed at wp_wc_product_meta_lookup.

Troubleshooting

• 401 Invalid authentication → key/secret wrong, or copied with leading/trailing whitespace.
• 404 rest_no_route → WP permalinks are set to “Plain”. Switch to “Post name”.
• rest_cannot_view → you set the key’s permissions to Write or none. Create a new key with Read.
• Empty products list → your store has no Published products. Drafts are excluded.

More: Database connection errors.

Connect a different data source

Overview Postgres MySQL MS SQL MongoDB Supabase Firebase OAuth setup Airtable Google Sheets Shopify REST API Webhook TS adapter Schema introspection