Billit Woo Connect

Billit WooCommerce Integration

A comprehensive WordPress plugin that seamlessly integrates WooCommerce with Billit for automated invoice and credit note creation, featuring advanced VAT handling, bi-directional PDF management, and Peppol network integration.

🚀 Key Features

Core Integration

  • Automatic Invoice Creation: Smart invoice generation when orders reach configured statuses
  • Advanced Credit Note System: Handles full/partial refunds including shipping and fees
  • Peppol Network Integration: Automatic B2B invoice delivery via European Peppol network
  • Bi-Directional PDF Management: Upload WooCommerce PDFs to Billit and download Billit PDFs
  • Real-Time Status Tracking: Visual indicators and comprehensive order notes

Advanced VAT & Customer Handling

  • Multi-Country VAT Detection: Automatic VAT number extraction and validation (BE, NL, DE, FR, GB)
  • Smart Customer Classification: Automatic B2B vs B2C detection with proper tax handling
  • POS System Support: VAT extraction from company names in POS orders
  • Company Name Cleaning: Removes embedded VAT numbers for professional appearance

Professional Admin Interface

  • Dual Meta Box System: Separate interfaces for operations and PDF management
  • PDF Download Icons: Direct PDF access from orders list overview
  • AJAX Operations: Real-time processing with progress indicators
  • Manual Override Options: Full manual control when needed

Enterprise-Grade Reliability

  • Comprehensive Error Handling: Detailed logging and graceful error recovery
  • Duplicate Prevention: Advanced logic prevents duplicate operations
  • HPOS Compatibility: Full support for WooCommerce High-Performance Order Storage
  • Retry Mechanisms: Automatic retries for failed operations

🛠️ Technical Requirements

  • WordPress: 5.0 or higher
  • WooCommerce: 6.0 or higher
  • PHP: 7.4 or higher
  • Billit Account: Active account with API access
  • SSL: HTTPS required for API communications

📦 Installation

  1. Upload Plugin Files:

    /wp-content/plugins/billit_woo_connect/

  2. Activate Plugin:

    • Navigate to Plugins → Installed Plugins
    • Find "Billit WooCommerce Integration"
    • Click Activate

  3. Initial Configuration:

    • Go to Settings → Billit Integration
    • Enter your Billit API credentials
    • Configure processing preferences
    • Test API connection

⚙️ Configuration Guide

API Settings 

API Key: [Your Billit API Key]
Company ID: [Your Billit Company ID] 
API Environment:
  • Sandbox: https://api.sandbox.billit.be/v1
  • Production: https://api.billit.be/v1

Processing Settings

  • ✅ Enable Automatic Processing: Smart automation for invoices and credit notes
  • 📋 Auto-Invoice Statuses: Configure which order statuses trigger invoice creation
  • 📤 Automatic Peppol Sending: Auto-send B2B invoices via Peppol network
  • 🔧 Processing Mode: Choose between different integration levels

PDF Management

  • 📄 Upload PDFs to Billit: Attach WooCommerce PDFs to Billit orders
  • 📥 Download PDFs from Billit: Retrieve and store Billit-generated PDFs
  • ⏱️ Auto-Retrieval: Scheduled PDF downloading after invoice/credit note creation
  • 👥 Frontend Display Control: Toggle customer visibility of PDFs on My Account page (enabled by default)

Order Configuration

  • 🏷️ Order Number Prefix: Customize prefixes for Billit orders (default: "WC-")
  • 📅 Invoice Expiry: Set payment terms (default: 30 days)
  • 💼 Credit Note References: Automatic linking to original invoices

🎯 Usage Guide

Automatic Processing Flow

Invoice Creation:

  1. Customer places order → WooCommerce processes payment
  2. Order reaches configured status (e.g., "Processing")
  3. Plugin detects VAT number and classifies customer (B2B/B2C)
  4. Creates invoice in Billit with proper VAT handling
  5. Sends via Peppol (for B2B customers) or stores for manual sending
  6. Retrieves and attaches PDF to WooCommerce order

Credit Note Creation:

  1. Merchant processes refund in WooCommerce
  2. Plugin detects refund components (products + shipping + fees)
  3. Creates comprehensive credit note in Billit
  4. Links to original invoice reference
  5. Sends via Peppol (if original was B2B)
  6. Retrieves and attaches credit note PDF

Manual Operations

