Invoice Export Profile

The Invoice Export Profile exports Magento store orders to FreeAgent as invoices. This is a critical profile for the Magento-FreeAgent integration, ensuring that all sales transactions are accurately reflected in your accounting system.

Overview

Profile Type ID: freeagent_invoice_export Direction: Magento → FreeAgent Purpose: Export Magento web store orders to FreeAgent as invoices

What Gets Exported

• Orders: Complete order data as FreeAgent invoices
• Line Items: Product line items with quantities and prices
• Contacts: Customer information (creates/links FreeAgent contacts)
• Shipping: Shipping charges as invoice line items
• Discounts: Discount amounts as invoice line items
• Tax: Tax rates and amounts
• Order Totals: Complete financial breakdown

Primary Use Cases

• Automated Invoicing: Automatically create FreeAgent invoices for new orders
• Financial Reconciliation: Ensure Magento sales data matches FreeAgent records
• Tax Reporting: Maintain accurate tax records in FreeAgent
• Cash Flow Tracking: Track outstanding invoices and payments
• Email Delivery: Trigger invoice emails to customers from FreeAgent

Primary Workflow

Customer Places Order (Magento)
         ↓
Order Status Changes to "Processing"
         ↓
Contact Created/Updated in FreeAgent
         ↓
Invoice Export Profile Runs (Automatic)
         ↓
Invoice Created in FreeAgent
         ↓
Invoice Email Sent (Optional)
         ↓
Invoice Status Synced Back (Invoice Import)

Contact Dependency

The Invoice Export automatically handles contact creation. If a customer doesn't exist as a FreeAgent contact, the invoice export pipeline will create the contact first, then create the invoice linked to that contact.

Configuration Reference

All configuration options are found at: Admin Panel > Byte8 > FreeAgent > Profiles > [Your Invoice Export Profile]

1. Client Configuration

Client

Field: client_id Type: Select (Required) Scope: Global

Select the FreeAgent client configuration to use for this invoice export profile.

Actions:

• Edit - Modify existing client configuration
• New Client - Create a new FreeAgent client connection
• Collect Configuration Data - Fetch tax rates, categories, and bank accounts from FreeAgent
• Delete Configuration Data - Remove cached configuration data

Initial Setup

After selecting a client, click Collect Configuration Data to populate dropdown options. This fetches tax rates, categories, and bank accounts from your FreeAgent system.

---

2. Schedule Configuration

Enable Schedule

Field: status Type: Checkbox Default: Enabled Scope: Global

Enable automatic invoice export processing via the scheduler. When enabled, orders will be exported to FreeAgent as invoices according to the configured schedule.

When to Enable:

• Production environments with regular order flow
• Automated invoicing workflow
• Real-time or near-real-time financial record keeping

When to Disable:

• Manual order review before invoicing
• Testing and configuration phases
• Batch export during specific time windows only

Schedule

Field: schedule_id Type: Select (Required when enabled) Scope: Global

Select the cron schedule that determines when this invoice export profile runs automatically.

Common Schedules:

• Every 5 minutes - Near real-time invoice sync (recommended for high-volume)
• Every 15 minutes - Standard invoice sync
• Every 30 minutes - Low-volume stores
• Custom - Define your own cron expression

Recommended: Every 5-15 minutes for timely financial record keeping.

Process Batch Size

Field: process_batch_size Type: Number Default: 50 Range: 1-1000 Scope: Global

Number of orders processed per batch.

Recommended settings:

• 50 (default) - Optimal for most stores
• 25-30 - Complex orders with many line items or low memory
• 75-100 - Simple orders with high memory

Performance notes:

• Memory usage scales with order complexity (number of line items)
• Start with default and adjust based on monitoring
• Consider the FreeAgent API rate limits

Performance Impact

Higher batch sizes consume more memory. Monitor your PHP memory_limit (recommended: 2GB+) when processing large batches.

Enable Automatic Retry on Failure

Field: enable_retry_on_failure Type: Checkbox Default: Disabled Scope: Global

Automatically retry failed invoice exports on subsequent schedule runs.

When to Enable:

• Automatic recovery from temporary FreeAgent downtime
• Network connectivity issues
• API rate limiting recovery

How It Works:

1. Invoice export fails (API timeout, connection error)
2. Order marked for retry with attempt counter
3. System retries on next scheduled run (up to configured max attempts)
4. Only retries orders less than 24 hours old
5. After max attempts exceeded, admin email notification sent (if enabled)
6. Orders exceeding max retry attempts require manual intervention

Maximum Retry Attempts

Field: retry_max_attempts Type: Number Default: 3 Scope: Global

Maximum number of retry attempts for failed invoice exports.

Recommended Values:

• 3 (default) - Suitable for most environments
• 5-10 - For environments with frequent but short FreeAgent downtime

Enable Retry Failure Notification

Field: retry_notification_enabled Type: Checkbox Default: Disabled Scope: Global

