Document the critical business logic for load lifecycle and billing workflows in laneweaverTMS. Use when implementing load status transitions, billing workflows, financial calculations, TONU handling, or quick pay features.
Provides business logic for load lifecycle and billing workflows in laneweaverTMS. Use when implementing load status transitions, billing workflows, financial calculations, TONU handling, or quick pay features.
/plugin marketplace add linehaul-ai/linehaulai-claude-marketplace/plugin install laneweaver-tms-agents@linehaulai-claude-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Use when:
uncovered → assigned → dispatched → at_origin → in_transit → at_destination → delivered
| Current Status | Valid Next Status | Trigger |
|---|---|---|
uncovered | assigned, cancelled | Carrier assignment or cancellation |
assigned | dispatched, uncovered, cancelled | Dispatch confirmation or carrier bounce |
dispatched | at_origin, assigned, cancelled | Carrier arrives or dispatch cancelled |
at_origin | in_transit, cancelled | Pickup completed, load departs |
in_transit | at_destination, cancelled | Approaching delivery destination |
at_destination | delivered, cancelled | Delivery completed |
delivered | (terminal state) | No further transitions |
cancelled | (terminal state) | No further transitions |
uncovered → assigned
carrier_id is set on the loadcarrier_rate is establishedassigned → dispatched
load_cognitiondispatched → at_origin
at_origin → in_transit
in_transit → at_destination
at_destination → delivered
Cancellation can happen from ANY non-terminal status:
load_cancellations recordloads.is_cancelled = true (synced via trigger)-- Example cancellation logic
INSERT INTO load_cancellations (load_id, reason, cancelled_by)
VALUES ($1, $2, $3);
-- Trigger auto-syncs is_cancelled flag:
UPDATE loads SET is_cancelled = true WHERE id = $1;
delivered → POD Received → Carrier Bill Received → Invoice Ready → Customer Invoiced → Carrier Paid
The load_billing table tracks billing milestones for each load:
| Field | Purpose |
|---|---|
pod_received | Proof of Delivery document received |
pod_received_at | Timestamp when POD was received |
carrier_bill_received | Carrier's invoice/rate confirmation received |
carrier_bill_received_at | Timestamp when carrier bill was received |
invoice_ready | Generated column: pod_received AND carrier_bill_received |
A load is ready for customer invoicing when BOTH:
-- Generated column auto-calculates invoice readiness
invoice_ready BOOLEAN GENERATED ALWAYS AS (pod_received AND carrier_bill_received) STORED
After invoice_ready = true:
customer_invoices recordload_idcustomer_rate)invoice_status to initial stateAfter carrier bill is received:
grossProfit = customerRate - carrierRate
grossMarginPct = (grossProfit / customerRate) * 100
netProfit = (customerRate + customerAccessorials) - (carrierRate + carrierAccessorials)
Basic Load:
Customer Rate: $2,500
Carrier Rate: $2,000
Gross Profit: $500
Gross Margin: 20%
Load with Accessorials:
Customer Rate: $2,500
Customer Accessorials: $150 (detention, lumper)
Carrier Rate: $2,000
Carrier Accessorials: $100 (detention)
Revenue: $2,650 ($2,500 + $150)
Cost: $2,100 ($2,000 + $100)
Net Profit: $550
Net Margin: 20.75%
-- View for financial calculations
CREATE OR REPLACE VIEW public.loads_with_financials
WITH (security_invoker = on)
AS
SELECT
l.id,
l.load_number,
l.customer_rate,
l.carrier_rate,
-- Gross profit (base rates only)
(l.customer_rate - COALESCE(l.carrier_rate, 0)) AS gross_profit,
-- Gross margin percentage
CASE
WHEN l.customer_rate > 0
THEN ((l.customer_rate - COALESCE(l.carrier_rate, 0)) / l.customer_rate * 100)
ELSE 0
END AS gross_margin_pct,
-- Accessorial totals
(SELECT COALESCE(SUM(amount), 0)
FROM customer_accessorials
WHERE load_id = l.id AND deleted_at IS NULL) AS customer_accessorials_total,
(SELECT COALESCE(SUM(amount), 0)
FROM carrier_accessorials
WHERE load_id = l.id AND deleted_at IS NULL) AS carrier_accessorials_total,
-- Net profit (including accessorials)
((l.customer_rate + (SELECT COALESCE(SUM(amount), 0) FROM customer_accessorials WHERE load_id = l.id AND deleted_at IS NULL)) -
(COALESCE(l.carrier_rate, 0) + (SELECT COALESCE(SUM(amount), 0) FROM carrier_accessorials WHERE load_id = l.id AND deleted_at IS NULL))) AS net_profit
FROM public.loads l
WHERE l.deleted_at IS NULL;
TONU occurs when a load is cancelled after a carrier has been assigned and has committed resources (dispatched driver, positioned truck, etc.).
TONU may be charged when:
assigned or later status)load_cancellations record includes TONU details-- load_cancellations table captures TONU
CREATE TABLE public.load_cancellations (
id UUID DEFAULT gen_random_uuid() NOT NULL,
load_id UUID NOT NULL,
reason TEXT,
tonu_amount NUMERIC(10,2), -- Amount charged for TONU
cancelled_at TIMESTAMPTZ DEFAULT now() NOT NULL,
cancelled_by INT4,
-- ... audit columns
);
Quick Pay is an accelerated payment option where carriers receive payment faster than standard terms (typically net 30) in exchange for a fee.
| Standard Terms | Quick Pay Terms | Typical Fee |
|---|---|---|
| Net 30 | 1-2 days | 1-2% of payment |
| Net 45 | 1-2 days | 2-3% of payment |
-- carrier_bills table tracks quick pay requests
CREATE TABLE public.carrier_bills (
id UUID DEFAULT gen_random_uuid() NOT NULL,
load_id UUID NOT NULL,
carrier_id UUID NOT NULL,
bill_amount NUMERIC(10,2) NOT NULL,
bill_status public.carrier_bill_status NOT NULL,
-- Quick pay fields
quick_pay_requested BOOLEAN DEFAULT false,
quick_pay_fee_pct NUMERIC(5,2), -- e.g., 2.00 for 2%
quick_pay_fee_amount NUMERIC(10,2),
scheduled_payment_date DATE,
paid_at TIMESTAMPTZ,
-- ... audit columns
);
quick_pay_requested = trueQuick Pay Fee = Bill Amount * Quick Pay Fee Percentage
Net Payment = Bill Amount - Quick Pay Fee
Example:
Bill Amount: $2,000
Quick Pay Fee %: 2%
Quick Pay Fee: $40
Net Payment: $1,960
quick_pay_requested = true for efficient filtering| Table | Purpose |
|---|---|
loads | Core load record with status, rates |
tenders | Customer tender/order source |
stops | Pickup and delivery locations |
load_billing | POD/carrier bill tracking, invoice ready |
| Table | Purpose |
|---|---|
load_cancellations | Cancellation records with TONU amounts |
| Table | Purpose |
|---|---|
customer_invoices | Customer invoices for loads |
carrier_bills | Carrier bills/invoices to pay |
customer_accessorials | Additional customer charges |
carrier_accessorials | Additional carrier charges |
Load Status Management:
[ ] Validate status transitions against allowed transitions table
[ ] Record status change timestamps
[ ] Sync is_cancelled flag via trigger when load_cancellations inserted
[ ] Prevent invalid transitions (e.g., uncovered → delivered)
Billing Workflow:
[ ] Track POD receipt separately from carrier bill receipt
[ ] Use generated column for invoice_ready calculation
[ ] Create customer invoice only when invoice_ready = true
[ ] Link all billing records to load_id
Financial Calculations:
[ ] Always use NUMERIC(10,2) for money fields
[ ] Include accessorials in net profit calculations
[ ] Handle null carrier_rate (uncovered loads)
[ ] Calculate margin percentages safely (avoid division by zero)
TONU Handling:
[ ] Only apply TONU after carrier assignment
[ ] Record TONU amount in load_cancellations
[ ] Bill TONU to customer
[ ] Pay TONU to carrier (if applicable)
Quick Pay:
[ ] Carrier-initiated request only
[ ] Calculate fee based on agreed percentage
[ ] Deduct fee from carrier payment
[ ] Track as revenue/margin improvement
Remember: This skill focuses on business logic patterns. For database schema implementation details (columns, indexes, constraints), refer to the laneweaver-database-design skill.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.