Simple Agility Commerce and Financial Reconciliation Lifecycle

Part of the Simple Agility stack. This contract defines the canonical data flow, event schemas, and monetary reconciliation mechanics spanning inbound inventory sourcing, physical warehouse management (Stockroom), marketplace sales channels (eBay, Amazon FBA, local), payout settlement, and double-entry financial accounting (SA-10, SA-11).

This page is the authoritative architectural contract binding Stockroom (~/source/stockroom), the future dedicated accounting engine (simple-agility-accounting), and any agents operating across the commerce domain.

sequenceDiagram
    autonumber
    actor Supplier as Estate / Thrift / Haul
    participant SR as Stockroom (WMS)
    participant Mkt as Marketplaces (eBay/FBA)
    participant Ship as Carrier / PirateShip
    participant Bank as Business Bank Account
    participant Ledger as Accounting Engine (General Ledger)

    Note over Supplier,SR: Stage 1: Inbound Sourcing & Cost Allocation
    Supplier->>SR: Physical goods purchased (Total cost: \$100.00)
    SR->>SR: Create Acquisition (Uniform split + overrides)
    SR-->>Ledger: Emit ItemAcquiredEvent (Dr Inventory Asset, Cr Cash/Card)

    Note over SR,Mkt: Stage 2: Listing & Active Inventory Holding
    SR->>Mkt: Publish Channel Listings (eBay Custom Label: I-<SKU>)
    opt Non-Sale Disposition (Damage / Donation)
        SR->>SR: Mark Disposed (Reason: DAMAGED / DONATED)
        SR-->>Ledger: Emit ItemDisposedEvent (Dr Loss/Expense, Cr Inventory Asset)
    end

    Note over Mkt,SR: Stage 3: Order Realization & Customer Payment
    Mkt->>SR: Order Paid webhook / sync (Price: \$30.00, Ship: \$5.00)
    SR->>SR: Create Sale (Status: ACTIVE, fees estimated)
    SR-->>Ledger: Emit ItemSoldEvent (Dr Mkt Receivable, Cr Revenue)

    Note over SR,Ship: Stage 4: Warehouse Fulfillment & Postage
    SR->>Ship: Pick & Purchase Postage (Media Mail: \$3.85)
    SR->>SR: Mark SHIPPED (Postage finalized, item exits crate)
    SR-->>Ledger: Emit ItemShippedEvent (Dr COGS, Cr Inventory Asset#59; Dr Postage, Cr Cash/Card)

    Note over Mkt,Bank: Stage 5: Settlement & Payout Reconciliation
    Mkt->>Bank: Lump-Sum Payout Disbursement (\$142.15 net)
    Bank-->>Ledger: Bank Transaction (Deposit: \$142.15)
    Mkt-->>Ledger: Ingest Settlement Statement (Orders, Returns, Subscriptions)
    Ledger->>Ledger: Reconcile Payout (Clear Mkt Receivable, allocate store fees & ad spend)

1. Architectural Principles & Boundaries

The commerce lifecycle adheres to three architectural invariants:

1. Separation of Physical Operations and Financial Ledger (SA-10):
   • Stockroom owns physical inventory reality: barcode scanning, shelf/crate locations (L-<code>), item condition grades, photography, triage pricing, eBay sync, and pick/pack workflows.
   • The Accounting Engine owns financial reality: the double-entry general ledger, chart of accounts, tax depreciation, sales tax remittance tracking, and formal P&L statements.
   • Stockroom emits immutable business events; it does not maintain debit/credit ledger tables.
2. Integer Cent Precision:
   • Every monetary amount across all databases, APIs, event payloads, and reports is strictly stored and calculated as integer cents (total_cost_cents, price_cents, fees_cents, postage_cents, net_cents).
   • Floating-point representations for currency are strictly prohibited to prevent fractional rounding drift.
3. Universal Audit Traceability:
   • Every financial journal entry points to a causal event ID, an item SKU (I-<SKU>), an acquisition record (A-<ID>), and where applicable, an external marketplace order or settlement ID.

2. The 5-Stage Commerce Lifecycle

Stage 1: Inbound Sourcing & Cost Basis Allocation

When inventory is purchased (from garage sales, thrift stores, estate liquidations, or library auctions), an Acquisition is created in Stockroom.

• Uniform Per-Unit Cost Split: The default mechanism divides total purchase cost equally across all manifest items:

Any remainder cents from integer division are assigned to the first item to maintain exact balance equality (\sum \text{item.cost\_cents} = \text{acquisition.total\_cost\_cents}).

• Selective Manual Overrides: If a lot contains an obvious standout (e.g., a rare vintage book worth $150 in a $50 box of 25 books), the operator can override that item's cost basis (e.g. to $30.00). Stockroom automatically rebalances the remaining $20.00 equally across the other 24 items ($0.83 each).
• Ledger Impact: Emits ItemAcquiredEvent.
  • Debit: 1200 Inventory Asset
  • Credit: 1010 Operating Cash (or 2010 Credit Card Payable)

Stage 2: Inventory Holding & Non-Sale Exits

While items sit in warehouse storage (assigned to crates or locations), physical events may occur before sale:

• Item Moves & Cycle Counts: Moving an item between crates or locations is an operational change that emits an internal LocationEvent with zero general ledger impact.
• Non-Sale Dispositions (Shrinkage, Damage, Donations, Personal Use): If an item is damaged in storage, discovered to be defective, donated to charity, or withdrawn by the owner, it exits inventory through an explicit disposition action with a mandatory reason code:

Stage 3: Marketplace Realization (Sale Event)

When a customer purchases an item on eBay, Amazon, or locally:

• Stockroom creates an active SaleEntity linked to the item SKU.
• Financial terms are captured in integer cents: price_cents (gross sale price), shipping_charged_cents (postage paid by buyer), and fees_cents (estimated marketplace commissions).
• The item status transitions from listed to sold, automatically queuing delist actions across any other channels.
• Ledger Impact: Emits ItemSoldEvent.
  • Debit: 1020 Marketplace Clearing (eBay/Amazon Receivable) (\text{price} + \text{shipping\_charged} - \text{fees})
  • Debit: 5030 Marketplace Commission & Payment Fees (\text{fees})
  • Credit: 4010 Gross Sales Revenue (\text{price})
  • Credit: 4020 Shipping Revenue Charged (\text{shipping\_charged})

Stage 4: Warehouse Fulfillment & Shipping

When the order is packaged and dispatched:

• The operator picks the item using Stockroom's mobile scan bar or handheld scanner.
• Exact shipping postage is finalized (e.g. USPS Media Mail label purchased via PirateShip or eBay Labels).
• Stockroom transitions the sale to shipped and records shipped_at and postage_cents.
• Ledger Impact: Emits ItemShippedEvent.
  • Recognition of COGS:
    • Debit: 5010 Cost of Goods Sold (COGS) (\text{item.cost\_cents})
    • Credit: 1200 Inventory Asset (\text{item.cost\_cents})
  • Recognition of Actual Outbound Freight:
    • Debit: 5020 Shipping Postage Expense (\text{postage\_cents})
    • Credit: 1010 Operating Cash (or 2010 Credit Card / Carrier Account) (\text{postage\_cents})

Stage 5: Settlement & Payout Reconciliation

Marketplaces do not disburse funds order-by-order. Periodically (daily or bi-weekly), eBay Managed Payments or Amazon disbursements deposit a consolidated lump sum into the business bank account.

• Two-Tier Settlement Reconciliation:
  1. The lump-sum deposit clears the accrued balance in 1020 Marketplace Clearing.
  2. Periodic marketplace settlement statements (CSV or API report) are matched against the disbursement.
  3. Platform overhead that cannot be attributed to a single item (e.g. eBay monthly store subscriptions, promoted listing ad clicks, dispute fees, or platform shipping label billing) is booked directly to operating expenses:
     • Debit: 1010 Operating Cash (Bank Account) (\text{actual deposit received})
     • Debit: 6010 Marketplace Subscriptions & Overhead (\text{monthly store fee})
     • Debit: 6020 Advertising & Promoted Listings (\text{ad campaign fees})
     • Credit: 1020 Marketplace Clearing (\text{clearing individual order accruals})

3. Canonical Event Schemas

Stockroom emits these structured events as JSON payloads over its event bus / append-log:

3.1 ItemAcquiredEvent

{
  "event_id": "01M4XR11A8B2C3D4E5F6G7H8J9",
  "event_type": "ItemAcquired",
  "occurred_at": "2026-10-14T14:30:00Z",
  "acquisition_id": "01M4XR00A1B2C3D4E5F6G7H8J0",
  "item_id": "01M4XR05X9Y8Z7W6V5U4T3S2R1",
  "sku": "I-00482",
  "source_name": "Sacramento Estate Sale",
  "source_type": "estate_sale",
  "cost_cents": 250,
  "cost_overridden": false,
  "category": "book",
  "title": "The Art of Computer Programming, Vol 1"
}

3.2 ItemSoldEvent

{
  "event_id": "01M4XR22B9C8D7E6F5G4H3J2K1",
  "event_type": "ItemSold",
  "occurred_at": "2026-10-14T18:15:00Z",
  "sale_id": "01M4XR20A1B2C3D4E5F6G7H8J1",
  "item_id": "01M4XR05X9Y8Z7W6V5U4T3S2R1",
  "sku": "I-00482",
  "channel": "ebay",
  "external_order_id": "14-11892-49201",
  "price_cents": 3500,
  "shipping_charged_cents": 500,
  "fees_cents": 485,
  "fees_estimated": true,
  "expected_net_cents": 3515
}

3.3 ItemShippedEvent

{
  "event_id": "01M4XR33C1D2E3F4G5H6J7K8L9",
  "event_type": "ItemShipped",
  "occurred_at": "2026-10-15T09:45:00Z",
  "sale_id": "01M4XR20A1B2C3D4E5F6G7H8J1",
  "item_id": "01M4XR05X9Y8Z7W6V5U4T3S2R1",
  "sku": "I-00482",
  "cost_cents": 250,
  "postage_cents": 385,
  "carrier": "USPS",
  "tracking_number": "9449009205568123456789"
}

3.4 ItemDisposedEvent

{
  "event_id": "01M4XR44D5E6F7G8H9J0K1L2M3",
  "event_type": "ItemDisposed",
  "occurred_at": "2026-10-16T11:00:00Z",
  "item_id": "01M4XR09W1X2Y3Z4A5B6C7D8E9",
  "sku": "I-00483",
  "cost_cents": 250,
  "reason_code": "DAMAGED_SCRAP",
  "notes": "Dropped during warehouse reorganization; cracked casing."
}

4. Standard Chart of Accounts & Journal Entries

The financial engine maps commerce events to the standard small-business Chart of Accounts:

5. Worked Numerical Settlement Example

Consider a concrete transaction flow demonstrating exact cent balancing:

1. Inbound Sourcing:
   • Operator buys a box of 10 books at an estate sale for $25.00 using an operating credit card.
   • Uniform split allocates $2.50 (250 cents) to SKU I-00482.
   • Journal Entry: Dr 1200 Inventory Asset $25.00 | Cr 2010 Credit Card Payable $25.00.
2. Item Sale (eBay):
   • Item I-00482 sells on eBay for $35.00 with $5.00 shipping paid by buyer (Total collected: $40.00).
   • eBay estimates fees at 13.25% + $0.40 = $5.70 (570 cents).
   • Journal Entry: Dr 1020 Marketplace Clearing $34.30 | Dr 5030 Marketplace Fees $5.70 | Cr 4010 Gross Revenue $35.00 | Cr 4020 Shipping Revenue $5.00.
3. Fulfillment (Shipping):
   • Operator packs the book and buys Media Mail postage for $3.92 via PirateShip.
   • Journal Entry 1 (COGS): Dr 5010 COGS $2.50 | Cr 1200 Inventory Asset $2.50.
   • Journal Entry 2 (Postage): Dr 5020 Shipping Expense $3.92 | Cr 1010 Operating Checking $3.92.
   • Realized Gross Profit on Order: \$35.00 + \$5.00 - \$2.50 - \$5.70 - \$3.92 = \mathbf{\$27.88}.
4. Marketplace Settlement (Batch Payout):
   • eBay Managed Payments sends a payout to Checking for $142.15, covering this order plus 4 others, while deducting a $24.95 monthly eBay store subscription fee.
   • Journal Entry: Dr 1010 Operating Checking $142.15 | Dr 6010 Store Subscriptions $24.95 | Cr 1020 Marketplace Clearing $167.10.
   • The receivable clears to $0.00, cash is in the bank, and store overhead is correctly classified as an operational expense.

See Also

• SimpleAgilityStackHub — Architecture and ownership principles of Simple Agility.
• SimpleAgilityDecisionLog — Binding decisions SA-10 (decoupled accounting) and SA-11 (commerce lifecycle).
• ResellingHub — Business rules, condition taxonomy, and customer spotlight flow.
• StockroomIntakeInventoryPricingDesign — Technical specification for Stockroom's WMS and database schema.
• SimpleAgilityAgentCoordination — Cross-repo agent coordination protocol and initiatives ledger.