# Store connectors — any store in, channel feeds out

Last updated: 2026-08-09  
UI hub: **`/stores`** (Stores & sources)

Descrybe v2 treats store platforms and supplier files as **input sources**, and Google Shopping / Meta / custom CSV/XML / REST as **outputs**. This page is the connector contract and backlog.

## Unified entry points

| Path | Role |
|------|------|
| `/stores` | Hub cards: Woo, Shopify, Feed URL, CSV upload, Export/REST |
| `/woocommerce` | Native WooCommerce REST sync (products, orders, reviews) |
| `/stores/shopify` | Shopify sibling guidance (feed URL / CSV today) |
| `/feeds` | Input feed list; deep-link `?add=1&source=url\|file` |
| `/export-feeds` | Outbound Google Shopping, Meta, custom CSV/XML public URLs |
| `/api/v1/*` | API-key REST catalog (generic “any system” pull) |
| `/api/public/export-feeds/{token}.{csv\|xml}` | Unauthenticated poll URL for Merchant Center / partners |

Primary sidebar: **Stores**, **Export** (plus Dashboard / Products / Billing). WooCommerce and input feeds are reached from the Stores hub. Reviews stay under More → Marketing. AI provider / email stay under More → Settings integrations. `/integrations` redirects to `/stores`.

## Inputs (sources)

### WooCommerce — ready (local live-proven)

- Config + encrypted credentials, connection test, queued product sync, orders/reviews for campaigns.
- UI: `/woocommerce`
- Ops: `docs/woocommerce-demo.md` (seed), **`docs/live-woo-test.md`** (`cmd/mock-woo` REST fixtures), `CREDENTIALS_ENCRYPTION_KEY`

### Shopify — ready (dry-run proven)

- Config + encrypted Admin API token, SSRF-safe shop domain, connection test, queued product push and orders pull.
- UI: /stores/shopify (also /shopify redirect). Hub card on /stores.
- Ops: docs/shopify-connector.md, docs/live-shopify-test.md, env SHOPIFY_*, dry-run via UI or token `dry-run`.
- Native product reviews are not supported (no first-party Admin API).

### Feed URL — ready

- Scheduled pull of public CSV/XML into `raw_products`, then mapping + sync.
- UI: `/feeds?add=1&source=url`

### CSV upload — ready

- One-shot file as an input feed (`source_path` in feed options).
- UI: `/feeds?add=1&source=file`

## Outputs (exports)

### Google Shopping / Merchant Center

- Presets in Export Feeds UI (`google_shopping_csv`, `google_shopping_xml`) — fields align with Go `marketing.DefaultCampaignMappings()` plus `g:` XML keys for XML.
- After create → **Refresh Feed** → copy public URL into Merchant Center → Products → Feeds → scheduled fetch.
- Seasonal prep (Black Friday) reuses the same mapping set via Content Calendar.

### Meta catalog

- Preset `meta_csv` for Commerce Manager data sources (id, title, availability, price, image_link, …).

### Custom CSV / XML

- Arbitrary field keys + Descrybe sources; XML root/item names configurable.
- Public URL is the integration surface for affiliates, comparison sites, and custom importers.

### Generic REST / webhook-style poll

Descrybe does **not** push arbitrary outbound webhooks yet. “Any store / any ERP” export is thin and intentional:

1. **Poll public feed URL** — `GET /api/public/export-feeds/{token}.csv|.xml` (no login).
2. **Pull catalog with API key** — `Authorization: Bearer dk_…` against `/api/v1/products` (and related catalog routes). OpenAPI: `GET /api/v1/openapi.yaml`.

Inbound Stripe webhooks are billing-only (`/api/webhooks/stripe`), not product sync.

### Inbound store webhooks (Shopify / Woo) — not shipped

Descrybe does **not** receive Shopify or WooCommerce webhooks. Product push and orders/reviews use **queued jobs + schedule/polling** only (UI: `StoreSyncDeliveryBanner` — “Store webhooks: not available”).

**Do not stub** `POST /api/webhooks/shopify|woocommerce` (or any CSRF-exempt half-HMAC receive path):

- `/api/webhooks/*` is CSRF-exempt and unauthenticated at the edge; auth must be full HMAC (and topic routing) or the route must not exist.
- A 501/“coming soon” after weak or missing verify trains shops to register a dead URL and looks like a live trust boundary.
- Real receive needs per-company secrets, shop/domain routing, idempotency, topic handlers, and platform registration — ship that as one complete feature, not a placeholder.

Only `/api/webhooks/stripe` is mounted today (signature-verified). See `docs/security-notes.md` and `docs/production-readiness.md`.

## Competitor must-haves → backlog

Brief scan of PIM / feed managers (Koongo, WISEPIM-style): channel templates, real-time sync, pre-export validation, advanced filters, bulk edit.

| Gap | Priority | Notes |
|-----|----------|--------|
| Google Shopping + Meta templates in UI | **Shipped** | Export presets + on-page how-to |
| Unified Stores hub / fewer nav duplicates | **Shipped** | `/stores`; Woo/Feeds off primary list |
| Pre-export validation (missing GTIN/price/title) | Backlog | High value; reuse quality score signals |
| Amazon channel preset | Backlog | Clone Google/Meta pattern |
| Advanced export filters (stock, tag, collection) | Backlog | Beyond status + source feed |
| Shopify Admin API (poll/queue sync) | **Shipped** (MVP) | Config/test/orders + product push; client-credentials OAuth checklist; App Store one-click backlog |
| Inbound store webhooks (Shopify/Woo receive + register) | Deferred | **Do not stub**; poll/queue only until full HMAC receive ships |
| Outbound product webhooks (push) | Backlog | Poll URL covers most partners; push only if asked |
| Two-way inventory sync | Backlog | Woo one-way MVP today |

Do **not** expand into 500-channel marketplaces until core Woo + feed + Google Shopping paths are battle-tested.

## Verification

```bash
cd apps/web && npm run check
cd apps/api && go build ./...
```