Virtuous CRM to iPaaS.com Gift Mapping Documentation

Virtuous CRM Gift records can be transferred from Virtuous CRM into iPaaS.com as Transaction records through webhook-driven automatic transfers or one-at-a-time Manual Sync. Each Virtuous CRM Gift is mirrored as one iPaaS.com Transaction, keyed by the Virtuous gift id, with both new gifts (Gift Create webhooks) and subsequent edits (Gift Update webhooks) handled by a single combined Add/Update mapping collection.

Note: The initial release ships with the smallest viable transfer path — Gift header → Transaction header, with one business field (amount → Total) and the four iPaaS.com-required fields. Customer linkage, related-record transfer (designations, premiums, pledge payments, recurring gift payments, passthroughs), historical sync, bidirectional sync, and delete propagation are not implemented. See the Virtuous CRM Integration Known Limitations document for the full list.

ID Format

Manual Sync ID Format

Enter the Virtuous CRM gift id (the numeric primary key, for example 45) into the iPaaS.com Manual Sync page to transfer a specific gift. This is the same id shown in the Virtuous UI and in the gift URL.

External ID Format (saved after sync)

After a successful transfer, iPaaS.com saves the Virtuous CRM gift id as the external ID on a dedicated external-ID record that the platform maintains for this collection. This external-ID record is the primary mechanism that routes subsequent Gift Update webhooks (and re-runs of Manual Sync for the same id) back to the existing iPaaS.com Transaction for an Update rather than creating a duplicate. The Virtuous gift id is also mapped into the iPaaS.com Transaction's TransactionNumber field by the default template — both for visibility and as a fallback collision-detection key (see Collision handling under Duplicate or Conflicting Mappings below). The TransactionNumber mapping must remain bound to the Virtuous gift id in the current release — remapping it disables the fallback auto-link and can produce duplicate Transactions when a gift is first synced against an iPaaS.com tenant that already has a matching Transaction from another origin. See the Known Limitations document for the full implications.

Deleted Record Support

Outbound deletes (iPaaS.com → Virtuous CRM) are not supported. The integration's Gift model implements only the Get method for retrieving gifts from Virtuous CRM; the Create, Update, and Delete methods are not implemented, so the integration cannot push deletions or any other writes back to Virtuous CRM. Delete mappings are not included in the default template.

Inbound deletes (Virtuous CRM → iPaaS.com) are also not propagated. The integration only subscribes to Gift Create and Gift Update webhook events; there is no Gift Delete subscription. If a gift is deleted in Virtuous CRM, the matching iPaaS.com Transaction is not deleted or marked. Subscribers who need to track deletions must coordinate that side-channel separately (for example, by periodically reviewing Virtuous CRM exports against iPaaS.com Transactions).

Custom Field Support

Custom fields on a Virtuous CRM Gift can be transferred 1:1 into iPaaS.com Transaction custom fields of the same data type. The integration retrieves the gift's custom fields as part of the standard GET /api/Gift/{id} call — no additional API calls or conversion functions are required. To map a custom field, create a mapping with mapping_type = Field, source_table = Custom, source_value = <Virtuous CRM custom field API name>, destination_table = Custom, and destination_field = <iPaaS.com custom field API name>.

The template ships with eight example custom-field mappings demonstrating the supported data types (Text, Paragraph, List, MultiselectList, Boolean, Date, Decimal, Link). These reference custom fields named VirtuousCustomText, VirtuousCustomParagraph, etc. and are templates only — replace the source names with your Virtuous CRM custom field API names before going live, or remove the examples entirely if not needed.

When a transformation is needed between the Virtuous source value and the iPaaS.com destination value (formatting, multi-source composition, conditional logic, vocabulary translation, etc.), use a Dynamic Formula mapping.

Mapping Collection Status

Status: Enabled. The collection has no filter formula applied — every gift received from Virtuous CRM is processed.

Trigger Events:

