The Donorbox Importer is a phased, batched CSV migration tool that brings your historical donations, donors, campaigns, and recurring plans from Donorbox into Charitable Pro. Available in Charitable Pro 1.8.14+.

Key Features

• Six-stage wizard: upload, preview, options, import, results, and optional rollback.
• Imports donors, campaigns, donations, and recurring plans (archival only) from standard Donorbox CSV exports.
• Auto-detects CSV columns from a stable schema allow-list with multiple header aliases per field.
• Dry-run mode previews everything without writing a single record.
• Per-import batch ID stamps every record so a full rollback is one click away if the import is wrong.
• Synchronous rollback for small imports and async batched rollback for very large ones.
• Configurable date format (ISO, MM/DD/YYYY, DD/MM/YYYY) for CSVs from different regions.
• Optional override of duplicate donors and donations on re-import.
• Optional use of Donorbox’s converted amounts for multi-currency sites.
• 24-hour cleanup of abandoned imports, so a closed browser tab does not leave staging files behind.
• Concurrency guard prevents two imports from running at the same time.

Why Use the Donorbox Importer?

Moving away from Donorbox without losing your history was, until now, a manual exercise in spreadsheet wrangling. The Donorbox Importer reads the same CSVs Donorbox itself exports, maps them to Charitable’s data model, and brings everything across in one guided flow. Your donors, your campaigns, and the donation history that proves the relationship all land in Charitable, where they can power thank-you emails, segmented re-engagement campaigns, and your ongoing reporting.

Exigences

• Charitable Pro 1.8.14 or later
• PHP 7.4 or higher (the importer checks and refuses to run below this)
• Recent database backup (strongly recommended before any large import)
• Donorbox account with permission to export Donations, Supporters, and Recurring Plans as CSV

Démarrage

Before You Begin

1. Log in to your Donorbox dashboard and export your data as CSV using the “All Columns” option:
   • Donations CSV (required)
   • Supporters CSV (optional but recommended)
   • Recurring Plans CSV (optional)
2. Back up your WordPress database.
3. Know that Donorbox payment tokens are not portable. Imported recurring plans are archival only and arrive in Charitable with a cancelled status. You will need to re-collect payment authorization from those donors if you want recurring billing to continue in Charitable.

Where to Find It

Go to Charitable → Tools → Import → Donorbox.

Utilisation

The Donorbox Importer is a six-stage wizard. Each stage waits for explicit confirmation before moving on, and the dry run can be repeated as many times as you like before committing.

Stage 1: Upload CSVs

Upload your Donorbox Donations CSV. The Supporters and Recurring Plans CSVs are optional but strongly recommended. Once you click Continue, the importer parses the headers, detects the delimiter (comma, semicolon, or tab), and matches columns against the Donorbox schema.

Stage 2: Preview Counts

A dry-run runs against your uploaded files and reports how many donors, campaigns, donations, and recurring plans were found. Nothing is written to your database at this stage. Use the counts to sanity-check that the import sees what you expect.

Stage 3: Import Options

Pick which entities to import and configure advanced behavior:

• What to import: Donors, Campaigns, Donations, Recurring Plans
• Override duplicates on import
• Use Donorbox converted amounts (for multi-currency sites)
• Dry run (preview only, nothing is written)
• Date format: ISO (YYYY-MM-DD), MM/DD/YYYY, or DD/MM/YYYY

Stage 4: Importing

The importer processes one phase at a time (donors, then campaigns, then recurring, then donations) in batches of 200 rows by default. Progress updates live in the browser, and every imported record is stamped with the import’s batch ID.

Stage 5: Results

A summary shows the count of imported, skipped, and errored records for each entity, plus any warnings. From here you can keep the import or trigger a rollback.

Stage 6: Rollback (Optional)

If the import is not what you expected, the Rollback button removes everything stamped with this import’s batch ID. Small imports run synchronously; very large imports (over 5,000 records by default) run in background batches.

Configuration Options

