Sprout Invoices → Invoice Ninja Exporter

A basic vibe-coded WordPress plugin to partially export data from Sprout Invoices into CSV files somewhat compatible with Invoice Ninja's import system. Not intended to be complete. Made with GitHub Copilot using Claude.

Overview

This plugin provides a simple admin interface to export your Sprout Invoices data (clients, invoices, and payments) into CSV files that can be imported into Invoice Ninja. It handles the data transformation needed to map Sprout's data structure to Invoice Ninja's expected format.

Features

• Client Export: Exports all clients with support for multiple contacts per client
• Invoice Export: Exports invoices with line items, taxes, and proper date handling
• Payment Export: Exports payments linked to their respective invoices
• Tax Support: Handles invoice-level taxes (HST, GST, etc.)
• Debug Tools: Built-in meta inspectors to troubleshoot data issues

Installation

1. Copy the sprout-to-ninja.php file to your WordPress plugins directory (wp-content/plugins/sprout-to-ninja/)
2. Activate the plugin in WordPress Admin → Plugins
3. Access the exporter at Tools → Sprout → Ninja Export

Usage

Import Order

Important: Import the CSV files into Invoice Ninja in this order:

1. Clients (sprout_clients.csv)
2. Invoices (invoice_ninja_invoices_merged.csv)
3. Payments (invoice_ninja_payments.csv)

This order ensures that invoices can reference existing clients, and payments can reference existing invoices.

Exporting Data

1. Navigate to Tools → Sprout → Ninja Export in WordPress Admin
2. Click the appropriate download button for each export type
3. Save the CSV files

Importing into Invoice Ninja

1. In Invoice Ninja, go to Settings → Import | Export
2. Select Import and choose the appropriate entity type (Clients, Invoices, or Payments)
3. Upload the corresponding CSV file
4. Map the columns (most should auto-map correctly)
5. Complete the import

CSV Formats

Clients CSV

Column	Description
client.name	Company/client name
client.phone	Client phone number
client.website	Client website URL
client.address1	Street address
client.address2	Address line 2
client.city	City
client.state	State/Province
client.postal_code	Postal/ZIP code
client.country_id	Country
contact.first_name	Contact first name
contact.last_name	Contact last name
contact.email	Contact email
contact.phone	Contact phone

Note: Multiple contacts per client are supported. Each contact is exported as a separate row with the same client information.

Invoices CSV

Column	Description
Invoice - Number	Invoice number/ID
Client - Email	Primary client contact email
Client - Name	Client name
Invoice - Date	Invoice date (YYYY-MM-DD)
Invoice - Due Date	Due date (defaults to +30 days if missing)
Invoice - Tax Name 1/2/3	Tax names (e.g., "HST")
Invoice - Tax Rate 1/2/3	Tax rates (e.g., "13.00")
Item - Product	Item type (Task, Service, Product, Time)
Item - Notes	Line item description
Item - Quantity	Quantity
Item - Cost	Unit cost

Note: Each line item is exported as a separate row. Rows with the same invoice number are grouped together during import.

Payments CSV

Column	Description
Payment - Number	Unique payment ID (PAY-{sprout_id})
Payment - Invoice Number	Links payment to invoice
Payment - Client Id	Client name for validation
Payment - Amount	Total payment amount
Payment - Applied	Amount applied to invoice
Payment - Date	Payment date (YYYY-MM-DD)
Payment - Method	Payment method
Payment - Private Notes	Payment notes

Configuration

Tax Names

The plugin defaults to "HST" for the primary tax. To change this, edit the default_tax_name1() and default_tax_name2() functions in sprout-to-ninja.php:

private static function default_tax_name1()
{
    return 'HST'; // Change to your tax name (GST, VAT, etc.)
}

private static function default_tax_name2()
{
    return 'Tax 2'; // Secondary tax name if used
}

Debug Tools

The plugin includes several debug tools accessible from the main export page:

• Meta Inspector: View raw meta data for any Sprout post type (clients, invoices, payments)
• Associated Users Debug: See how contacts are linked to clients
• Line Item Structure Debug: Examine the structure of invoice line items

These tools are helpful for troubleshooting if data isn't exporting as expected.

Data Handling Notes

Multiple Contacts

Sprout Invoices stores multiple contacts as separate meta rows. The plugin correctly extracts all contacts and exports one row per contact for the client import.

Missing Due Dates

If an invoice doesn't have a due date set in Sprout, the export automatically sets it to 30 days after the invoice date.

Payment Dates

If a payment is missing a date in its metadata (common with older Stripe payments), the plugin falls back to the WordPress post publish date.

Taxes

Invoice-level taxes are read from _doc_tax and _doc_tax2 meta fields. The tax name defaults to the configured value if no label is stored.

Item Types

Line items include a type field (Task, Service, Product, Time) from Sprout's preset items, which maps to Invoice Ninja's Item - Product field.

Troubleshooting

Payments failing to import

• Ensure invoices are imported first
• Check that invoice numbers match between the invoice and payment CSVs
• Verify the client name matches exactly

Missing taxes

• Use the Meta Inspector to check if _doc_tax is set on your invoices
• Verify the tax percentage is stored (e.g., "13" for 13%)

Missing contacts

• Use the Associated Users Debug to verify contacts are linked to clients
• Check that WordPress users exist for the linked user IDs

Version History

• 0.6.0 - Separated payments export, added payment method and notes, fixed column naming
• 0.5.0 - Added item type export, removed unused columns
• 0.4.0 - Fixed Invoice Ninja column format, added due date fallback
• 0.3.0 - Added tax support, fixed multiple contacts per client
• 0.2.0 - Added payment date fallback, fixed currency handling
• 0.1.0 - Initial release

License

This plugin is provided as-is for migrating data from Sprout Invoices to Invoice Ninja.