Gift Create: webhook event in Virtuous CRM. Triggers an Add transfer to iPaaS.com.
Gift Update: webhook event in Virtuous CRM. Triggers an Update transfer to iPaaS.com (matched on the existing iPaaS.com Transaction via iPaaS.com's external-ID record for this collection, keyed on the Virtuous gift id that was saved at initial sync).

Subscribers may add a Mapping Filter to skip gifts they do not want processed (for example, gifts under a minimum amount, gifts in particular segments, or test data).

Duplicate or Conflicting Mappings

No sibling mapping collections operate on the iPaaS.com Transaction entity for this subscription as of the initial release.

Collision handling

The integration's collision behavior is fixed and is not user-configurable. Two matching mechanisms decide whether an incoming webhook produces an Add or an Update:

Primary match — external-ID record. After the first successful sync of a gift, iPaaS.com maintains an external-ID record linking the Virtuous gift id to the iPaaS.com Transaction. Subsequent webhooks for the same gift id route directly to the linked Transaction for an Update.
Fallback match — TransactionNumber. If no external-ID record yet exists for the incoming gift id (typically on first sync, or after the external-ID record has been cleared), iPaaS.com also looks for an existing iPaaS.com Transaction whose TransactionNumber matches the Virtuous gift id. If a match is found, the Transaction is linked automatically — iPaaS.com creates the external-ID record pointing to the existing Transaction and performs an Update, rather than creating a duplicate. This is the practical reason the default template maps the gift id to TransactionNumber and why that mapping must not be modified in the current release.

If neither mechanism finds a match, a new iPaaS.com Transaction is created and a new external-ID record is added.

Cross-integration collision risk

Because the fallback match uses the bare numeric Virtuous gift id against the iPaaS.com Transaction's TransactionNumber field, this integration must not coexist on the same iPaaS.com subscription with another TO iPaaS.com integration whose TransactionNumber values may overlap the Virtuous gift id range — for example, a commerce integration whose order numbers are small integers. The first Virtuous CRM webhook for a gift id matching a pre-existing non-Virtuous CRM Transaction will auto-link to that Transaction and overwrite it with gift-shaped data. The TransactionNumber format does not yet include an integration-specific prefix that would prevent these collisions. See the Known Limitations document for the operational implications.

Unmapped-field overwrite risk (Add/Update direction TO iPaaS.com)

Because this collection handles both Add and Update in a single Add/Update sync type and writes to iPaaS.com via a full-record replace, any field on the iPaaS.com Transaction that is not mapped here will be overwritten with an empty value on every Update transfer. The six mapped fields (SystemId, TransactionNumber, Total, EmailAddress, Type, Status) are preserved on each update; every other field on the iPaaS.com Transaction (for example, Date, Currency, Customer reference, line-item totals, payment information, custom fields not explicitly mapped, etc.) will be reset. If your business process requires preserving additional iPaaS.com Transaction fields across Update transfers — including any custom fields that downstream consumers populate independently — add explicit mappings for those fields in this collection.

Supported Child Collections

This collection does not define child collections. See Additional Notes below for the list of Virtuous Gift related entities (designations, premiums, pledge payments, etc.) that are intentionally excluded from this transfer.

Virtuous CRM Caveats

Rate limit. Virtuous CRM enforces an hourly request limit per API token. If the limit is reached during a burst of activity, the affected transfers are automatically rescheduled to resume after the limit resets. No subscriber action is required and no transfers are lost; the transfer queue may simply take longer to drain than the hourly window would suggest if the burst was large.
Permission errors are not rescheduled. If a transfer fails because of a permission problem (the user account behind the integration's OAuth tokens has been revoked, locked, or has insufficient scopes), the failure is recorded in the iPaaS.com error log and is not retried automatically. The subscriber must resolve the access issue and then manually re-run the affected transfers.
Credential lifetime and re-authentication. The integration manages session refresh automatically using the credentials entered on the Subscription Settings page. If the Virtuous CRM user account is locked, has its password rotated, or has its scopes changed, transfers will start to fail with a permission error — re-enter the updated credentials on the iPaaS.com Subscription Settings page to restore service.
Webhook setup is manual. Webhook subscriptions cannot be configured by the integration on the subscriber's behalf — the subscriber must create the webhook manually in the Virtuous CRM admin UI and paste the iPaaS.com payload URL into it. See Setup Requirements below for the step-by-step.
Webhook retry and auto-pause. Virtuous CRM will retry failed webhook deliveries automatically. If a webhook fails 10 times within a 24-hour window, Virtuous CRM automatically pauses it, and the subscriber must re-enable it in the Virtuous CRM admin UI before automatic transfers resume. Use the iPaaS.com Manual Sync page as a workaround for any gifts that arrived during a paused window.
Virtuous CRM Gift API reference: Gifts endpoint documentation. Cross-reference this when adding additional field mappings — the API documentation describes the allowed values for enumerated fields (for example, giftType), date format expectations, and the structure of nested objects.

iPaaS.com Caveats

Static field overrides. Three of the populated iPaaS.com Transaction mappings (EmailAddress, Type, Status) are populated with Static values rather than from Virtuous source fields. Subscribers or their MiSP should review each Static and decide whether to keep the default, override the Static, or replace the mapping with a Dynamic Formula. The Type=Order and Status=Complete defaults are appropriate for most subscribers; the EmailAddress default should be reviewed before going live.
Transactions are not initialized. The integration does not support an initial / historical sync of pre-existing Virtuous CRM gifts. Only gifts received through webhooks or pulled individually via the Manual Sync page reach iPaaS.com.

Setup Requirements

For full setup steps see the Installation Instructions and Connections and Settings articles. The integration-wide setup (Virtuous CRM user account credentials, subscription configuration, webhook registration in Virtuous CRM, optional Virtuous custom-field setup) is documented there and not repeated here.

Integration Flow

When a Gift Create or Gift Update webhook arrives from Virtuous CRM, the integration runs the following sequence for a single gift:

Receive the webhook payload from Virtuous CRM. The payload identifies the gift by its numeric id and indicates whether the event is a create or update.
Retrieve the full gift record from Virtuous CRM. The integration calls GET /api/Gift/{id} using its OAuth access token, refreshing the token automatically if it has expired.
Run the retrieved record through this mapping collection. Source values are read from the Virtuous Gift record, defaults / statics / dynamic formulas are evaluated, and the resulting field set is built for the iPaaS.com Transaction.
Create or update the iPaaS.com Transaction. The platform decides between Add and Update via two checks (see Collision handling below for the full description): first, an existing external-ID entry matching the Virtuous gift id routes the transfer to an Update against the linked Transaction; if no external-ID entry exists yet, the platform also looks for an existing iPaaS.com Transaction whose TransactionNumber matches the gift id and auto-links it. Only if neither match is found is a new Transaction created. Updates are performed as a full-record replace. On a successful Add or auto-link, the platform creates or updates the external-ID entry so it is the primary match on the next webhook.

If the Virtuous CRM API returns a rate-limit response during step 2, the transfer is automatically rescheduled — see the Virtuous CRM Caveats section. There are no child API calls for related Virtuous entities such as gift designations, premiums, pledge payments, recurring gift payments, or passthroughs; those are out of scope and are not retrieved as part of this flow.

Mappings

Add/Update Virtuous CRM Gift TO iPaaS.com

Mapping Filter: None — every gift received from Virtuous CRM is processed.

Description: Transfers a single Virtuous CRM Gift into an iPaaS.com Transaction. The combined Add/Update sync type means the same mapping definition handles both Gift Create and Gift Update webhooks; the integration decides between Add and Update by first looking up the Virtuous gift id in iPaaS.com's external-ID record for this collection, and falling back to a match against an existing iPaaS.com Transaction's TransactionNumber when no external-ID entry exists yet. See Collision handling above for the full description.

Field Mapping Table

Mapping Type	Source Field (Virtuous CRM)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`SpaceportSystemId`	SystemId	Required. iPaaS plumbing — resolves to the iPaaS.com subscription's system ID at transfer time so the Transaction is attributed correctly. Do not change or remove this mapping.
Field	`Id` (Gift primary key)	TransactionNumber	Required — do not remap. Mapped from the Virtuous Gift `id`. Two roles: (1) visibility on the iPaaS.com Transaction, and (2) fallback collision-detection key — when no external-ID record yet exists for the incoming gift `id`, iPaaS.com matches against existing Transactions on TransactionNumber and auto-links rather than creating a duplicate. After the first sync the external-ID record takes over as the primary match. In the current release this mapping must remain bound to the Virtuous gift `id`; remapping it breaks duplicate detection.
Field	`Amount`	Total	Recommended. The gift dollar amount, transferred 1:1. Currency code, exchange rate, and base currency code are available as source values but are not mapped in the template.
Static	`"Order"`	Type	Required. Hardcoded transaction type. Allowed values for Type: `Order`, `Shipment`, `Invoice`, `Hold`, `Quote`, `Ticket`, `Return`, `Validated Return`, `Job`, `Fulfillment`. Override with a different Static or a Dynamic Formula if your downstream process uses transaction-type segmentation.
Static	`"Complete"`	Status	Required. Hardcoded transaction status. Allowed values for Status: `Pending`, `Complete`, `Cancelled`, `Shipped`, `Backorder`, `Refunded`, `Partially Refunded`, `Partially Shipped`, `Awaiting Pickup`, `Awaiting Payment`, `On Hold`, `Processing`, `Returned`, `Draft`. Override if your business process distinguishes status states.
Static	`"default@ipaas.com"`	EmailAddress	Optional (not required by the iPaaS.com Transaction schema, but supplied because Virtuous CRM Gift records do not carry an email). Replace this Static with a Dynamic Formula that resolves the email from the related Virtuous Contact via the Gift's `contactId` if downstream systems use EmailAddress for contact matching.
Field (Custom)	`VirtuousCustomBoolean`	VirtuousCustomBoolean	Optional / template example. Demonstrates a boolean custom-field transfer. Replace the source/destination names with the actual Virtuous CRM and iPaaS.com custom field API names, or remove the example before going live.
Field (Custom)	`VirtuousCustomDate`	VirtuousCustomDate	Optional / template example. Demonstrates a date custom-field transfer. Replace or remove before going live.
Field (Custom)	`VirtuousCustomDecimal`	VirtuousCustomDecimal	Optional / template example. Demonstrates a decimal / numeric custom-field transfer. Replace or remove before going live.
Field (Custom)	`VirtuousCustomLink`	VirtuousCustomLink	Optional / template example. Demonstrates a link / URL custom-field transfer. Replace or remove before going live.
Field (Custom)	`VirtuousCustomList`	VirtuousCustomList	Optional / template example. Demonstrates a single-select list custom-field transfer. When source and destination vocabularies disagree, replace this Field mapping with a Dynamic Formula that translates the value. Replace or remove before going live.
Field (Custom)	`VirtuousCustomMultiselectList`	VirtuousCustomMultiselectList	Optional / template example. Demonstrates a multi-select list custom-field transfer. Use a Dynamic Formula if the destination represents multi-select differently. Replace or remove before going live.
Field (Custom)	`VirtuousCustomParagraph`	VirtuousCustomParagraph	Optional / template example. Demonstrates a paragraph / long-text custom-field transfer. Replace or remove before going live.
Field (Custom)	`VirtuousCustomText`	VirtuousCustomText	Optional / template example. Demonstrates a single-line text custom-field transfer. Replace or remove before going live.

Error Handling

Errors from this mapping collection appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs. For the full catalog of error messages, descriptions, and resolution steps see the Error Messages article.

Testing & Validation

Test Scenarios

Create a new gift in Virtuous CRM and verify it appears in iPaaS.com. Create a test gift in Virtuous CRM with a known amount and a recognizable identifier. Confirm that the Gift Create webhook fires (verify in Virtuous CRM webhook delivery logs), then confirm the matching iPaaS.com Transaction appears in the iPaaS.com Transaction list with TransactionNumber = Virtuous gift id and Total = gift amount.
Update an existing gift in Virtuous CRM and verify the change propagates. Edit the test gift (for example, change the amount or any mapped custom field), confirm the Gift Update webhook fires, and confirm the existing iPaaS.com Transaction is updated rather than duplicated. Verify the Update preserves the TransactionNumber.
Trigger Manual Sync from iPaaS.com. From the iPaaS.com Manual Sync page, enter the Virtuous gift id and confirm the sync runs end-to-end with the same result as the webhook path.
Verify required-field validation. Intentionally break one of the required mappings (for example, change the Status static to an empty value) and attempt a sync. Confirm an error appears in the iPaaS.com error log and that the Transaction is not partially written. Restore the mapping after testing.
Verify Out of Scope behavior. Add a gift in Virtuous CRM with a designation, premium, or pledge payment attached. Confirm the gift's scalar fields transfer to iPaaS.com but the related-record collections do not.
Verify rate-limit auto-reschedule (optional). If you can safely exhaust the hourly limit in a test environment, trigger a burst that exceeds it and confirm that affected transfers are rescheduled rather than lost.

Validation Checklist

Gift Create webhook fires in Virtuous CRM and the Transaction appears in iPaaS.com.
Gift Update webhook fires and updates the existing Transaction (no duplicate).
Manual Sync with a Virtuous gift id works end-to-end.
TransactionNumber on the iPaaS.com side matches the Virtuous gift id for every test transfer.
Total on the iPaaS.com side matches the Virtuous gift amount for every test transfer.
EmailAddress on the iPaaS.com side reflects the chosen subscriber configuration (default static, overridden static, or Dynamic Formula).
Any subscriber-specific custom field mappings (replacing the eight template examples) transfer values correctly.
OAuth refresh has been validated (run a transfer more than 15 days after install to confirm access-token refresh works).

iPaaS.com Transactions page showing a synced Virtuous CRM Gift as Transaction number 20136 with Type Order, Status Complete, and Total 99.98

Additional Notes

Out of Scope

The following Virtuous Gift related-record types are intentionally excluded from this mapping collection and are not transferred to iPaaS.com:

Gift Designations (giftDesignations) — project / fund allocations attached to the gift.
Gift Premiums (giftPremiums) — premiums (thank-you items) associated with the gift.
Pledge Payments (pledgePayments) — payment records tied to pledge gifts.
Recurring Gift Payments (recurringGiftPayments) — payment records tied to recurring gifts.
Gift Passthroughs (giftPassthroughs) — passthrough-credit records.

If your business process requires any of these to land in iPaaS.com, contact iPaaS.com support — additional mapping collections will be needed.

Currency Handling

The Virtuous Gift currencyCode, exchangeRate, and baseCurrencyCode fields are available as source values but are not mapped in the template. The iPaaS.com Transaction Total receives the raw amount value with no currency normalization. Multi-currency subscribers should add the appropriate mappings before going live.