If you want to build an integration creating or transferring Gift information in and out of Virtuous, this article will walk you through some key insights and best practices.

Article Table of Contents

Definition of a Gift
Syncing Gifts FROM Virtuous
Syncing Gifts TO Virtuous
Passthrough Gifts (aka Soft Credits)
Donor Paid Costs (Processing Fees)
Premiums
Recurring Gifts
Pledges

Definition of a Gift

Before we dive into the details, let’s make sure that Gifts is the best place for your data. In Virtuous, we define gifts as donations to the organization as part of your fundraising. If these aren’t truly donations, check out our article Non-Donation Integration Best Practices. Virtuous doesn’t distinguish between purchases and donations so that’s why we advise custom collections for non-donation related transactions. Also see Event Integration Best Practices if the purchase is an event registration alone and not a donation.

There are cases where there is a donation that was incentivized by a premium/benefit ("Give $30 today and receive our t-shirt.") This is still considered a gift where you can attach a premium to deduct the fair market value. We’ll get into that a bit later.

Syncing Gifts FROM Virtuous

To send gifts from Virtuous to another source, we advise using our gift webhook. You can learn more about our webhooks here. In short, as new gifts are entered into Virtuous, the Gift webhook will fire and send the gift information you want to your other platform.

Syncing Gifts TO Virtuous

Best practice is to send gifts over in bulk through our Gift and Contact Import tool. By posting through our batch transaction end point you reduce the risk of running into our rate limit (1500 calls/hour). Not only does this reduce the risk of a rate limit, but it also utilizes our Gift and Contact Import tool which has built-in matching and validation logic. Additionally it will flag any contact information that’s different for the Virtuous user to confirm. This makes sure the data is clean going in the first time and reduces duplicates.

Check out our article Contacts Integration Best Practices for suggested contact information to send over with the gift to help Virtuous identify the existing record or create a new contact. Note that for gift transactions, the Transaction Source (when provided on the gift) will also be referenced as the Reference Source of the contact. So only the Transaction Source is needed. Always include a Reference ID (the ID of the contact in your system) as Virtuous will automatically select the record with that ID and append the ID to any new records it finds or creates.

Along with the Contact Information, you will want to send over the gift information. At the very least you will also want the following:

• Transaction Source and Transaction ID: The name and ID of the originating system, that way a Virtuous user can look up by the ID to easily find it in Virtuous.
• Gift Date: Date of the gift.
• Gift Type: The list of Gift Types is hard-coded in Virtuous. The values include: Cash, Check, Credit, Cryptocoin, Electronic Fund Transfer (EFT), Noncash (or an In-Kind Gift), Stock, Other, Reversing Transaction, and Qualified Charitable Contribution.
• Gift Amount: Amount of the gift.
• Segment: What motivated the gift to be given. This will need to exist before gifts can be applied. You can require the Virtuous user to have the same segment codes in Virtuous as in this other system, or you can have the integration search and create the Segment codes by referencing Campaign Integration Best Practices.
• Project: This is where the money is designated to go. Virtuous does accept project splits, so if your system allows for multiple designations on a gift, be sure to passthrough the project split information. Similar to segments, you can have the Virtuous user ensure the projects in Virtuous match the funds in source system. Or the integration can search for existing projects or create new projects. Keep in mind that projects have to be present already in order for the gifts to attach to. You can denote project splits with designations in the json.
• Batch: Make sure you include logic for naming batches making it easy to identify. This might be the source name and the date for example.

Passthrough Gifts (aka Soft Credits)

Passthrough gifts, sometimes known as soft credits, are a way of noting who the original donor is on a gift. You can learn more in this article, but want to clarify that passthroughs should not be used for peer-to-peer, tracking a fundraiser, or any other use outside of someone giving their gift through another entity like a donor advised fund, etc.

Our Gift and Contact Import tool allows you to not only search for the contact, but also the passthrough contact. So there's no need to add complex logic for creating and matching passthroughs. Remember, if your using the Reference IDs mentioned in our Contacts Integration Best Practices then you can use the Reference ID, also include the passthrough contact information as well in case the Reference ID doesn’t live in Virtuous yet to allow Virtuous to connect.

Currently, you may only have one passthrough associated on a single gift and it’s assumed the entire amount is credited to the passthrough.

Donor Paid Costs (Processing Fees)

If you want to reflect the credit card processing fees the donor has chose to cover, this can be done by a Project Split. A Project in Virtuous is used to reflect what the donation is funding. When a donor covers the cost of processing fees, the fees should be applied to a non tax deductible project. The project name is typically Donor Paid Costs with a project code of CREDITCARDCOSTS and the project itself is not tax deductible. You can denote project splits with designations in the json.

Premiums

A Premium in Virtuous is an entity that designates the fair market value of an item given to a donor for a gift they gave to the organization. Let’s say the nonprofit is giving away a t-shirt when a gift of $100 is donated. Someone gives a gift for $100, but not all of what they donated is tax deductible. If the t-shirt has a Fair Market Value of $15, this will need to be recorded on the gift in Virtuous as a Premium so that the receipt shows the tax deductible donation amount of $85 minus the $15 fair market value of the t-shirt. The best way to record this in Virtuous is using Premiums. 

This means the integration will want to create the following in order:

1. Create each item offered as a Premium
   Creating these offerings as a premium first ensures that when the gift comes in, the premium already exists to avoid any errors. You could also have the Virtuous user create the premiums exactly as they are in the source system rather than adding through an integration. It depends on how often new premiums are offered which option would be best.
   
   
2. Send the gift over with the following:
   a. Premium Code
   b. Premium Quantity

When using Premiums for an event registration, see Event Integration Best Practices for event specific examples.

Recurring Gifts

First step on recurring gifts is to confirm definitions between the source system and Virtuous. A recurring gift in Virtuous basically creates the commitment of a recurring gift and allows tracking of payments expected to come in. A recurring gift is it’s own entity that the gifts can attach to as they come in. A Virtuous user will be able to identify when a payment is missed so they can then reach out to the donor about additional payments.

Making a recurring gift through the API is simple. Just add the Frequency to the first gift given with the recurring gift commitment. Virtuous will flag creating the recurring gift from the frequency using the gift information as the recurring gift. Do not include the frequency on subsequent gifts as it will try to create additional recurring gifts. Recurring gift frequencies are:

• Weekly
• Bimonthly
• Monthly
• Quarterly
• Semiannually
• Annually
• Biennially

Pledges

A pledge represents a commitment from a donor to give a specific sum of money over a set period of time. An example being a $10,000 commitment, that will be paid $2,000 every year for the next 5 years. Frequencies are:

• Weekly
• Bimonthly
• Monthly
• Quarterly
• Semiannually
• Annually
• Biennially

In order to create a pledge, you will need to pass the following through on the transaction:

• Expected Fulfillment Date
• Frequency
• Pledge Amount

Check out these other articles to learn more about other best practices surrounding related contact data:

Contact Integration

Campaign Integration

Non-Donation Item Integration

Custom Event Integration