Music Store Management Platform Domain Design: Rentals # 1. Overview The Rentals domain manages instrument rental contracts, recurring billing, and rent-to-own tracking. Rentals are one of the most financially complex areas of the platform due to recurring Stripe subscriptions, multi-rental billing consolidation, and rent-to-own equity calculations. # 2. Rental Types Type Description Month-to-month Standard rental — continues until returned or cancelled. No purchase obligation. Rent-to-own A percentage of each payment applies toward purchase price. Customer can buy out at any time. Short-term Hourly, daily, or weekly rental. Flat fee, no subscription. Common for events. Lease purchase Fixed-term contract with defined end purchase price. # 3. Database Schema ## 3.1 rental Column Type Notes id uuid PK company_id uuid FK account_id uuid FK Billing account member_id uuid FK Member who has the instrument inventory_unit_id uuid FK Specific instrument rented rental_type enum month_to_month | rent_to_own | short_term | lease_purchase status enum active | returned | cancelled | completed start_date date end_date date Null for open-ended rentals monthly_rate numeric(10,2) Monthly charge amount deposit_amount numeric(10,2) Security deposit collected deposit_returned boolean billing_group varchar Groups rentals for consolidated billing stripe_subscription_id varchar Stripe subscription reference stripe_subscription_item_id varchar Line item if consolidated rto_purchase_price numeric(10,2) Rent-to-own: full purchase price rto_equity_percent numeric(5,2) % of payment applied to equity rto_equity_accumulated numeric(10,2) Total equity built toward purchase notes text legacy_id varchar AIM rental contract ID created_at timestamptz ## 3.2 rental_payment Records each individual payment made against a rental — populated via Stripe webhook events. id, rental_id, account_id, stripe_invoice_id, stripe_payment_intent_id,amount, rto_equity_applied, payment_date, status (paid|failed|refunded), created_at # 4. Rent-to-Own Logic When a rental is of type rent_to_own, each payment applies a percentage toward the purchase price. - rto_equity_accumulated increases by (monthly_rate × rto_equity_percent) each payment - Buyout amount = rto_purchase_price − rto_equity_accumulated - Staff can offer buyout at any time — triggers inventory_unit status change to 'sold' - On buyout, Stripe subscription is cancelled and a one-time charge is created for remaining balance - Invoice shows accumulated equity and remaining buyout balance # 5. Billing Consolidation ## 5.1 Consolidated Billing When billing_group is set to the same value on multiple rentals for the same account, they share one Stripe subscription with multiple line items. One charge per month covers all grouped rentals. ## 5.2 Split Billing When billing_group is null, the rental has its own independent Stripe subscription. Useful when a customer wants rentals charged on different dates. ## 5.3 Adding a Rental Mid-Cycle - If consolidating: add new line item to existing subscription — Stripe prorates automatically - If split: create new standalone subscription with requested billing date - Invoice shows prorated amount for partial first month # 6. Return Workflow - Staff records return — captures condition assessment - inventory_unit status updated to 'available' (or 'in_repair' if damage found) - Stripe subscription cancelled or line item removed - Deposit refund processed if applicable — logged in audit trail - Final invoice generated for any partial month charges - If damage found, repair ticket created automatically and linked to rental record