Tutorial Integrasi WooCommerce ke Founder HQ
FounderHQ WordPress Plugin
Order Management System Documentation
System Overview
The FounderHQ WordPress Plugin provides two main order management functionalities that allow seamless integration between WooCommerce stores and the FounderHQ system.
Verify Existing Orders
Checks which WooCommerce orders already exist in FounderHQ, prevents duplicates, and cleans up orphaned records using smart email/phone matching.
Smart Bulk Push
Intelligently pushes new orders to FounderHQ with built-in duplicate checking, complete order data transfer, and comprehensive error handling.
Architecture Components
- Frontend: WordPress Admin Panel with AJAX-powered UI
- Backend: Laravel API with robust authentication
- Processing: Laravel Queue Jobs for scalable background processing
- Database: Multi-table synchronization with soft delete support
Verify Existing Orders Flow
Verify Existing Orders Process Flow
User clicks “Verify Existing Orders”
↓
Confirmation Modal
“This will verify ALL orders against FounderHQ”
“This will verify ALL orders against FounderHQ”
↓
WordPress gathers orders
Excludes: success & existing status
Excludes: success & existing status
↓
Orders > 250?
Chunked Processing
250 orders per chunk
250 orders per chunk
Direct API Call
Single batch processing
Single batch processing
↓
Laravel Authentication
API Key + Secret validation
API Key + Secret validation
↓
VerifyOrdersJob Execution
Background processing
Background processing
↓
1
Email Match
Search by customer email
2
Phone Match
Fallback to phone number
3
Verify Order
Check actual Order record
4
Cleanup
Soft delete orphaned records
↓
Status Polling
Every 2 seconds until complete
Every 2 seconds until complete
↓
Results Display
Summary + detailed breakdown
Summary + detailed breakdown
Order Status Processing Logic
| Order Status | Processing Action | Reason |
|---|---|---|
| success | SKIP – Not included in verification | Already successfully synced to FounderHQ |
| existing | SKIP – Not included in verification | Confirmed to exist in FounderHQ system |
| pending | VERIFY – Check against FounderHQ | Never been processed or sync status unclear |
| failed | VERIFY – Check against FounderHQ | Previous sync attempt failed, might exist now |
| no status | VERIFY – Check against FounderHQ | No sync metadata found, needs verification |
Verification Results & Actions
| Match Result | Database Action | WooCommerce Update | User Notification |
|---|---|---|---|
| Valid Order Found WoocommerceOrder exists + Order record exists |
No change needed | Update metadata: • _founder_link_sync_status = 'existing'• _founder_link_last_sync = timestamp |
Already exists in FounderHQ |
| Orphaned Record WoocommerceOrder exists but Order record missing |
Soft delete WoocommerceOrder record | No metadata update (treated as new order) | Ready for sync |
| No Match Found No WoocommerceOrder record exists |
No change needed | No metadata update (treated as new order) | Ready for sync |
Smart Bulk Push Flow
Smart Bulk Push Process Flow
User clicks “Smart Bulk Push”
↓
Confirmation Modal
“This will push pending orders to FounderHQ”
“This will push pending orders to FounderHQ”
↓
WordPress gathers ALL orders
Includes: Complete order data + line items
Includes: Complete order data + line items
↓
Orders > 250?
Chunked Processing
250 orders per chunk
250 orders per chunk
Direct API Call
Single batch processing
Single batch processing
↓
Laravel Authentication
API Key + Secret validation
API Key + Secret validation
↓
SmartBulkPushJob Execution
4-step background process
4-step background process
30%
Verify Existing
Check duplicates
10%
Categorize
Existing vs New
50%
Push New Orders
Submit to FounderHQ
10%
Compile Results
Final summary
↓
Real-time Progress Updates
Live progress bar + time estimates
Live progress bar + time estimates
↓
Final Results Dashboard
Success/failure breakdown
Success/failure breakdown
Smart Bulk Push Processing Logic
| Step | Progress | Action Description | Output |
|---|---|---|---|
| 1. Verify Existing | 0% → 30% | Run same verification logic as “Verify Existing Orders” • Email/phone matching • Orphaned record cleanup |
Categorized list: existing vs new orders |
| 2. Categorize Orders | 30% → 40% | Split verification results into two groups: • Existing – Skip these • New – Process these |
Two arrays: existingOrders[], newOrders[] |
| 3. Push New Orders | 40% → 90% | For each new order: • Call /submit-order API• Include complete order data • Handle individual failures gracefully |
Success/failure status per order |
| 4. Compile Results | 90% → 100% | Generate comprehensive summary: • Total processed • Success/failure counts • Detailed breakdown |
Final results dashboard |
Order Submission Details
Complete Order Data Sent to FounderHQ
{
“wc_order_id”: 12345,
“status”: “processing”,
“total”: “199.99”,
“currency”: “MYR”,
“payment_method”: “stripe”,
“customer”: {
“first_name”: “John”,
“last_name”: “Doe”,
“email”: “john@example.com”,
“phone”: “+60123456789”
},
“billing”: { /* Complete billing address */ },
“shipping”: { /* Complete shipping address */ },
“line_items”: [
{
“name”: “Product Name”,
“quantity”: 2,
“price”: “99.99”,
“sku”: “PROD-001”
}
],
“store_name”: “My WooCommerce Store”,
“url_name”: “https://mystore.com”
}
Feature Comparison
| Aspect | Verify Existing Orders | Smart Bulk Push |
|---|---|---|
| Primary Purpose | Check if WooCommerce orders already exist in FounderHQ | Push new orders to FounderHQ with duplicate prevention |
| Orders Included | Only orders without ‘success’ or ‘existing’ status | ALL orders (pending, processing, on-hold, completed) |
| Data Transferred | • Order IDs • Customer email/phone • Basic order details |
• Complete order data • Billing & shipping addresses • Line items & products • Payment method |
| Primary Action | READ/VERIFY Check existing records |
WRITE/CREATE Submit new orders |
| Database Changes | • Soft delete orphaned records • Update WooCommerce metadata |
• Create new FounderHQ orders • Update WooCommerce metadata • Link orders via hq_order_id |
| Performance Impact | Light – Read-only operations | Heavy – Creates new database records |
| Typical Use Case | • Audit existing data • Clean up inconsistencies • Pre-migration check |
• Initial data migration • Catch-up sync • Bulk order import |
| Error Handling | • Graceful orphan cleanup • No data loss risk |
• Individual order failure tolerance • Comprehensive retry logic |
Technical Implementation Details
System Architecture
Frontend Layer
- WordPress Admin Interface
- AJAX-powered interactions
- Real-time progress tracking
- Error handling & user feedback
API Communication
- RESTful API endpoints
- Basic Authentication
- JSON data exchange
- Comprehensive error codes
Background Processing
- Laravel Queue Jobs
- Synchronous dispatch for reliability
- Progress tracking in database
- Failure recovery mechanisms
Data Management
- Multi-table synchronization
- Soft delete support
- Comprehensive logging
- Audit trail maintenance
Performance & Scalability
Chunked Processing for Large Datasets
- Threshold: Automatic chunking when >250 orders
- Chunk Size: 250 orders per batch for optimal performance
- Progress Tracking: Real-time updates across all chunks
- Error Isolation: Failed chunks don’t affect successful ones
- Memory Management: Prevents PHP memory limit issues
Security & Reliability Features
| Security Layer | Implementation | Purpose |
|---|---|---|
| Authentication | Basic Auth with API Key + Secret | Verify legitimate requests |
| Authorization | WordPress capability checks (manage_options) |
Ensure admin-level permissions |
| CSRF Protection | WordPress nonce validation | Prevent cross-site request forgery |
| Data Integrity | Comprehensive validation & sanitization | Prevent malicious data injection |
| Error Isolation | Individual order failure tolerance | Prevent single failures from stopping entire batch |
| Audit Trail | Detailed logging of all operations | Enable debugging & compliance tracking |
Error Handling & Recovery
Automatic Retry Logic
Failed operations are automatically retried up to 3 times with exponential backoff to handle temporary network issues or server overload.
Graceful Degradation
System continues processing even when individual orders fail, providing detailed failure reports without stopping the entire operation.
Comprehensive Logging
Every operation is logged with detailed context, enabling quick debugging and system monitoring for production environments.
Data Recovery
Soft delete mechanisms ensure no data is permanently lost, allowing recovery of accidentally removed records when needed.
Best Practices Implemented
- Idempotent Operations: Safe to retry without side effects
- Progressive Enhancement: Graceful fallback for older browsers
- Resource Management: Memory-efficient processing for large datasets
- User Experience: Real-time feedback and progress indication
- Maintainability: Clean separation of concerns and modular architecture