Core Return Logistics (Mechanics)

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €29/mo; return label generation, supplier reconciliation, deposit tracking

Generated from docs/plan/paid/core-return-logistics/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid system for managing return shipments of cores (parts/components) back to suppliers, with tracking, reconciliation, and deposit refund automation.

The problem

Used cores must return to suppliers; tracking is manual, deposits are lost, and reconciliation is chaos.

What it does

• Create return shipment for used cores (reverse logistics)
• Generate return label (uses carrier-integrations or custom return address)
• Track return shipment back to supplier
• Reconcile returned core with original order (match serial number or SKU)
• Trigger supplier refund/credit when return is received
• Manage return deposit tracking (customer paid deposit, refunded on successful return)
• Audit trail: all return states, decisions, refunds

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.

• Quality inspection — we don’t grade returned cores. Reason: manual or vendor-specific inspection.
• Supplier settlement — we don’t invoice supplier; merchant reconciles manually. Reason: financial reconciliation outside scope.

Data model

New tables: ReturnShipment {id, orderId, coreProductId, returnTrackingNumber, returnLabelPdf, status (‘pending_return’|‘in_transit_return’|‘received_by_supplier’), depositAmount (minor units), depositRefundedAt, createdAt, receivedAt}. No migration.

API

• POST /api/returns
• GET /api/returns/:id
• POST /api/returns/:id/tracking
• POST /api/returns/:id/received
• POST /api/returns/:id/refund-deposit

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

Admin

Return request form: select order and core product. Return tracking: view label, track shipment, record receipt.

The seam — why this is paid

Core owns: refund mechanics, return object, status transitions. Paid owns: return logistics, carrier integration, supplier communication.

Support commitment: logistics SLA, supplier data integration, financial reconciliation

Dependencies

• Order infrastructure
• carrier-integrations (for return labels)
• Refund system

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.

• Creating return for order #123 generates return label with carrier
• Return tracking shows status progression from pending to delivered
• Marking return as received sets status to ‘received_by_supplier’ and triggers deposit refund

Risks

Deposit not refunded: supplier receives core but refund never issued; mitigation: automated trigger on ‘received_by_supplier’ status. Serial number mismatch: wrong core shipped back; mitigation: audit trail validates SKU/serial on receipt.

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.