Virtuous CRM Integration Known Limitations

These are the known limitations of the Virtuous CRM integration as of its initial release. They apply to all subscribers and stem from current design decisions, the boundaries of the Virtuous CRM API, and scope choices made for the initial release.

Note: The initial release ships with the minimum field set required to land Virtuous CRM Gifts as iPaaS.com Transactions. Several capabilities a typical CRM-to-platform integration would carry — customer linkage, related-record transfer (designations, premiums, pledge payments), historical sync, bidirectional sync, delete propagation — are not implemented. They are expected to be scoped and built in a follow-up release based on feedback. Many of the limitations below are direct consequences of the initial scope and will be revisited as the integration matures.

This integration was built for and validated against Virtuous CRM — the donor-management SaaS product Virtuous Software markets under the Virtuous CRM brand. It is not designed to integrate with any other software product, edition, or platform, whether produced by Virtuous Software or by another vendor with a similar product name.

If a subscriber is asking whether iPaaS.com can integrate with a different Virtuous Software product (or a different vendor's product that happens to share a name), contact iPaaS.com support to discuss whether a separate integration is available or feasible.

The integration ships with only the smallest viable transfer path: Virtuous CRM Gift → iPaaS.com Transaction, header-only, with a single business field (amount → Total) and four required-by-iPaaS-schema fields (SystemId, TransactionNumber, Type, Status). The remaining iPaaS.com Transaction surface (line items, taxes, payments, tracking, addresses, notes, discounts, and most scalar fields like Date, Currency, Customer reference) is unmapped by default and depends on subscribers or their MiSP to add mappings, or on a follow-up release to formalize defaults.

What this means for you: Configure and test the integration in a staging subscription, validate that the limited mapping set covers your needs, and contact iPaaS.com support if your business case depends on functionality not present today — your input directly informs the next release scope. Future releases may expand the default field set, add related-record collections, and address several of the limitations below.

The integration transfers only the top-level Gift header to an iPaaS.com Transaction. The Virtuous Gift model exposes several related-record collections that are intentionally not retrieved or transferred:

iPaaS.com Transaction line items, taxes, payments, tracking entries, addresses, notes, and discounts are also unmapped — the iPaaS.com Transaction is created with only header data.

What this means for you: Reports and downstream systems that depend on line-level detail (per-designation amounts, per-payment status, recurring-gift schedules) will not have that data on the iPaaS.com side. If you need any of the related-record types in iPaaS.com, contact iPaaS.com support to scope additional mapping collections — this is not a configuration the subscriber can self-serve.

The iPaaS.com Transaction's EmailAddress field is populated by a static value of default@ipaas.com for every gift, because Virtuous CRM Gift records do not carry an email address directly and the integration does not retrieve the related Virtuous Contact to derive one. There is no implemented mechanism to link a transferred Transaction to a Customer record in iPaaS.com — every gift lands as an orphan Transaction.

What this means for you: Downstream systems that key transactions to a contact by email (notifications, deduplication, reporting) will see every Virtuous CRM-originated Transaction tied to the same placeholder address. Before going live, replace the EmailAddress Static mapping with a Dynamic Formula that resolves the email from the related Virtuous Contact via the Gift's contactId, or accept that all Virtuous CRM Transactions will be grouped under the placeholder. Proper customer-record linkage may be addressed in a follow-up release.

The default template maps the Virtuous Gift id into the iPaaS.com Transaction's TransactionNumber field. This mapping serves two roles: visibility on the Transaction record, and — critically — a fallback collision-detection key that iPaaS.com uses to auto-link pre-existing Transactions on first sync. If a subscriber remaps TransactionNumber to a different source, the fallback auto-link breaks and the integration may create duplicate Transactions for gifts that already have a matching Transaction in iPaaS.com from another origin.

What this means for you: Do not change the TransactionNumber mapping in this collection. Treat it as required configuration in its default form. If your business process requires a different identifier on the Transaction record, raise a request with iPaaS.com support as further development will be needed before this is possible.

Because the integration uses the bare numeric Virtuous gift id as TransactionNumber, an iPaaS.com Transaction whose TransactionNumber happens to match a Virtuous gift id — for example, an Order from another commerce integration that uses a small numeric order number — can collide with Virtuous CRM gifts via the fallback collision-detection mechanism. The first Virtuous CRM webhook for a gift id matching a pre-existing Transaction will auto-link to that Transaction and overwrite it with gift-shaped data.

What this means for you: Do not deploy this integration on the same iPaaS.com subscription as another TO iPaaS.com integration that uses a numeric Transaction number in an overlapping range (for example, a Shopify or NetSuite integration whose order numbers may also be small integers). If you need to run both, contact iPaaS.com support to discuss namespacing or a redesign of the TransactionNumber mapping. The current TransactionNumber format does not include any integration-specific prefix that would prevent these collisions.

This mapping collection uses the Add/Update sync type and writes to iPaaS.com via a full-record replace on every Update. Any field on the iPaaS.com Transaction that is not explicitly mapped in this collection will be reset to an empty value on every subsequent Gift Update webhook. The six fields populated by the default template (SystemId, TransactionNumber, Total, EmailAddress, Type, Status) are preserved; every other Transaction field (Date, Currency, Customer reference, line-item totals, payment information, tracking entries, custom fields not explicitly mapped, etc.) is wiped each time the gift is updated.

What this means for you: If you populate iPaaS.com Transaction fields from any other source (a manual edit in the iPaaS.com UI, a separate integration, a downstream automation), those values will be erased the next time the underlying Virtuous CRM gift is updated. Either add explicit mappings in this collection for every field you need preserved, or accept that Virtuous CRM-originated Transactions are owned end-to-end by the Virtuous CRM integration and should not be modified outside of it. This is the expected behavior of a TO iPaaS.com Add/Update collection and is not specific to Virtuous CRM, but the small default mapping set makes the surface of wiped fields large in this integration.

The integration cannot create, modify, or delete Virtuous CRM webhook subscriptions on the subscriber's behalf via the Virtuous API. The subscriber must log in to the Virtuous CRM admin UI and create the webhook manually — pasting the iPaaS.com payload URL into the Settings → Connectivity → Webhooks page and selecting the Gift Create and Gift Update events.

What this means for you: Plan a one-time manual configuration step in Virtuous CRM as part of installation. The Virtuous CRM Installation Instructions article walks through the screens. Any post-install changes (rotating the iPaaS.com payload URL, adding events, re-enabling the webhook after a 24-hour auto-pause) also have to be performed in the Virtuous CRM UI, not in iPaaS.com.

The iPaaS.com payload URL for Virtuous CRM webhooks embeds the per-subscription Webhook API Key as a query parameter (?webhookapikey={WebhookAPIKey}). When the auto-generated Webhook API Key happens to contain a forward slash (/), Virtuous CRM cannot parse the resulting URL — the / is treated as a path separator rather than as part of the query value, the URL becomes structurally invalid, and the webhook either fails to save in the Virtuous CRM admin UI or fires against the wrong path and is silently dropped. URL-encoding the slash to %2F does not work consistently across the Virtuous CRM webhook saver. The integration has no mechanism to regenerate the Webhook API Key from the subscriber side.

What this means for you: If your Webhook API Key contains a / character, contact iPaaS.com support and request a new key. Support can regenerate the key until one is produced that does not contain a slash, then provide the new payload URL for use in the Virtuous CRM Webhooks configuration. You can spot this case by inspecting the key on the iPaaS.com Virtuous CRM Subscription page (click the unmask / eye icon next to the Webhook API Key) before pasting the URL into Virtuous CRM. This is a known issue tracked for a future fix.

The integration is unidirectional. iPaaS.com can receive new and updated Virtuous CRM gifts and mirror them as Transactions, but it cannot push Transactions, changes, or deletes back to Virtuous CRM. The integration's Gift model implements only the Get operation; Create, Update, and Delete are not implemented.

What this means for you: Treat Virtuous CRM as the system of record for gift data. Changes made to iPaaS.com Transactions that originated from Virtuous CRM will not propagate back to the gift record in Virtuous CRM. If you need reverse-sync, contact iPaaS.com support to discuss alternatives.

The integration has no bulk-pull or initialization mode. Only gifts received through the Gift Create / Gift Update webhook stream (or pulled individually via the iPaaS.com Manual Sync page using a specific gift id) reach iPaaS.com. Gifts that existed in Virtuous CRM before the integration was installed will not be back-filled automatically.

What this means for you: If you need historical gifts in iPaaS.com, either accept that only forward-going gifts will appear, or plan a manual back-fill using the Manual Sync page (one gift id at a time). For large historical sets, see our article on how to use Postman Runner to accomplish this.

Outbound deletes (iPaaS.com → Virtuous CRM) are not implemented — the integration's Gift model's Delete operation is intentionally not built, so iPaaS.com cannot remove or soft-delete gifts in Virtuous CRM.

Inbound deletes (Virtuous CRM → iPaaS.com) are not propagated either — the integration only subscribes to Gift Create and Gift Update webhooks, not Gift Delete. A gift deleted in Virtuous CRM leaves its matching iPaaS.com Transaction untouched.

What this means for you: Track deletions through a side-channel — for example, periodic reconciliation between Virtuous CRM exports and iPaaS.com Transaction lists — and reflect them manually in iPaaS.com if your downstream processes require it.

The Virtuous Gift currencyCode, exchangeRate, and baseCurrencyCode fields are exposed as source values but are not mapped in the default template. The iPaaS.com Transaction Total receives the raw amount value with no currency normalization or conversion.

What this means for you: If your Virtuous CRM environment processes gifts in multiple currencies, the iPaaS.com side will see all Total values as bare numbers with no currency context. Multi-currency subscribers should add mappings for the relevant currency fields and decide whether to convert to a base currency in a Dynamic Formula before going live.

Virtuous CRM enforces an hourly request limit per API token. When iPaaS.com hits the limit during a burst of activity, the affected transfers are automatically rescheduled to resume after the limit resets. No work is lost, but the transfer queue can take materially longer than the hourly window suggests to drain after a large burst.

What this means for you: Schedule any large manual back-fill or surge work outside of peak hours, and accept that during sustained bursts the iPaaS.com side will lag Virtuous CRM by the rate-limit reset interval. No subscriber action is required when the rate limit is hit — the integration handles rescheduling automatically.

Virtuous CRM retries failed webhook deliveries automatically, but if a webhook fails 10 times within a 24-hour window Virtuous CRM pauses it. Once paused, the integration receives no further automatic transfers until the subscriber re-enables the webhook in the Virtuous CRM admin UI.

What this means for you: If automatic transfers stop unexpectedly, check the webhook's status in the Virtuous CRM admin UI before troubleshooting further. Use the iPaaS.com Manual Sync page to back-fill any gifts that arrived during the paused window after re-enabling the webhook.

This document covers 14 known limitations of the Virtuous CRM integration in its initial release. For detailed technical documentation of how individual fields, mappings, and the transfer workflow operate, see the mapping collection description for the Add/Update Virtuous CRM Gift TO iPaaS.com collection and the long-form Virtuous CRM to iPaaS.com Gift Mapping Documentation article. Limitations are expected to be revisited and reduced in the next release scope.