lunarfront-app/planning/20_Domain_Consignment.md

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)