Marketplace & Social Shop Sync (Facebook, TikTok, Google)

Paid pluginsize Lplanned, not built

Indicative price, not an offer: $0-19/mo platform fee (channels pay their own commission)

Generated from docs/plan/paid/marketplace-social-shop-sync/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Paid module that syncs AstroBaaS product catalog to Facebook Shop, TikTok Shop, and Google Shopping with real-time inventory reservation and order import. Merchants need OAuth credentials (Facebook/TikTok/Google) and each platform enforces its own catalog rules.

The problem

I miss sales by not selling on social platforms; manual listing sync to Facebook/TikTok/Google Shop is broken. Every product update means manually re-uploading to Facebook and TikTok, and inventory gets out of sync within hours.

What it does

• OAuth 2.0 flow for Facebook, TikTok, Google Shop (per merchant, per platform)
• Product catalog export in each platform’s schema (images, prices, variants, descriptions)
• Real-time inventory sync with per-platform reservation (reserve 5 units for Facebook, 3 for TikTok from 10 total)
• Order import from each platform (creates AstroBaaS order with source_platform field)
• Price and category mapping (AstroBaaS → platform format)
• Daily full catalog refresh (sync to catch manual platform edits)
• Multi-language product descriptions (if shop configured for multiple languages)
• Tax and shipping category assignment per product
• Platform-specific attribute mapping (e.g., Google color taxonomy)
• Inventory conflict detection (both platforms claim last unit; log conflict, let one succeed)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Commission calculation or payment settlement (reason: belongs to paid accounting addon; this module handles inventory sync only)
• Platform reviews and ratings aggregation (reason: belongs to paid review aggregation service)
• Platform analytics integration (reason: belongs to paid analytics addon)
• Custom per-merchant product data mapping (reason: would require per-shop rule editing; core does 1:1 mapping only)
• Automatic platform policy enforcement (reason: platform rules change monthly; belongs to support tier)

Data model

Migration required. New tables: shop_social_accounts (platform, encrypted_oauth_token, platform_shop_id, status, connected_at). New fields: product.facebook_id, product.tiktok_id, product.google_id, product.social_sync_status (synced/pending/error). New table: inventory_reservation (product_id, platform, reserved_qty, reserved_at). New field: order.source_platform (facebook/tiktok/google).

API

• POST /admin/social-shops/connect/:platform
• GET /admin/social-shops/callback
• GET /admin/social-shops
• DELETE /admin/social-shops/:platform
• POST /admin/social-shops/:platform/sync-now
• GET /admin/social-shops/:platform/sync-status
• PATCH /admin/products/:id/social-mapping
• GET /admin/inventory-conflicts

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Social Shop connection page with buttons for each platform (shows OAuth status). Sync status dashboard (last sync time, next scheduled, error messages). Product preview as it appears on each platform. Inventory reservation view (which units claimed by which platform). Order import log (timestamps, order IDs from each platform).

The seam — why this is paid

Core owns product catalog API and inventory system. Paid pack owns platform-specific OAuth, credential storage, and sync scheduling. Core provides inventory API; paid pack owns inventory_reservation table and per-platform stock holds. Core audit log tracks product changes; paid pack logs all sync operations and conflicts.

Paid module owns channel-specific OAuth, catalog sync API, and inventory reservation logic per marketplace rules; core provides product catalog export only

Dependencies

• Core product catalog API with variant support
• Core inventory system (must support per-platform reservations)
• Core order creation API (to import platform orders)
• Existing OAuth infrastructure
• Webhook system (for real-time inventory updates from platforms, optional but recommended)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A product created in AstroBaaS appears on Facebook Shop within 5 minutes (scheduled sync) or < 1 minute (manual sync)
• A product with 10 units total reserves 5 for Facebook and 3 for TikTok; AstroBaaS available stock shows 2
• If both Facebook and TikTok claim the last unit simultaneously, one succeeds and one gets a conflict log entry (no overselling)
• An order placed on Facebook Shop creates an AstroBaaS order with source_platform = ‘facebook’ and currency set to shop currency
• Inventory on Facebook Shop updates when AstroBaaS inventory changes (real-time via webhook if available, or within 1 hour via scheduled sync)
• Disconnecting a platform stops syncing and releases all reserved inventory for that platform
• A product violating platform rules (e.g., missing tax category for Google) is flagged in sync log but still uploaded (human review required)
• Multi-variant products map correctly (SKU consistent across platforms)

Risks

If inventory reservation logic fails, overselling occurs across channels and causes refunds. If OAuth tokens are stored unencrypted, any backup leak exposes merchant Facebook/TikTok account. If sync runs too frequently, platform rate limits are hit and all syncs stall for 24 hours. If order import has duplicates, customers are charged twice. If platform attributes are mapped wrong, products are rejected by the platform.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.