Content is user-generated and unverified.

Transportation Charges Module - New Enhancement User Stories

Overview

New enhancements to the existing transportation charges module to add seller credits, subhauler charges, drop-off handling, overpayment scenarios, and system integrations.

Epic 1: Seller Credits Management (New Enhancement)

User Story 1.1: Add Seller Credits

As a dispatcher
I want to add credits that reduce the amount billed to sellers
So that I can apply agreed-upon discounts or adjustments

Acceptance Criteria:

  1. When "Any Seller Credit?" is toggled to "Yes", display credit entry table
  2. Credit types available:
    • Late Pickup Credit
    • Other
    • Late Bill Credit (display only if already exists, cannot add new)
  3. For Late Pickup Credit:
    • Storage From Date (optional)
    • Storage To Date (optional)
    • Rate per day (optional)
    • Amount (mandatory)
    • If dates and rate provided, auto-calculate amount
    • Amount cannot exceed total storage charges
  4. For Other Credit:
    • Comments (mandatory)
    • Amount (mandatory)
    • Amount cannot exceed total bill amount
  5. Sum of all credits cannot exceed total bill amount
  6. Only one credit of each type allowed per bill
  7. Credits shall be reflected in total calculation but bill amount remains unchanged

Validation Rules:

  • Late Pickup Credit amount <= Sum of all storage charges (Period 1 + Period 2 + Negotiated)
  • Other Credit amount <= Total bill amount
  • Sum of all credits < Total bill amount (cannot equal or exceed)
  • Other Credit comments field: minimum 10 characters
  • Credit amounts must be positive numbers with up to 2 decimal places
  • If dates provided for Late Pickup Credit, end date >= start date
  • Duplicate credit type validation: show error "Credit type already exists"
  • Document upload mandatory for all credit types

User Story 1.2: Handle Late Bill Credit

As a dispatcher
I want the system to automatically apply late bill credits
So that charges added after seller billing window are handled correctly

Acceptance Criteria:

  1. On screen load, call Seller Billing API to check billing window status
  2. If seller billing window is closed and changes are made:
    • Automatically create Late Bill Credit entry
    • Credit amount = net change in charges (positive or negative)
    • Display as read-only in credits section
  3. Late Bill Credit cannot exceed total bill amount
  4. User cannot manually add Late Bill Credit type

Technical Requirements:

  • Seller Billing API endpoint: /api/v1/seller/billing-status/{sellerId}
  • Cache billing status for 5 minutes
  • Handle API failures gracefully - allow user to proceed with warning

Epic 2: Subhauler Additional Charges (New Enhancement)

User Story 2.1: Add Subhauler Charges

As a dispatcher
I want to add additional charges incurred by subhaulers
So that I can track all service costs

Acceptance Criteria:

  1. When "Any Additional Sub-hauler Charges?" is toggled to "Yes", display charges table
  2. Available charge types:
    • Dry Run
    • Second Stop Charges (Additional Stop)
    • Additional Labor Charges
    • Drop Off (only if Pick-up Required = YES and drop-off action completed)
  3. For each charge, capture:
    • Charge Type (dropdown)
    • Tow Provider (populated from system)
    • Bill to Seller (Yes/No dropdown)
    • Amount ($)
  4. Maximum amount for any subhauler charge: $1000 (hard stop)
  5. Include row delete (X) button for each charge
  6. Multiple charges of same type allowed except Drop Off (only one)
  7. Document upload mandatory for charges marked "Bill to Seller = Yes"

Validation Rules:

  • Amount validation: Must be > 0 and <= $1000
  • Hard stop with error message: "Subhauler charge cannot exceed $1000"
  • Tow Provider field cannot be empty
  • Drop Off charge type:
    • Only visible if drop-off action was completed
    • Only one Drop Off charge allowed per bill
    • Error if attempting to add second: "Only one drop-off charge allowed"
  • For Pick-up Required = NO lots: Drop Off option must not appear in dropdown
  • Document upload validation when Bill to Seller = Yes:
    • Check file exists before save
    • Accepted formats: PDF, JPG, PNG
    • Max file size: 5MB
    • Error message: "Document required for seller-billed charges"

User Story 2.2: Dry Run Charge with Contract Prefill

As a dispatcher
I want dry run charges to prefill from vendor contracts
So that I can quickly enter contracted rates

