Facebook Shop Sync

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €29/mo; credential: Facebook API integration, daily catalog sync

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

Merchants maintain their Facebook Shop catalog and sync it with AstroBaaS inventory automatically. New product uploads in AstroBaaS appear on Facebook within hours; when a customer buys on Facebook, the order syncs to AstroBaaS and inventory updates. The paid pack maintains Facebook API integration and sync logic; core owns the inventory interface.

The problem

Merchants running Facebook Shops must update product catalog manually if AstroBaaS is their source of truth. Inventory gets out of sync, causing overselling or misleading customers.

What it does

• Product sync: new products in AstroBaaS upload to Facebook Shop within 2 hours
• Inventory sync: stock changes in AstroBaaS update Facebook availability
• Order import: Facebook Shop orders sync to AstroBaaS within 15 minutes
• Price sync: product price changes in AstroBaaS update on Facebook
• Image sync: product images (up to 5 per product) upload to Facebook
• Deactivation: products marked inactive in AstroBaaS are hidden on Facebook Shop
• Sync status dashboard: admin sees last sync time, sync errors, item counts
• Test mode: sync to Facebook staging environment

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.

• Facebook ads integration: we sync catalog only; ads campaigns are managed in Facebook Ads Manager (separate product).
• Messenger sales: Facebook Messenger checkout is Facebook’s responsibility; we sync orders only.
• Review sync: customer reviews on Facebook Shop are not synced to AstroBaaS (feedback loop not needed).
• Promotion codes: Facebook promotions are managed in Facebook Shop; AstroBaaS does not push discount rules.

Data model

New document: facebook_sync_record { productId, facebookProductId, lastSyncAt, syncStatus (success, error), error_message }. New setting: facebook_shop_id (string), facebook_catalog_id (string).

API

• POST /api/facebook/sync/start -> { jobId }
• GET /api/facebook/sync/{jobId}/status -> { status, productsSynced, productsFailed, lastCheck }
• GET /api/facebook/sync/status (admin only) -> current sync status, last sync time
• POST /api/facebook/sync/product/{productId} (manual sync for one product)
• GET /api/facebook/orders?from=2026-09-01&to=2026-09-03 (admin only, imported orders)

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

Admin

Admin sees: Facebook Shop connection status, last sync time and next scheduled sync, product sync progress, sync error log (by product), inventory sync status, imported orders from Facebook.

The seam — why this is paid

Core owns the inventory interface and order sync. Paid pack owns: Facebook Catalog API integration, real-time sync scheduler, error recovery logic.

Credential: Facebook Shop API management, inventory sync, order import

Dependencies

• product subsystem (existing)
• inventory subsystem (existing)
• order subsystem (existing)
• scheduler subsystem (existing)

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 added to AstroBaaS appears on Facebook Shop within 2 hours
• Inventory for product ABC decreases by 10 in AstroBaaS; Facebook Shop shows updated stock
• An order placed on Facebook Shop appears in AstroBaaS order list within 15 minutes
• Product is marked inactive in AstroBaaS; it is hidden on Facebook Shop within 2 hours
• Price change in AstroBaaS updates on Facebook within 2 hours
• Product has 5 images in AstroBaaS; all 5 upload to Facebook (up to 5 supported)
• Admin can manually trigger sync for one product from admin UI
• Sync error (API timeout, invalid product) is logged with product ID, error, timestamp

Risks

If inventory sync is one-way only, Facebook sells when AstroBaaS is out of stock (overselling). If order import is delayed, customer email and shipping address take time to arrive (poor fulfillment). If product IDs are not stable, each sync creates duplicate Facebook products. If images are not validated, non-image files crash sync. If Facebook API is rate-limited, sync falls behind (support burden).

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.