Send an email notification when an invoice exceeds maximum retry attempts.

---

3. HTTP API Configuration

Controls how the profile interacts with the FreeAgent API.

API Behavior

• Create New: Only create invoices that don't exist in FreeAgent
• Update Existing: Only update invoices that already exist
• Create and Update: Create new and update existing (recommended)

---

Processing Pipeline

The Invoice Export service uses a sophisticated multi-stage processor pipeline:

Generators

Generator	Sort Order	Purpose
Contact Data	10	Generate contact payload for order customer
Invoice Data	20	Generate invoice payload from order data
Shipping Items	25	Generate shipping charge line items
Discount Items	28	Generate discount line items

Processors

Processor	Sort Order	Purpose
Contact Creation	40	Create or link FreeAgent contact for order customer
Invoice Processing	45	Create or update invoice in FreeAgent via API
Email Sending	50	Trigger invoice email delivery from FreeAgent

Post-Processors

Post-Processor	Sort Order	Purpose
Response Data	90	Process API response and store FreeAgent references
Order History	95	Add FreeAgent reference to Magento order history
Queue & Log	100	Update queue status and log processing results

Sales Order Grid Integration

The Invoice module extends the Magento sales order grid with additional FreeAgent columns:

Grid Column	Description
fa_invoice_id	FreeAgent Invoice ID
fa_reference	FreeAgent Reference Number
fa_status	FreeAgent Invoice Status

These columns allow you to quickly see the FreeAgent sync status directly from the Magento order grid.

Entity Data

Invoice sync data is tracked in the freeagent_invoice_entity table:

Column	Type	Description
entity_id	INT	Primary key
invoice_id	VARCHAR	FreeAgent invoice ID
order_id	INT	Magento order ID
reference	VARCHAR	FreeAgent reference number
status	VARCHAR	Sync status
queue_status	VARCHAR	Queue processing status
message	TEXT	Sync messages (JSON)
metadata	TEXT	Additional data (JSON)
collected_at	DATETIME	When data was collected from FreeAgent
processed_at	DATETIME	When data was last processed

CLI Commands

# Collect invoices from FreeAgent
bin/magento fa_invoice:collect

# Export all pending orders as invoices
bin/magento fa_invoice:export

# Export specific orders by profile ID
bin/magento fa_invoice:export --profile=1

# Export specific order by entity ID
bin/magento fa_invoice:export --id=42

# Dry run (preview without sending)
bin/magento fa_invoice:export --dry-run

# Import invoice status from FreeAgent
bin/magento fa_invoice:import

Best Practices

1. Schedule contact export before invoice export - While the invoice pipeline handles contact creation, pre-existing contacts are faster to process.

2. Use appropriate batch sizes - Start with 50 and adjust based on order complexity. Orders with many line items require more memory per batch.

3. Monitor the sales order grid - Use the FreeAgent columns in the order grid to identify orders that haven't been synced.

4. Enable retry for production - Temporary API outages are common. Enable retry with 3-5 attempts to handle transient failures automatically.

5. Review shipping and discount handling - Verify that shipping charges and discounts are correctly mapped as invoice line items.

6. Test with sandbox first - Always test invoice export in FreeAgent sandbox mode before enabling on production.

Troubleshooting

Orders Not Exporting

Problem: Scheduled invoice export runs but no orders are exported

Solutions:

1. Verify the profile schedule is enabled
2. Check that orders exist in the queue (correct status)
3. Review var/log/freeagent/invoice.log for errors
4. Verify FreeAgent API credentials are valid
5. Test with CLI: bin/magento fa_invoice:export --dry-run

Contact Creation Fails

Problem: Invoice export fails because contact creation fails

Solutions:

1. Check contact data for required fields (email, name)
2. Review var/log/freeagent/contact.log for API errors
3. Verify the customer has a valid email address
4. Check for duplicate contacts in FreeAgent

Incorrect Tax Amounts

Problem: FreeAgent invoices show incorrect tax amounts

Solutions:

1. Verify tax rate mapping configuration
2. Check Magento tax configuration matches FreeAgent
3. Review the invoice data generator for tax handling
4. Compare line item tax calculations

Duplicate Invoices

Problem: Same order appears as multiple invoices in FreeAgent

Solutions:

1. Check the freeagent_invoice_entity table for duplicate entries
2. Verify the API behavior setting (create vs. update)
3. Review the reference number generation for uniqueness
4. Check for concurrent profile executions

Email Not Sending

Problem: Invoices created but emails not sent

Solutions:

1. Verify the email processor is enabled in the pipeline
2. Check FreeAgent email settings
3. Review var/log/freeagent/invoice.log for email errors

Next Steps

1. Credit Memo Export - Configure credit memo sync
2. Contact Export - Configure contact synchronization
3. CLI Commands - Full CLI reference

Related Documentation

• About Profiles
• Client Configuration
• Profile Configuration