Acceptance Criteria:

  1. When Dry Run is selected as charge type:
    • System shall retrieve vendor contract rates
    • Prefill amount from contract if available
    • Allow manual override of prefilled amount
  2. Link dry run charges by lot number when multiple subhaulers involved
  3. Dry run charge shall be linked to the subhauler who attempted pickup

Technical Requirements:

  • Retrieve rates from Tow Provider Management system
  • Contract rate lookup timeout: 5 seconds
  • Default to manual entry if lookup fails

Epic 3: Drop-off Scenarios (New Enhancement)

User Story 3.1: Record Drop-off for Pick-up Required Lots

As a dispatcher
I want to record when a vehicle is dropped off instead of picked up
So that I can track delivery method and pay drop-off vendors

Acceptance Criteria:

  1. Display "Drop Off" action button for Pick-up Required = YES lots
  2. On button click, open dialog with:
    • Who is Dropping Off? (Pick-up Location/One Time Vendor radio)
    • Vendor selection dropdown (filtered by current yard)
    • For new vendor, capture:
      • Business Name (mandatory)
      • Phone Number (mandatory)
      • Email (optional)
      • Address (mandatory)
  3. System shall create new vendor record with type = "Drop Off"
  4. After drop-off recorded, enable "Drop Off" in subhauler charge types

Validation Rules:

  • Business Name: Required, 3-100 characters
  • Phone Number: Required, valid 10-digit format (XXX-XXX-XXXX or XXXXXXXXXX)
  • Email: If provided, must be valid email format
  • Address: Required, minimum 10 characters
  • Duplicate vendor check:
    • Check by phone number before creating new vendor
    • If exists, show message: "Vendor with this phone number already exists"
    • Allow user to select existing or create new
  • Vendor dropdown: Only show vendors who have previously dropped off at current yard
  • Drop Off button: Only visible when Pick-up Required = YES

User Story 3.2: Process Drop-off Commission Payment

As a dispatcher
I want to record and pay drop-off vendors
So that they are compensated for delivery service

Acceptance Criteria:

  1. When Drop Off charge is added in subhauler section:
    • Prefill vendor details from drop-off dialog
    • Allow editing of vendor details
    • Capture amount (max $1000)
    • Capture Bill to Seller (Yes/No)
  2. On Save & Submit:
    • Call Vendor Billing API to record charge
    • Upon successful recording, initiate automatic payment
    • Use check printer from user settings
    • Generate payment record in system

Technical Requirements:

  • Vendor Billing API: POST /api/v1/vendor-billing/charges
  • Include immediate_payment: true for drop-off charges
  • Check printer selection from user profile settings

User Story 3.3: Handle Pick-up Not Required Drop Charges

As a dispatcher
I want to record drop charges for seller-arranged deliveries
So that appropriate fees are billed to sellers

Acceptance Criteria:

  1. For Pick-up Required = NO lots:
    • Include "Drop Charge" field in main charges section
    • Drop charge is always billable to seller (no option to change)
    • Hide Drop Off option from subhauler charges dropdown
  2. Drop charge in main section follows standard charge validation rules
  3. No vendor selection or payment processing for these charges

Epic 4: Payment Exception Handling (New Enhancement)

User Story 4.1: Handle Overpayment Scenarios

As a dispatcher
I want the system to handle overpayments appropriately
So that excess amounts are tracked for refund processing

Acceptance Criteria:

  1. System shall calculate overpayment as: Total Payments - Total Charges
  2. When overpayment exists (payments > charges):
    • Display warning before save: "Payment exceeds charges by $[amount]. An exception will be created and can be closed once incoming payment is associated."
    • Require user acknowledgment to proceed
  3. On Save & Submit with overpayment:
    • Create all normal charge types
    • Add OVERPAID charge type for excess amount
    • OVERPAID amount = Total Payments - Total Charges
  4. OVERPAID charge properties:
    • Shows as read-only line item in charges display
    • Not billable to seller (system enforced)
    • Cannot be edited or deleted by user
    • Linked to same lot/bill number
  5. Display overpaid amount in UI after creation for reference

Validation Rules:

  • Overpayment calculation must be precise to 2 decimal places
  • Warning modal must block save until acknowledged
  • OVERPAID charge type:
    • Cannot be manually created by user
    • Cannot be modified after creation
    • Must always have "Bill to Seller = No"
  • If multiple payments exist, sum all payments for overpayment calculation
  • Overpayment amount must be > $0.00 to trigger OVERPAID creation