From Order Edit Page:

  • Billit Integration Meta Box:
    • 📋 View current status (invoice/credit note creation)
    • 🔘 Manual "Create Invoice" and "Create Credit Note" buttons
    • ✅ Real-time status updates with detailed information
  • Billit PDF Downloads Meta Box:
    • 📁 View all downloaded PDFs (invoices, credit notes)
    • 📥 "Download All PDFs" or individual PDF downloads
    • 🔄 "Refresh All PDFs" to update existing files
    • 📊 File size, dates, and document type indicators

From Orders List:

  • Billit Status Column: Shows operation status at a glance
  • PDF Download Icons: Direct download links for available PDFs
    • 📋 = Invoice PDF available
    • 🧾 = Credit Note PDF available
    • Click any icon for instant PDF download

Advanced Features

VAT Number Detection:

Automatic detection from:
• Customer billing fields (vat_number, billing_vat_number)  
• Company names (embedded VAT: "Company BE0123456789")
• Multi-country format handling and validation

POS System Integration:

Input: "Beauty Salon BE1234567890"
Output: 
  • Company: "Beauty Salon" (cleaned)
  • VAT Number: "BE1234567890" (extracted)
  • Classification: B2B Customer

Comprehensive Refund Handling:

Refund Components Detected:
• Product refunds (with quantities and VAT)
• Shipping cost refunds (with proper tax calculation)  
• Payment gateway fees and handling fees
• All components properly categorized in credit notes

🔧 API Integration Details

Invoice Payload Structure 

{
  "OrderType": "Invoice",
  "OrderDirection": "Income", 
  "Customer": {
    "VATLiable": true,
    "VATDeductable": true,
    "VATNumber": "BE0123456789",
    "ContactFirstName": "John",
    "ContactLastName": "Doe"
  },
  "OrderLines": [
    {
      "Quantity": 2,
      "UnitPriceExcl": 25.00,
      "Description": "Product Name",
      "VATPercentage": 21
    }
  ]
}

Credit Note Features 

{
  "OrderType": "CreditNote",
  "AboutInvoiceNumber": "WC-1234",
  "Paid": true,
  "PaidDate": "2025-12-17",
  "OrderLines": [
    {"Description": "Product Refund", "Quantity": 1, "UnitPriceExcl": 25.00},
    {"Description": "Shipping Refund", "Quantity": 1, "UnitPriceExcl": 5.00}, 
    {"Description": "Fee Refund", "Quantity": 1, "UnitPriceExcl": 2.00}
  ]
}

PDF Management APIs

  • Upload: POST /v1/orders/{id}/attachments (multipart/form-data)
  • Download: GET /v1/files/{fileId} (base64 content)
  • Storage: WordPress media library with organized metadata

📊 Order Notes & Tracking

Invoice Operations 

✅ Billit Invoice Created Successfully
• Invoice ID: 2219533  
• Order Number: WC-2922
• Amount: € 109,00
• Created: 2025-11-11 23:45:57
• Auto-send via Peppol: Enabled (B2B customer)

📤 Invoice sent via Peppol network successfully
📥 Billit PDF retrieved and attached to order

Credit Note Operations 

🔄 Billit Credit Note Created Successfully
• Credit Note ID: 2219544
• Original Invoice: WC-2922  
• Refund Amount: € 48,00
• Components: Products (€38) + Shipping (€10)
• Created: 2025-11-12 01:15:23

📤 Credit note sent via Peppol network successfully
📥 Credit note PDF retrieved and attached to order

System Messages 

🔄 Billit automatic processing triggered (Status: processing)
ℹ️ B2B customer detected - Peppol sending enabled
ℹ️ Private customer - manual PDF sending required
❌ API Error: [Specific error message with troubleshooting info]

🛡️ Security & Performance

Security Features

  • ✅ HTTPS-only API communications
  • ✅ Secure WordPress options storage for API credentials
  • ✅ Nonce verification for all AJAX requests
  • ✅ Capability checks for administrative functions
  • ✅ Input sanitization and validation
  • ✅ Directory protection with index.php files
  • ✅ Protected log files with .htaccess

Performance Optimizations

  • ⚡ WordPress cron for scheduled operations
  • ⚡ AJAX for non-blocking admin operations
  • ⚡ Efficient API request batching
  • ⚡ Smart caching and duplicate prevention
  • ⚡ Optimized database queries for HPOS compatibility
  • ⚡ Settings caching to reduce database queries
  • ⚡ GitLab updater caching (12-hour cache with force-check support)

🔍 Troubleshooting Guide

Enable Debug Mode

  1. Settings → Billit Integration → Enable Debug Mode
  2. Check WordPress error logs: /wp-content/debug.log
  3. Monitor real-time processing in order notes

Common Issues & Solutions

API Connection Issues 

