FAQ & Known Limitations

Frequently Asked Questions

Can I sync historical data from Virtuous into WeGive?

Yes, but we recommend importing historical data manually using WeGive's Import Tool rather than relying on the integration's initial sync function. Virtuous's API rate limits cause frequent timeouts on large datasets, making the sync unreliable for big data loads. Manual import gives you more control and lets you work in manageable batches. See Migrating Your Historical Data for the full walkthrough.

What happens if I disconnect and reconnect the integration?

Disconnecting the integration stops all sync activity in both directions. When you reconnect, you'll need to re-enter your API key and Communication ID and re-enable the integration. Existing records that were previously synced will retain their linked IDs, so the integration should pick up where it left off without creating duplicates, as long as the wg_id custom field is still in place in Virtuous.

How do I handle donors that exist in both systems already?

If donors already exist in both WeGive and Virtuous before the integration is enabled, the integration will attempt to match them based on available identifiers. To reduce the risk of duplicate records being created, clean up your data in both systems before enabling the integration. Remove duplicate emails, ensure company donors have complete contact info, and consider using Batch Integration mode so your team can manually verify matches through the Virtuous Import Tool.

Why are some transactions not syncing to Virtuous?

Not all transaction statuses are synced. Successful transactions and processing non-ACH transactions are always sent. Processing ACH transactions are only sent if the "Send Processing ACH as Success" setting is enabled. Failed and refunded transactions are only sent if the original transaction already exists in Virtuous. See Ongoing Sync Behavior for the full rules.

How do I switch between Batch and Real-Time integration mode?

You can change your integration mode in your Virtuous integration settings at Data > Integrations > Virtuous. The change takes effect immediately for new donations. See Connecting WeGive to Virtuous for details on each mode, and Batch Integration & the Virtuous Import Tool for a full walkthrough of the batch workflow.

What permissions does my Virtuous API key need?

Your API key needs sufficient permissions to read and write contacts, gifts, recurring gifts, projects, and segments in Virtuous. If your connection test fails or you see authorization errors in your Integration Logs, confirm with your Virtuous administrator that the user account associated with the API key has full API access.

Can I customize the field mappings?

No. Field mappings between WeGive and Virtuous are set automatically and cannot be customized. The integration uses a fixed set of mappings that cover contacts, transactions, recurring donations, funds, campaigns, contact methods, and addresses. See Field Mapping Reference for the complete list of how each field maps between the two systems.

Why do old emails stay on Virtuous contacts after I update them in WeGive?

This is expected Virtuous behavior. When a contact's primary email is updated, Virtuous does not delete the old email. Instead, it creates a new contact method for the new email and flags it as primary, while the old email is demoted to a secondary without a type designation. Communications always go to the active primary email. See Old Emails Remaining on Virtuous Contacts After an Update for more detail.

Why are late-day donations showing the wrong date in Virtuous?

This is a known timezone handling issue. Donations made after 4pm PST can cross the UTC date boundary during sync, causing them to appear in Virtuous with the following day's date. This issue has been partially addressed but may still occur. See Date and Time Issues in Virtuous Integration for workarounds and how to report ongoing problems.

Why did my integration suddenly stop working without any changes on my end?

Virtuous occasionally makes changes to their API without advance notice, which can cause syncs to fail unexpectedly. If your integration was working correctly and suddenly begins producing errors, check your logs at Data > Integration Logs. WeGive records all sync activity and errors, so the logs are the best place to identify when the errors started. If you can't identify the issue from the logs, contact WeGive support with the relevant log entries and we'll investigate.

Known Limitations

"Bi-directional" sync applies only to the specific data types listed in the integration. It does not mean all data in both systems flows back and forth. Workflows that depend on data types not in the supported list - such as tags, event registrations, communication lists, or custom fields - will need to be managed outside the integration.

Field mappings are fixed and cannot be customized. The integration uses automatic mappings for all data types. You cannot add, remove, or change how fields map between the two systems.

Virtuous API rate limits cause timeouts on large syncs. Virtuous enforces a hard cap of 1,500 API requests per hour. The initial "Begin Sync from Virtuous" function is unreliable for large datasets because it can exhaust this limit quickly, causing the sync to stall or error out mid-process. This affects not just historical data migration but any operation that touches a large number of records at once - including tagging donors or syncing communication lists - which is why those features are not supported at scale. We recommend manual import for historical data migration and Batch Integration mode for ongoing donation volume.

Only certain recurring frequencies are supported. Virtuous supports Monthly, Biweekly, Quarterly, Yearly, Daily, and First and 15th. Weekly and Semi-annually are not supported and will not sync.

ACH transactions require an explicit setting to sync while processing. By default, ACH donations are not sent to Virtuous until they are fully confirmed. Enable "Send Processing ACH as Success" if you want them to appear immediately.

Company donors may sync with placeholder names. If a company donor in WeGive is missing a contact person's first or last name, Virtuous will create the record with "FNU" (First Name Unknown) and "LNU" (Last Name Unknown) as placeholders.

Failed and refunded transactions only sync if the record already exists in Virtuous. WeGive will not push a brand new failed or refunded transaction to Virtuous. Only transactions that were previously synced as successful or processing will be updated with a failed or refunded status.

Email conflicts between individual and company donors can cause sync failures. Virtuous previously allowed duplicate emails across contacts but no longer does. Legacy data with shared emails will cause sync errors. There is no unique email enforcement in WeGive currently, so prevention requires manual data cleanup and staff training.

Late-day donation dates may appear incorrectly in Virtuous. Due to a timezone handling issue, donations made after 4pm PST may show the next day's date in Virtuous. This has been partially fixed but may still occur.

Mobile phone numbers may sync as "Home Phone" in Virtuous. A correction for this is in progress. In the meantime, you may need to manually update the phone type in Virtuous if accuracy is important for your records.

Communication lists do not sync to Virtuous. Audience segmentation and communication preferences managed in WeGive stay in WeGive and are not pushed to Virtuous.