Marketplace Channel Sync

Paid pluginsize Lplanned, not built

Indicative price, not an offer: EUR 300-600/year or EUR 800 one-off

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

Paid module that syncs product catalog, inventory, orders, and prices between AstroBaaS and Amazon, eBay, Walmart. Handles variant-to-SKU mapping, per-channel inventory reservation, and order import. Merchants need OAuth credentials (Selling Partner API, eBay, Walmart API).

The problem

Selling on Amazon and eBay means manually syncing inventory, orders, and prices. Every price change requires re-listing on both sites, and inventory gets out of sync within hours. Order management is split between three systems.

What it does

• Amazon Selling Partner API OAuth integration (MWS or SellingPartner)
• eBay OAuth integration (via partner OAuth keys)
• Walmart integration (API credentials if available)
• Product mapping (AstroBaaS variant SKU → Amazon ASIN, eBay Item ID, Walmart SKU)
• Real-time price sync (AstroBaaS price → listing price on each channel)
• Inventory sync with per-channel reservation (prevent overselling across channels)
• Inventory conflict resolution (which channel gets the unit if both claim it)
• Order import (Marketplace order → AstroBaaS order with source_marketplace)
• Shipping label generation from AstroBaaS orders
• Fulfillment status sync (mark marketplace order shipped when AstroBaaS order ships)
• Return/refund sync (marketplace returns → AstroBaaS return requests)

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.

• Marketplace analytics (reason: belongs to paid analytics addon)
• Repricing automation (reason: belongs to paid pricing strategy addon)
• Seller performance tracking (reason: marketplace-specific metrics; core doesn’t own reputation data)
• Tax calculation per marketplace (reason: belongs to paid tax compliance addon)
• Automated dispute resolution (reason: legal complexity; belongs to support tier)

Data model

Migration required. New tables: marketplace_channels (platform, encrypted_api_credentials, sync_status, last_sync_at). New fields: product_variant.asin, product_variant.ebay_item_id, product_variant.walmart_sku, product_variant.marketplace_channel_id. New table: inventory_reservation (product_id, channel_id, reserved_qty, reserved_at). New field: order.source_marketplace (amazon/ebay/walmart).

API

• POST /admin/marketplace-channels/connect/:channel
• GET /admin/marketplace-channels/callback
• GET /admin/marketplace-channels
• DELETE /admin/marketplace-channels/:id
• PATCH /admin/marketplace-channels/:id/sync-config
• POST /admin/marketplace-channels/:id/sync-now
• GET /admin/marketplace-channels/:id/status
• PATCH /admin/products/:id/marketplace-skus
• GET /admin/orders (with source_marketplace filter)
• POST /admin/orders/:id/fulfillment

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

Admin

Marketplace channel connection page (OAuth buttons). Sync status dashboard (last sync, errors, next sync). Inventory reservation view (units per channel). Product mapping tool (bulk assign SKUs). Order view filtered by source. Fulfillment sync page (mark orders shipped). Channel performance metrics (orders, revenue per channel).

The seam — why this is paid

Core owns product catalog, order creation, inventory, and fulfillment. Paid pack owns marketplace OAuth, credential storage, mapping logic, and sync scheduling. Core provides inventory API; paid pack owns inventory_reservation table and conflict resolution. Core audit log tracks changes; paid pack logs syncs and conflicts.

Requires Amazon/eBay/Walmart API credentials and real-time sync. High support cost for order routing and inventory conflicts.

Dependencies

• Core product catalog API with variant support
• Core order creation and fulfillment API
• Core inventory system (must support reservations)
• Core shipping system (to pull fulfillment data)
• Existing OAuth infrastructure
• Webhook system (optional, for real-time sync triggers)

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 listed on Amazon and eBay with 10 units total reserves 7 for Amazon and 3 for eBay; AstroBaaS shows 0 available
• If Amazon and eBay both claim the last unit simultaneously, one succeeds and one gets a conflict log entry (no overselling)
• A price change in AstroBaaS updates on Amazon within 5 minutes (real-time) or 1 hour (scheduled)
• An Amazon order creates an AstroBaaS order with source_marketplace = ‘amazon’ and maps back to Amazon for fulfillment tracking
• A return initiated on eBay creates an AstroBaaS return request with source_marketplace = ‘ebay’
• Disconnecting a channel stops sync and refunds reserved inventory to available
• Marketplace credentials are encrypted at rest
• Multi-variant products with different SKUs per channel map correctly (Amazon ASIN-123, eBay EBAY-SKU-456)

Risks

If inventory reservation fails, a single unit sells to multiple channels (overselling). If OAuth tokens expire without refresh, sync silently stops and inventory drifts. If order import duplicates orders, customers charge twice. If credentials leak, attacker accesses merchant Amazon/eBay/Walmart account. If sync is too frequent, marketplace rate limits are hit.

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.