descrybe/docs/store-connectors.md

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

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