Problem: "API Connection Failed"
Solutions:
• Verify API key and company ID are correct
• Check API environment (sandbox vs production)  
• Test connection using admin interface
• Ensure HTTPS is properly configured

VAT Detection Issues 

Problem: "VAT number not detected"
Solutions:
• Check customer billing fields for VAT number
• For POS orders, ensure company name includes VAT
• Verify VAT number format matches country standards
• Review debug logs for detection attempts

PDF Issues 

Problem: "PDF not downloading"
Solutions:
• Ensure invoice/credit note exists in Billit first
• Check if PDF generation completed (may take time)
• Verify WordPress media directory permissions
• Use manual "Retrieve PDF" button for troubleshooting

Missing Refund Components 

Problem: "Shipping not included in credit note"
Solutions:
• Ensure shipping is included in WooCommerce refund
• Check refund amount matches product + shipping total
• Review debug logs for refund component detection
• Verify tax settings for shipping items

Debug Log Examples 

[INFO] Starting credit note creation process
[INFO] Private customer identified
[API] API Request: POST /orders (Credit Note Creation)
[INFO] Found shipping item: Standard Shipping, total=10.00, tax=2.10
[INFO] Added shipping refund: Standard Shipping, total=10.00, tax=2.10
[API] API Response: HTTP 200 - Credit note created (ID: 2219544)
[INFO] Credit note PDF retrieval scheduled

🔧 Hooks & Filters for Developers

Available Actions 

// Fired after successful operations
do_action('billit_invoice_created', $order_id, $invoice_data);
do_action('billit_credit_note_created', $order_id, $credit_note_data);
do_action('billit_pdf_retrieved', $order_id, $pdf_data);

// Before operations (allow modifications)
do_action('billit_before_invoice_creation', $order_id, &$payload);
do_action('billit_before_credit_note_creation', $order_id, &$payload);

Available Filters 

// Modify customer data before sending
$customer_data = apply_filters('billit_customer_data', $customer_data, $order);

// Modify order lines before sending  
$order_lines = apply_filters('billit_order_lines', $order_lines, $order);

// Modify VAT detection results
$vat_number = apply_filters('billit_detected_vat', $vat_number, $order);

📈 Performance Metrics

Typical Processing Times

  • Invoice Creation: 1-3 seconds
  • Credit Note Creation: 1-2 seconds
  • PDF Retrieval: 2-5 seconds
  • Peppol Sending: 3-10 seconds

Error Handling

  • Automatic Retries: 3 attempts for failed operations
  • Graceful Degradation: Continues processing even with non-critical failures
  • Comprehensive Logging: Full audit trail for troubleshooting

🔄 Version History

Current Version: 1.2.0

New in 1.2.0: ✅ Automatic Credit Note Payment Status: Credit notes now marked as paid automatically when refunds are issued ✅ Frontend PDF Display Control: New setting to show/hide invoices and credit notes on customer My Account page ✅ Performance Optimizations: Settings caching and updater caching (12-hour cache with force-check support) ✅ Security Enhancements: Directory protection files (index.php) in all subdirectories ✅ Version Consistency: Aligned plugin version constants across files

Core Features: ✅ Complete Billit API integration (invoices, credit notes, Peppol)
✅ Advanced VAT detection and multi-country support ✅ Bi-directional PDF management system ✅ Comprehensive refund handling (products + shipping + fees) ✅ Professional admin interface with dual meta boxes ✅ Enterprise-grade error handling and logging ✅ WooCommerce HPOS compatibility ✅ POS system integration with company name cleaning

Admin Interface: ✅ Real-time AJAX operations with progress indicators ✅ PDF download icons in orders list overview
✅ Separate meta boxes for operations and PDF management ✅ Manual override capabilities for all operations

Customer & VAT Handling: ✅ Automatic B2B/B2C classification ✅ VAT number extraction from multiple sources ✅ Company name cleaning for professional appearance ✅ Multi-country VAT format support and validation

📞 Support & Development

For Technical Issues

  • 🐛 Plugin Issues: Check debug logs and verify configuration
  • 🔌 API Issues: Consult Billit API documentation
  • 🛒 WooCommerce Issues: Ensure proper WooCommerce setup
  • 📄 PDF Issues: Verify file permissions and media library access

Development Notes

This plugin represents approximately 12-15 hours of development creating an enterprise-grade integration that handles:

  • Complex multi-API interactions (Billit v1/v2 endpoints)
  • Advanced business logic for European VAT compliance
  • Sophisticated file management and PDF processing
  • Real-time UI with comprehensive admin interface
  • Production-ready error handling and logging systems

Status: Ready for production testing and deployment! 🚀