Import Options (Stage 3)

Option	Type	Défaut	Description
Importer les donateurs	boolean	vrai	Process the Supporters CSV (when uploaded) to create donor records.
Importer les campagnes	boolean	vrai	Create Charitable campaigns from unique campaign names in the donations export.
Importer les dons	boolean	vrai	Create donation records linked to donors and campaigns.
Import Recurring Plans	boolean	true (when plans CSV uploaded)	Create archival recurring plan records (cancelled status).
Override Duplicates	boolean	false	When checked, re-importing a record updates the existing one instead of skipping it.
Use Converted Amounts	boolean	false	Use Donorbox’s converted amount column instead of the original donation currency.
Dry Run	boolean	false	Read and parse everything without writing any record to the database.
Date Format	chaîne de caractères	iso	iso (YYYY-MM-DD), mdy (MM/DD/YYYY), or dmy(DD/MM/YYYY).

Donorbox Fields Imported

Donations CSV (required)

Donation ID, donor email/first/last name, amount, converted amount, currency, donation date, donation status, payment method, Stripe/PayPal transaction IDs, processing fee, refund amount, campaign name and ID, comment, anonymous flag, gift aid, employer, occupation, recurring flag, plan ID, full address, phone, UTM source/medium/campaign, IP address.

Supporters CSV (optional)

Donor email, first/last name, full address, phone, employer, occupation, date joined, Donorbox donor ID, lifetime donation count, lifetime amount.

Recurring Plans CSV (optional)

Donorbox plan ID, donor email, first/last name, campaign name, amount, currency, frequency, start date, next charge date, status, payment method, donation count.

The importer accepts multiple alias names for each field (for example email, donor_email, email_address all map to the donor email), so older or relabeled exports usually work without manual cleanup.

Personnalisation

Batch Size

The default batch size is 200 rows per request. Define CHARITABLE_DONORBOX_BATCH_SIZE in wp-config.php for an environment-wide override, or hook the charitable_donorbox_batch_size filter for finer control:

add_filter( 'charitable_donorbox_batch_size', function( $size ) {
    return 500;
} );

Dépannage

“Another Donorbox import is already in progress”

The importer only allows one import at a time. Wait for the existing import to finish, or use the rollback flow on the existing import before starting a new one.

“PHP Version Not Supported”

The importer requires PHP 7.4+. Update PHP in your hosting control panel and reload the page.

CSV columns are not recognized

Re-export from Donorbox using the “All Columns” option. Donorbox occasionally changes header names; if your export uses a header the importer does not recognize, hook charitable_donorbox_csv_schema to extend the allow-list.

Recurring plans are imported as cancelled

This is intentional. Donorbox payment tokens are not portable, so the plans are brought across as archival historical records. To resume recurring billing in Charitable you will need to re-collect payment authorization from those donors using a Charitable recurring donation form.

Import looks wrong; how do I undo it?

Use the Rollback button on the Results screen. The importer stamps every record it creates with the import’s batch ID and the rollback removes only those records.

Developer Resources

Hooks et filtres

• charitable_donorbox_batch_size — change how many CSV rows are processed per AJAX request (default 200).
• charitable_donorbox_csv_schema — extend or override the column allow-list per entity type (donations, supporters, plans).
• charitable_donorbox_rollback_async_threshold — change the record count above which rollback runs asynchronously (default 5,000).
• charitable_donorbox_verbose_logging — enable verbose internal logging for the active import.

Constants

• CHARITABLE_DONORBOX_BATCH_SIZE — define in wp-config.php for an environment-level batch size override.

Useful Classes

• Charitable_Donorbox_Importer — main orchestrator. Phase order is donors → campaigns → recurring → donations.
• Charitable_Donorbox_CSV_Parser — streaming CSV parser with delimiter detection, header normalization, and per-entity schema allow-lists.

Logging

Import events are logged with the source donorbox and appear in the standard Charitable logs (Charitable → Tools → Logs), filterable by the Donorbox Import source.