Epic 5: System Integration APIs (New Enhancement)

User Story 5.1: Check Management - SOLR Collection Integration

As a system
I want to integrate with OAC's SOLR collection for check management
So that check payment data can be searched and retrieved efficiently

Acceptance Criteria:

  1. Establish connection to OAC SOLR collection with proper authentication
  2. Implement search capabilities for:
    • Check number
    • Check date range
    • Vendor ID
    • Amount range
    • Check status (printed, void, cleared, etc.)
  3. Return check data including:
    • Check number
    • Payee information
    • Amount
    • Date issued
    • Status
    • Associated lot numbers
  4. Support pagination for large result sets
  5. Implement connection pooling and timeout handling

Technical Requirements:

  • SOLR query timeout: 10 seconds
  • Maximum results per page: 100
  • Connection retry logic: 3 attempts with exponential backoff
  • Index fields required: check_number, vendor_id, amount, issue_date, status, lot_number
  • Support wildcard searches for check numbers

User Story 5.2: Check Management - OAC Check Actions API Integration

As a system
I want to integrate with OAC APIs for check actions
So that users can perform check operations from within the application

Acceptance Criteria:

  1. Implement API integration for check actions:
    • Print check
    • Void check
    • Reissue check
    • Check inquiry
  2. For Print Check:
    • Send payment details to OAC
    • Receive check number in response
    • Update local records with check number
  3. For Void Check:
    • Send check number and void reason
    • Handle success/failure responses
    • Update check status locally
  4. For Reissue Check:
    • Void original check
    • Create new check with reference to original
  5. Handle all OAC API error responses with appropriate user messages

API Specifications:

  • Endpoint base: /oac/api/v1/checks/
  • Authentication: OAuth 2.0 bearer token
  • Request timeout: 30 seconds
  • Error handling: Map OAC error codes to user-friendly messages
  • Required headers: X-Correlation-ID for request tracking

User Story 5.3: Get Charges and Payments API

As an external system
I want to retrieve charges and payments by lot number
So that I can access financial data for reporting and reconciliation

Acceptance Criteria:

  1. Create REST API endpoint: GET /api/v1/charges-payments/{lotNumber}
  2. Response shall include:
    • All charge types and amounts
    • All payments with method details
    • Seller credits applied
    • Subhauler charges
    • Total calculations
    • Bill status
    • Created/modified timestamps
  3. Implement authentication and authorization
  4. Support JSON response format
  5. Include API versioning for backward compatibility

API Response Structure:

json
{
  "lotNumber": "string",
  "charges": {
    "tow": 0.00,
    "labor": 0.00,
    "gate": 0.00,
    "storage": [...],
    "tax": 0.00,
    "total": 0.00
  },
  "payments": [...],
  "sellerCredits": [...],
  "subhaulerCharges": [...],
  "status": "string",
  "timestamps": {...}
}

Non-Functional Requirements:

  • Response time: < 2 seconds
  • Rate limiting: 100 requests per minute per client
  • Audit trail for all API access

User Story 5.4: Seller Billing Kafka Integration

As a system
I want to publish events to Kafka for seller billing changes
So that the seller team is notified of invoice and credit updates in real-time

Acceptance Criteria:

  1. Publish Kafka events for:
    • New invoice creation
    • Invoice amount changes
    • Seller credit additions
    • Seller credit modifications
    • Invoice cancellations
  2. Event payload shall include:
    • Lot number
    • Invoice number
    • Change type (CREATE, UPDATE, DELETE)
    • Previous values (for updates)
    • New values
    • Timestamp
    • User who made the change
  3. Implement guaranteed delivery with acknowledgment
  4. Handle Kafka broker failures gracefully
  5. Include correlation ID for event tracking

Kafka Configuration:

  • Topic name: seller-billing-changes
  • Partition key: lot number
  • Message format: JSON with schema registry
  • Retention period: 7 days
  • Replication factor: 3
  • Delivery guarantee: At least once

User Story 5.5: Vendor Billing API Enhancement

As a vendor billing system
I want to support additional subhauler charge types
So that all transportation charges can be properly categorized and billed

