Core Exchange Management (Mechanics)

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €34/mo; core deposit enforcement, return logistics, credit reconciliation

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

Manage core (used part) deposits and returns for mechanical shops. Charge deposit at checkout for parts that require core return (alternators, starters, etc.). Track returns, enforce refund reversal if customer doesn’t return core within 30 days. Admin inspects received cores, approves quality, and reverses deposit. Reconciliation dashboard shows deposit vs refund variance.

The problem

Shops lose money when customers don’t return used cores after purchasing rebuilt parts. A €50 core deposit is charged at checkout, but if the customer never returns the old part, the deposit should be forfeited after 30 days. Without automation, staff forget, deposits get lost, and shops can’t track profitability.

What it does

• Core products defined in catalog (charge deposit at checkout as separate line item)
• Deposit charged as separate order line (e.g., €30 core deposit)
• Customer initiates return within 30 days, gets prepaid shipping label
• Staff marks core received (status: pending inspection)
• Staff inspects quality (score 1-10); approves or rejects
• Approved core: deposit reversed (refund to customer)
• Rejected core: deposit forfeited, core scrapped
• Auto-reverse job: forfeits deposit 30+ days after order if not returned
• Core inventory tracking (received, inspected, approved, ready to resale)
• Reconciliation report (deposits charged vs refunds issued vs forfeited)

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.

• Shipping label generation — use third-party shipping service. Reason: integration per provider, not this scope.
• Refurbishing time estimation — varies by part, requires manual estimate. Reason: business logic varies.
• Automatic core quality grading — requires ML or human inspection; we provide inspection UI only. Reason: liability; humans must decide.

Data model

New tables: core_products (coreProductId, partId, coreName, depositAmount (minor units), max_age_for_refund (days)). Order schema: add coreDeposits array [{coreProductId, depositAmount, depositId, status}]. core_returns (returnId, orderId, coreProductId, depositId, status (pending/received/inspected/approved/rejected), received_date, notes). core_inventory (coreId, coreProductId, condition (received/inspected/approved/ready_for_resale/scrapped), quality_score, created_at). Audit: all deposits, refunds, reversals. Migration: add tables + foreign keys to relational; blob storage nests objects.

API

• GET /api/products/{productId}/core-deposit
• GET /api/orders/{orderId}/core-deposits
• POST /api/core-returns
• GET /api/customers/{customerId}/core-returns
• POST /api/admin/core-returns/{returnId}/receive
• POST /api/admin/core-returns/{returnId}/inspect
• POST /api/admin/core-returns/{returnId}/approve
• GET /api/admin/core-inventory
• POST /api/admin/core-deposits/auto-reverse
• GET /api/admin/core-reconciliation-report

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

Admin

Core product setup (assign deposit amount to product). Return inbox (shows pending returns, expected arrival). Inspection queue (received cores, quality form). Core inventory (condition status, ready to resale). Reconciliation dashboard (deposits charged vs refunds vs forfeited, variance report). Auto-reverse settings (days until forfeit, cron schedule).

The seam — why this is paid

Core owns: order extensions, audit logging, webhook system, deposit tracking. Paid pack owns: return workflow orchestration, inspection queue, auto-reversal rules, reconciliation analytics.

Support commitment: core deposit accounting, refund-reversal workflows, return SLA

Dependencies

• Order system
• Audit log
• Webhook system
• Product catalog (core product definitions)
• Scheduled job system (for auto-reverse)

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.

• Adding core product to order charges €30 deposit as separate line item on order
• Customer initiates return within 30 days; gets prepaid shipping label (via third-party integration)
• Staff receives core, clicks ‘Receive’; status moves to pending inspection
• Staff inspects quality 8/10, approves; customer deposit refunded
• Customer initiates return 35 days after purchase; auto-reverse job forfeits deposit
• Reconciliation report: deposits €1200, refunds €950, forfeited €250 (within 7 days)
• Rejected core (quality < 3/10) stays in inventory as scrap; deposit not reversed
• Two cores on same order: customer returns one; one refunded, one forfeited after 30 days
• Webhook fires when deposit auto-reversed; can trigger billing alert
• Core inventory shows 5 approved cores ready to resale

Risks

Deposit never charged to order: customer leaves, refund can’t be reversed later. Auto-reverse job runs twice: deposit reversed twice (idempotency bug). Staff marks core received but it never arrived: false positive reversal. Quality inspection subjective: approval variance between staff. Return deadline interpreted wrong (30 days from order vs 30 days from shipped): off-by-one refund reversals.

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.