Print-on-Demand & Dropshipping Fulfillment

Paid pluginsize Lplanned, not built

Indicative price, not an offer: $0-19/mo + 2-5% transaction fee, or commission-based per fulfillment partner contract

Generated from docs/plan/paid/print-on-demand-dropshipping-fulfillment/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merchants can’t afford inventory for custom/niche products. This paid module enables zero-inventory fulfillment via print-on-demand and dropshipping partners (Printful, Apliiq, etc.).

The problem

I want to sell custom t-shirts and niche products, but I can’t afford to buy inventory upfront. I need automatic order routing to print-on-demand and dropshipping partners, with inventory sync.

What it does

• Support multiple fulfillment partners: Printful, Printify, Apliiq, Gelato, custom dropshipping APIs
• Store partner credentials (API keys) encrypted per merchant
• Map products to fulfillment partner SKUs (e.g., ‘red t-shirt XL’ → Printful SKU ‘12345’)
• On order checkout, route line items to appropriate fulfillment partner based on product mapping
• Auto-submit orders to partner API (partner handles printing, packing, shipping)
• Sync inventory from partner into products collection (available_quantity updated daily)
• Sync tracking: partner sends shipment notification; populate shipments collection with tracking number
• Handle partner failures gracefully: if partner is out of stock, fail checkout with clear message to customer
• Dashboard showing fulfillment partner status, order volume, failure rate

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.

• Wholesale dropshipping (e.g., Oberlo, CJdropshipping) with product import automation — that is product management, separate feature
• Markup calculation per partner (e.g., cost from partner + 30% merchant margin) — that is pricing engine, not fulfillment; can be plugin
• Partner-specific upsell opportunities (e.g., ‘recommend upgrade to premium embroidery’) — that is merchandising, separate feature

Data model

fulfillment_partners collection: {id, partner_name, credentials (encrypted), status (active|inactive), sync_inventory_interval_hours}. product_fulfillment_mappings collection: {product_id, partner_id, partner_sku, cost_minor_units}. orders.fulfillment_partner_id (which partner handles this order). No migration if columns are additive.

API

• POST /api/admin/fulfillment-partners — add partner credentials
• GET /api/admin/fulfillment-partners — list partners and sync status
• POST /api/admin/products/:productId/fulfillment-mapping — map product to partner SKU
• GET /api/admin/fulfillment-orders — list orders routed to partners, with partner status
• POST /api/webhooks/fulfillment/:partner — partner webhook endpoint (order shipped, tracking update)

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

Admin

Admin panel ‘Fulfillment’ section shows: (1) Configured partners (Printful, Apliiq, etc.) with status (connected/sync error), last inventory sync timestamp; (2) Product mappings table (product name, partner SKU, partner name); (3) Orders routed to partners with status (pending submit, submitted, shipped, failed).

The seam — why this is paid

Paid module owns partner integrations, order routing, and inventory sync. Core (checkout system) triggers routing decision. Merchant must pay to access partners; core provides the plumbing.

Paid module owns fulfillment partner API credentials, inventory sync, and order-routing logic per fulfillment rules; core tracks fulfillment status only

Dependencies

• Existing products, orders, order_items collections
• checkout system (must call fulfillment routing on order creation)
• webhook system (to receive partner shipment updates)
• scheduler (to sync inventory every N hours)

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.

• Map product to Printful SKU and create order; confirm order is submitted to Printful API
• Verify order is marked orders.fulfillment_partner_id=‘printful’
• Simulate partner webhook: send tracking number; confirm shipments collection is updated
• Run inventory sync and confirm available_quantity is updated from partner
• If partner is out of stock, create order and confirm checkout fails with ‘Product unavailable from fulfillment partner’

Risks

Partner API failures during checkout can cause lost orders. Implement retry queue and notify merchant immediately. Partner inventory syncs can take 1-2 hours to propagate; customers may see inconsistent availability. Implement buffer: reserve some inventory with partner, don’t sell 100% of reported quantity.

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.