Acceptance Criteria:

  1. Extend existing Vendor Billing API to support new charge types:
    • Dry Run
    • Second Stop Charges (Additional Stop)
    • Additional Labor Charges
    • Drop Off
  2. API request shall include:
    • Charge type (from above list)
    • Vendor ID
    • Amount
    • Bill to seller flag (true/false)
    • Lot number
    • Service date
    • Notes/description (optional)
  3. For Drop Off charges:
    • Include vendor details (name, phone, email, address)
    • Support immediate payment initiation flag
    • Include check printer selection
  4. Validate charge type against allowed values
  5. Return success response with transaction ID

API Endpoint Enhancement:

  • POST /api/v1/vendor-billing/charges
  • New charge_type enum values: DRY_RUN, SECOND_STOP, ADDITIONAL_LABOR, DROP_OFF
  • Validation: Amount must be > 0 and <= 1000
  • Response includes: transaction_id, payment_status (for drop-off)

User Story 5.6: Tow Provider Management API Enhancement

As a Tow Provider Management system
I want to support drop-off vendor creation and yard association
So that drop-off vendors can be properly managed and tracked

Acceptance Criteria:

  1. Create API endpoint for drop-off vendor creation:
    • POST /api/v1/vendors/drop-off
    • Required fields: business_name, phone, address, vendor_type
    • Optional fields: email
    • Vendor types: PICKUP_LOCATION, ONE_TIME_VENDOR
  2. Support yard association:
    • Link vendor to specific yard(s)
    • Track which yards vendor has serviced
    • Filter vendors by yard in GET requests
  3. Vendor retrieval API enhancement:
    • GET /api/v1/vendors/drop-off?yard={yardId}
    • Return only vendors associated with specified yard
    • Include vendor type in response
  4. Duplicate detection:
    • Check phone number uniqueness
    • Return existing vendor if duplicate found
  5. Audit trail for vendor creation and modifications

Data Model Requirements:

  • vendor_type: DROP_OFF (new type)
  • drop_off_type: PICKUP_LOCATION or ONE_TIME_VENDOR
  • yard_associations: Array of yard IDs
  • service_history: Track all drop-offs by yard and date

Validation Rules:

  • Phone number: Unique across all vendors
  • Business name: 3-100 characters
  • At least one yard association required
  • Cannot change vendor_type after creation

User Story 5.7: OAC New Charge Types Creation

As an OAC system administrator
I want to create new charge types in OAC
So that the transportation charges system can properly categorize and record different types of charges

Acceptance Criteria:

  1. Create the following new charge types in OAC:
    • Pickup Advance Charges: For standard transportation charges paid to tow providers
    • Copart Paid Charges: For charges that Copart pays on behalf of sellers
    • Overpaid Charges: For tracking payment amounts that exceed total charges
  2. Each charge type configuration shall include:
    • Charge type code (unique identifier)
    • Display name
    • Description
    • GL account mapping
    • Billable to seller flag (default setting)
    • Active/Inactive status
  3. Charge type properties:
    • Pickup Advance Charges:
      • Can be billed to seller: Yes
      • Default GL account for transportation expenses
      • Allow positive amounts only
    • Copart Paid Charges:
      • Can be billed to seller: Yes
      • Default GL account for reimbursable expenses
      • Allow positive amounts only
    • Overpaid Charges:
      • Can be billed to seller: No (system enforced)
      • Default GL account for payment exceptions
      • Allow positive amounts only
      • Read-only flag: Yes (cannot be manually created)
  4. Integration requirements:
    • Expose charge types via API for consumption by transportation system
    • Include in SOLR indexing for reporting
    • Available in bill creation and modification workflows

Technical Requirements:

  • Database table: charge_types
  • Required fields: charge_type_code, display_name, description, gl_account, billable_flag, active_flag, read_only_flag
  • API endpoint: GET /api/v1/charge-types (return active charge types)
  • Validation: Unique charge_type_code constraint
  • Audit trail: Track creation and modification of charge types

Data Migration:

  • Create SQL scripts for initial charge type setup
  • Include in deployment package
  • Verify charge types exist before system go-live

Future Enhancements (To Be Discussed)

  • Refund processing workflows
  • Check exceptions handling
  • Credit card payment exceptions
  • Incoming payment reconciliation
Content is user-generated and unverified.
    Transportation Charges Module - Complete User Stories | Claude