LunarFront — Small Business Management Platform Domain Design: Consignment Version 1.0 | Draft # 1. Overview The Consignment domain manages inventory that is owned by a third party (the consignor) and sold on their behalf by the store. The store earns a commission on each sale and owes the consignor the remainder. Consignment is common in music retail — individuals and local dealers bring in used instruments, vintage gear, or specialty items for the store to sell. Consignment items appear in the regular product catalog and POS — customers do not see any difference between store-owned and consignment inventory. The distinction is purely internal for accounting, commission tracking, and consignor settlement. # 2. Core Concepts ## 2.1 Consignor A consignor is the person or business who owns the item. They are represented as an `account` in the system — they may also be a customer who buys from the store. Using the account entity means consignors have payment info on file for settlement payouts. ## 2.2 Consignment Detail A `consignment_detail` record links a product to its consignor and defines the commission terms. If a product has a consignment_detail, it is consignment inventory. If not, it is store-owned. ## 2.3 Commission The store's cut of a consignment sale. Defined as a percentage on the consignment_detail record. Example: 30% commission means the store keeps 30% of the sale price, the consignor receives 70%. ## 2.4 Minimum Price Consignors may set a floor price below which the item cannot be sold without their approval. Stored on consignment_detail. POS enforces this — if a staff member attempts to sell below min price, the system warns and requires override. ## 2.5 Settlement Periodic payout to the consignor for their sold items. Typically monthly. The store reviews all consignment sales for the period, deducts commission, and pays the consignor the balance. # 3. Database Schema ## 3.1 consignment_detail Extension table on product — one record per consignment product. Column | Type | Notes id | uuid PK | product_id | uuid FK → product | The consignment item company_id | uuid FK → company | Tenant scoping consignor_account_id | uuid FK → account | Who owns the item commission_percent | numeric(5,2) | Store's cut — e.g. 30.00 = 30% min_price | numeric(10,2) | Nullable — floor price set by consignor agreement_date | date | When consignment agreement was made notes | text | Terms, special conditions is_active | boolean | False when item returned to consignor unsold created_at | timestamptz | ## 3.2 consignment_settlement Records each payout to a consignor. Groups all consignment sales for a period. Column | Type | Notes id | uuid PK | company_id | uuid FK | consignor_account_id | uuid FK → account | period_start | date | Settlement period start period_end | date | Settlement period end total_sales | numeric(10,2) | Sum of sale prices for period total_commission | numeric(10,2) | Store's cut total_payout | numeric(10,2) | Amount owed to consignor (sales - commission) status | enum | pending, paid, cancelled paid_date | date | When consignor was paid paid_via | varchar | check, ach, cash, account_credit notes | text | created_by | uuid FK | Employee who created settlement created_at | timestamptz | ## 3.3 consignment_settlement_line Individual sold items included in a settlement. Column | Type | Notes id | uuid PK | settlement_id | uuid FK → consignment_settlement | product_id | uuid FK → product | transaction_id | uuid FK → transaction | The sale transaction sale_price | numeric(10,2) | What it sold for commission_amount | numeric(10,2) | Store's cut on this item consignor_amount | numeric(10,2) | Consignor's payout on this item sold_date | date | created_at | timestamptz | # 4. Consignment Lifecycle Status | Description intake | Item received from consignor — product created, consignment_detail linked, inventory_unit created with status 'available' listed | Item is in the catalog and available for sale at POS sold | Item sold — commission calculated, included in next settlement settled | Consignor has been paid for the item returned | Item returned to consignor unsold — consignment_detail.is_active set to false, inventory_unit retired expired | Agreement period ended without sale — store contacts consignor to pick up or renew # 5. Key Workflows ## 5.1 Consignment Intake - Consignor brings item to store (or store picks up) - Staff creates account for consignor if not existing - Staff creates product entry for the item (serialized, with description, photos) - Staff creates consignment_detail — links product to consignor account, sets commission %, min price - inventory_unit created with status 'available' - Consignment agreement printed or emailed — includes item description, commission terms, min price, store contact ## 5.2 Consignment Sale - Item sold at POS like any other product - POS checks for consignment_detail on the product - If min_price set and sale price < min_price → warning, requires manager override - Transaction recorded normally - Consignment sale flagged for inclusion in next settlement - Journal entry differs from regular sale — see Accounting section ## 5.3 Settlement - Manager runs settlement report for a period (e.g. monthly) - System groups all consignment sales by consignor for the period - For each consignor: total sales, total commission, total payout - Manager reviews and approves settlement - Settlement record created with line items - Consignor paid via check, ACH, cash, or account credit - Settlement marked paid with date and method ## 5.4 Unsold Item Return - Consignor requests item back, or agreement expires - Staff updates consignment_detail.is_active = false - inventory_unit.status set to 'retired' - Product deactivated (is_active = false) - No financial transaction — item was never store property # 6. POS Integration - Consignment items appear in product search and catalog like any other item - No visual distinction to customers - Staff sees a "Consignment" badge on the product detail in POS - Min price enforced — POS blocks sale below min_price without override - Discounts on consignment items: commission calculated on actual sale price (after discount), not list price - Receipt shows the item like any other product — no consignment info visible to customer # 7. Accounting — Journal Entry Differences Consignment sales produce different journal entries than regular sales because the store never owned the inventory. ## 7.1 Regular Sale (Store-Owned) Debit | Credit | Notes Cash/Stripe Clearing | Sales Revenue | Full sale price is revenue COGS | Inventory | Cost of item removed from inventory ## 7.2 Consignment Sale Debit | Credit | Notes Cash/Stripe Clearing | Consignment Payable | Consignor's portion — liability until settled Cash/Stripe Clearing | Commission Income | Store's commission — this is your revenue (no COGS entry) | (no inventory entry) | Store never owned the item — no cost basis ## 7.3 Consignment Settlement (Paying Consignor) Debit | Credit | Notes Consignment Payable | Cash/Bank | Liability cleared when consignor is paid ### New Chart of Accounts Entries Needed Code | Account Name | Type | Notes 2500 | Consignment Payable | Liability | Amounts owed to consignors for sold items 4600 | Commission Income — Consignment | Revenue | Store's commission on consignment sales # 8. Reporting Report | Description Consignment inventory | All active consignment items — consignor, list price, days listed Consignment sales by period | Items sold, sale price, commission, consignor payout Unsettled consignment | Sold items not yet included in a settlement — amounts owed Settlement history | Past settlements by consignor — dates, amounts, payment method Commission analysis | Commission earned by period — identifies how much consignment contributes to revenue Aging report | Consignment items listed for X days without selling — candidates for return or price reduction Consignor statement | Per-consignor report — items listed, items sold, commission, payouts — printable/emailable # 9. Business Rules - Consignment items are always serialized (each is a unique item with a consignment_detail) - Commission calculated on actual sale price after discounts, not list price - Min price enforced at POS — override requires manager role - Consignor cannot be paid until settlement is approved by manager - Settlement cannot include items from future dates - Returned items generate no financial transaction — no revenue, no COGS - Consignment_detail is soft-deleted (is_active = false), never hard deleted — preserves history - Consignor account follows same rules as any account — soft-delete only, financial history retained - Price reductions on consignment items should notify consignor (future: notification system)