Version: 3.0 | Status: Ready for Stakeholder Review | Date: 2026-01-15
1. Overview
1.1 Purpose
The Billion Marketplace Integration provides streamlined connectivity between Toprent.app and the Billion marketplace platform. This integration enables rental companies to expand their customer reach through marketplace presence while maintaining simplified operational workflows for order processing.
1.2 Business Value
| Value Area | Measurable Outcome | Timeframe |
|---|
| Revenue Expansion | Generate 10-15% additional bookings through marketplace channel | Within 6 months |
| Operational Efficiency | Process marketplace orders using existing workflows with zero additional staff | Immediate |
| Market Reach | Access marketplace customer base without separate sales/marketing investment | Within 3 months |
| Cost Control | Maintain integration with <2 hours/week operator overhead | Ongoing |
1.3 Success Metrics
| Metric | Definition | Baseline | Target | Measurement Method |
|---|
| Marketplace Order Volume | Orders received via Billion integration | 0 | 50+ orders/month per active tenant | Order source tracking |
| Order Processing Success Rate | % of marketplace orders successfully converted | N/A | >95% | Webhook success logs |
| Integration Uptime | % time integration is operational | N/A | >99.5% | Health check monitoring |
| Order Sync Latency | Time from status change to marketplace notification | N/A | <30 seconds | Webhook delivery logs |
| Operator Time per Order | Additional time required for marketplace vs direct orders | Direct order baseline | <5 min additional | Operator time studies |
| Revenue per Integration | Monthly revenue from marketplace orders | 0 | >$2,000/tenant | Financial reports |
1.4 Target Users
| Role | Business Context | Primary Activities |
|---|
| Company Admin | Business owners managing marketplace presence | Activate/deactivate integration, configure commission settings |
| Operator | Staff processing daily rental orders | Process marketplace orders, monitor integration status |
| Platform Admin | Toprent.app operations team | Manage integration health, troubleshoot connectivity issues |
1.5 Scope
In Scope:
- Marketplace integration activation and configuration
- Order intake from marketplace via webhooks
- Order status synchronization
- Commission tracking for marketplace orders
- Integration health monitoring
Out of Scope:
- Advanced marketplace management (SEO, moderation, static vehicles)
- Customer account management on marketplace
- Extra services publication
- Legal document management
- Payment processing (handled by 09-payment-processing)
- Customer communication (handled by 10-communications)
2. User Stories
Company Admin Stories
| Priority | Story | Acceptance Criteria |
|---|
| P0 | As an admin, I can activate Billion marketplace integration so that my company receives marketplace orders | Integration activates within 1 business day; webhook endpoint becomes active; activation logged |
| P1 | As an admin, I can configure commission rates for marketplace orders so that pricing reflects marketplace fees | Commission rates saved and applied to all new marketplace orders |
| P1 | As an admin, I can deactivate marketplace integration when needed | Integration stops receiving new orders; existing orders continue processing normally |
Operator Stories
| Priority | Story | Acceptance Criteria |
|---|
| P0 | As an operator, I can identify marketplace orders so that I can track their source and commission | Orders display “Billion” source badge; commission amount visible |
| P0 | As an operator, I can process marketplace orders using standard workflows so that no special training is required | Marketplace orders follow identical processing steps as direct orders |
| P1 | As an operator, I can view integration status so that I can identify and report issues | Dashboard shows last successful sync, error count, and connectivity status |
| Priority | Story | Acceptance Criteria |
|---|
| P0 | As a platform admin, I can monitor integration health across tenants so that I can proactively resolve issues | Dashboard shows all active integrations, error rates, and latency metrics |
| P1 | As a platform admin, I can enable/disable marketplace features platform-wide so that I can manage rollouts | Platform toggle affects all tenant integrations immediately |
| P1 | As a platform admin, I can troubleshoot integration issues so that I can restore connectivity | Access to logs, webhook history, and retry capabilities |
3. Functional Requirements
3.1 Integration Management
| ID | Requirement | Business Outcome |
|---|
| FR-01 | Admins can activate marketplace integration via settings panel | Companies can start receiving marketplace orders |
| FR-02 | System validates configuration before allowing activation | Prevents failed integrations and customer-facing errors |
| FR-03 | Admins can deactivate integration with preserved order history | Companies can pause marketplace presence without data loss |
| FR-04 | System tracks integration status and activation history | Enables troubleshooting and audit compliance |
| FR-05 | Platform admins can enable/disable marketplace features globally | Supports controlled rollouts and emergency shutdowns |
3.2 Order Processing
| ID | Requirement | Business Outcome |
|---|
| FR-06 | System receives marketplace orders via webhook | Enables real-time order intake from marketplace |
| FR-07 | Marketplace orders convert to standard Toprent.app orders | Operators use familiar workflows without retraining |
| FR-08 | Orders display marketplace source for tracking | Enables revenue attribution and commission tracking |
| FR-09 | Commission calculation applies to marketplace orders | Accurate financial reporting and pricing |
| FR-10 | Order status updates synchronize to marketplace | Customers see accurate order status on marketplace |
| FR-11 | Failed webhooks retry automatically | Prevents order loss from temporary connectivity issues |
3.3 Monitoring and Reporting
| ID | Requirement | Business Outcome |
|---|
| FR-12 | Integration health dashboard displays connectivity status | Proactive issue identification |
| FR-13 | System logs all integration events and errors | Enables troubleshooting and audit compliance |
| FR-14 | Platform admins receive alerts for integration failures | Rapid response to connectivity issues |
| FR-15 | Order volume and revenue tracking by source | Business intelligence for marketplace channel performance |
4. Acceptance Criteria
AC-01: Integration Activation
- Given a company admin with proper permissions
- When admin enables Billion marketplace integration
- Then integration status shows “Active” within 1 minute
- And webhook endpoint begins accepting orders
- And activation appears in audit log with timestamp
AC-02: Marketplace Order Intake
- Given an active marketplace integration
- When Billion sends a valid order via webhook
- Then order appears in Toprent.app within 30 seconds
- And order displays “Billion” as source
- And marketplace receives confirmation response
AC-03: Order Status Synchronization
- Given a marketplace order in Toprent.app
- When operator changes order status
- Then marketplace receives status update within 30 seconds
- And synchronization logged for audit trail
AC-04: Error Recovery
- Given a failed webhook delivery
- When marketplace retries the request
- Then system processes the order without duplicates
- And error resolution logged for monitoring
AC-05: Integration Health Monitoring
- Given active integrations across multiple tenants
- When platform admin views integration dashboard
- Then dashboard shows connectivity status per tenant
- And displays error rates and latency metrics
- And highlights integrations requiring attention
5. Business Rules
BR-01: Integration Activation
- Marketplace integration requires platform admin approval for first activation
- Tenant admins can activate/deactivate after initial approval
- Deactivation stops new orders but preserves existing order history
BR-02: Order Processing
- Marketplace orders follow standard Toprent.app order workflows
- Commission rates apply based on tenant configuration
- Order validation follows existing business rules
- Duplicate orders rejected based on marketplace order ID
BR-03: Error Handling
- Failed webhook deliveries retry with exponential backoff (max 3 retries)
- Integration errors logged but don’t impact core system operations
- Platform admins notified of persistent failures (>3 consecutive)
BR-04: Data Management
- Marketplace order data validated before processing
- Order source tracked for revenue attribution
- Audit logging captures all integration activities
6. Dependencies
6.1 Depends On
| Module | Dependency Type | Impact |
|---|
| 01-multi-tenant-architecture | Required | Tenant isolation for integration settings |
| 06-order-reservation-system | Required | Core order processing and status management |
| 30-audit-logs | Required | Integration event logging |
6.2 External Dependencies
| System | Integration Type | SLA Requirement |
|---|
| Billion Marketplace Platform | Webhook API | 99% uptime for order delivery |
7. Non-Functional Requirements
| Category | Requirement | Target |
|---|
| Performance | Webhook response time | <2 seconds |
| Performance | Status sync delivery | <1 second processing |
| Availability | Integration uptime | >99.5% |
| Reliability | Order processing success rate | >99% |
| Security | Webhook payload validation | All requests authenticated |
| Security | Rate limiting | Prevent integration abuse |
| Monitoring | Health check frequency | Every 5 minutes |
8. Glossary
| Term | Definition |
|---|
| Billion | External marketplace platform for vehicle rental aggregation |
| Source | Origin indicator for orders (e.g., “billion”) used for tracking and commission |
| Webhook | HTTP callback for real-time data exchange between systems |
| Integration | Connectivity layer between Toprent.app and Billion marketplace |
| Commission | Fee applied to marketplace orders for channel costs |
Change Log
| Version | Date | Author | Changes |
|---|
| 1.0 | 2026-01-01 | AI Generated | Initial technical documentation |
| 2.0 | 2026-01-09 | AI Generated | Simplified scope, removed complex features |
| 3.0 | 2026-01-15 | Converted | Business-focused format with measurable outcomes |