Module: Virtuous::Client::Gift

Included in:
Virtuous::Client
Defined in:
lib/virtuous/client/gift.rb

Overview

Gift data

{
  contact_id: [Integer],
  gift_type: [String],
  gift_date: [Time],
  amount: [Float],
  transaction_source: [String],
  transaction_id: [String],
  batch: [String],
  segment_id: [Integer],
  receipt_segment_id: [Integer],
  media_outlet_id: [Integer],
  notes: [String],
  is_private: [Boolean],
  receipt_date: [Time],
  contact_individual_id: [Integer],
  contact_passthrough_id: [Integer],
  cash_accounting_code: [String],
  state: [String],
  is_tax_deductible: [Boolean],
  gift_ask_id: [Integer],
  passthrough_gift_ask_id: [Integer],
  grant_id: [Integer],
  contact_membership_id: [Integer],
  currency_code: [String],
  exchange_rate: [Float],
  check_number: [String],
  credit_card_type: [String],
  cryptocoin_type: [String],
  transaction_hash: [String],
  coin_sold_for_cash: [Boolean],
  coin_amount: [Float],
  date_coin_was_sold: [Time],
  coin_sale_amount: [Float],
  ticker_symbol: [String],
  number_of_shares: [Float],
  ira_custodian: [String],
  stock_sold_for_cash: [Boolean],
  date_stock_was_sold: [Time],
  stock_sale_amount: [Float],
  non_cash_gift_type_id: [Integer],
  non_cash_gift_type: [String],
  description: [String],
  non_cash_sold_for_cash: [Boolean],
  date_non_cash_was_sold: [Time],
  non_cash_original_amount: [Float],
  non_cash_sale_amount: [Float],
  gift_designations: [
    {
      project_id: [Integer],
      amount: [Float],
      state: [String]
    }
  ],
  gift_premiums: [
    {
      premium_id: [Integer],
      quantity: [Integer],
      state: [String]
    }
  ],
  pledge_payments: [
    {
      id: [Integer],
      amount: [Float],
      state: [String]
    }
  ],
  recurring_gift_payments: [
    {
      id: [Integer],
      amount: [Float],
      state: [String]
    }
  ],
  tribute_type: [String],
  tribute_id: [Integer],
  tribute_description: [String],
  acknowledgee_id: [Integer],
  reversed_gift_id: [Integer],
  custom_fields: [
    {
      name: [String],
      value: [String],
      display_name: [String]
    }
  ]
}

Instance Method Summary collapse

Instance Method Details

#create_gift(data) ⇒ Hash

Creates a gift.

Examples:

client.create_gift(
  contact_id: 1, gift_type: 'Cash', amount: 10.5, currency_code: 'USD',
  gift_date: Date.today
)



164
165
166
 
# File 'lib/virtuous/client/gift.rb', line 164

def create_gift(data)
  parse(post('api/Gift', format(data)))
end

#create_gifts(gifts) ⇒ Array

Creates gifts in bulks of up to 100 at a time.

Examples:

client.create_gifts([
  {
    contact_id: 1, gift_type: 'Cash', amount: 10.5, currency_code: 'USD',
    gift_date: Date.today
  },
  {
    contact_id: 2, gift_type: 'Cash', amount: 5.0, currency_code: 'USD',
    gift_date: Date.today
  }
])



188
189
190
191
192
 
# File 'lib/virtuous/client/gift.rb', line 188

def create_gifts(gifts)
  request_body = gifts.map { |gift| format(gift) }
  response = post('api/Gift/Bulk', request_body)
  response.map { |gift| parse(gift) }
end

#delete_gift(id) ⇒ Object

Delete a gift.

Examples:

client.delete_gift(1)



223
224
225
 
# File 'lib/virtuous/client/gift.rb', line 223

def delete_gift(id)
  delete("api/Gift/#{id}")
end

#find_gift_by_transaction_id(transaction_source, transaction_id) ⇒ Hash

Fetches a gift record by transaction id.

Examples:

client.find_gift_by_transaction_id('source', 1)



145
146
147
148
 
# File 'lib/virtuous/client/gift.rb', line 145

def find_gift_by_transaction_id(transaction_source, transaction_id)
  encoded_id = transaction_id.is_a?(String) ? encode(transaction_id) : transaction_id
  parse(get("api/Gift/#{encode(transaction_source)}/#{encoded_id}"))
end

#get_contact_gifts(contact_id, **options) ⇒ Hash

Gets the gifts made by a contact.

Examples:

client.get_contact_gifts(1, take: 10)

Output

{ list: [...], total: n }

Options Hash (**options):

  • :sort_by (String) —

    The field to be sorted. Supported: Id, GiftDate, Amount, Batch, CreatedDateTime.

  • :descending (Boolean) —

    The direction to be sorted.

  • :skip (Integer) —

    The number of records to skip. Default = 0.

  • :take (Integer) —

    The number of records to take. Default = 10.



113
114
115
116
117
118
119
120
 
# File 'lib/virtuous/client/gift.rb', line 113

def get_contact_gifts(contact_id, **options)
  options = options.slice(:sort_by, :descending, :skip, :take)

  parse(get(
          "api/Gift/ByContact/#{contact_id}",
          format(options)
        ))
end

#get_gift(id) ⇒ Hash

Fetches a gift record by id.

Examples:

client.get_gift(1)



131
132
133
 
# File 'lib/virtuous/client/gift.rb', line 131

def get_gift(id)
  parse(get("api/Gift/#{id}"))
end

#import_gift(data) ⇒ Object

Creates a gift. This ensures the gift is matched using the Virtuous matching algorithms for Contacts, Recurring gifts, Designations, etc.

Transactions are posted to the API and are set to a holding state. At midnight, transactions are bundled into imports based on the source they were posted with. The organization reviews the imported transactions, and then clicks run.

Full list of accepted fields

{
  transaction_source: [String],
  transaction_id: [String],
  contact: [Contact],
  gift_date: [String],
  cancel_date: [String],
  gift_type: [String],
  amount: [String],
  currency_code: [String],
  exchange_rate: [Float],
  frequency: [String],
  recurring_gift_transaction_id: [String],
  recurring_gift_transaction_update: [Boolean],
  pledge_frequency: [String],
  pledge_transaction_id: [String],
  pledge_expected_fullfillment_date: [String],
  batch: [String],
  notes: [String],
  segment: [String],
  media_outlet: [String],
  receipt_date: [String],
  receipt_segment: [String],
  cash_accounting_code: [String],
  tribute: [String],
  tribute_dedication: {
    tribute_id: [Integer],
    tribute_type: [String],
    tribute_first_name: [String],
    tribute_last_name: [String],
    tribute_city: [String],
    tribute_state: [String],
    acknowledgee_individual_id: [Integer],
    acknowledgee_first_name: [String],
    acknowledgee_last_name: [String],
    acknowledgee_address: [String],
    acknowledgee_city: [String],
    acknowledgee_state: [String],
    acknowledgee_postal: [String],
    acknowledgee_email: [String],
    acknowledgee_phone: [String]
  },
  is_private: [Boolean],
  is_tax_deductible: [Boolean],
  check_number: [String],
  credit_card_type: [String],
  non_cash_gift_type_id: [Integer],
  non_cash_gift_type: [String],
  non_cash_gift_description: [String],
  stock_ticker_symbol: [String],
  stock_number_of_shares: [Integer],
  ira_custodian: [String],
  submission_url: [String],
  designations: [
    {
      id: [Integer],
      name: [String],
      code: [String],
      amount_designated: [String]
    }
  ],
  premiums: [
    {
      id: [Integer],
      name: [String],
      code: [String],
      quantity: [String]
    }
  ],
  custom_fields: [Hash],
  custom_objects: [
    {
      name: [String],
      fields: [
        {
          name: [String],
          value: [String]
        }
      ]
    }
  ],
  contact_individual_id: [Integer],
  passthrough_contact: [Contact],
  event_attendee: {
    event_id: [Integer],
    event_name: [String],
    invited: [Boolean],
    rsvp: [Boolean],
    rsvp_response: [Boolean],
    attended: [Boolean]
  }
}

Examples:

client.import_gift(
  gift_type: 'Cash', amount: 10.5, currency_code: 'USD', gift_date: Date.today,
  contact: {
    contact_type: 'Organization', name: 'Org name', first_name: 'John',
    last_name: 'Doe', email: '[email protected]'
  }
)



341
342
343
 
# File 'lib/virtuous/client/gift.rb', line 341

def import_gift(data)
  post('api/v2/Gift/Transaction', format(data))
end

#import_gifts(transactions:, **shared_fields) ⇒ Object

Creates a batch of gift transactions. This ensures the gift is matched using the Virtuous matching algorithms for Contacts, Recurring gifts, Designations, etc.

Transactions are posted to the API and are set to a holding state. At midnight, transactions are bundled into imports based on the source they were posted with. The organization reviews the imported transactions, and then clicks run.

Examples:

client.import_gifts(
  transaction_source: 'Source', transactions: [
    {
      gift_type: 'Cash', amount: 10.5, currency_code: 'USD', gift_date: Date.today,
      contact: {
        contact_type: 'Organization', name: 'Org name', first_name: 'John',
        last_name: 'Doe', email: '[email protected]'
      }
    },
    {
      gift_type: 'Cash', amount: 5.0, currency_code: 'USD', gift_date: Date.today,
      contact: {
        contact_type: 'Organization', name: 'Org name', first_name: 'John',
        last_name: 'Doe', email: '[email protected]'
      }
    }
  ]
)

Options Hash (**shared_fields):

  • :transaction_source (String)
  • :create_import (Boolean)
  • :import_name (String)
  • :batch (String)
  • :batch_total (Float)
  • :default_gift_date (String)
  • :default_gift_type (String) 


384
385
386
387
388
389
390
391
 
# File 'lib/virtuous/client/gift.rb', line 384

def import_gifts(transactions:, **shared_fields)
  shared_fields = shared_fields.slice(
    :transaction_source, :create_import, :import_name, :batch, :batch_total,
    :default_gift_date, :default_gift_type
  )

  post('api/v2/Gift/Transactions', format(shared_fields.merge(transactions: transactions)))
end

#update_gift(id, data) ⇒ Hash

Note:

Excluding a property will remove it's value from the object.

Updates a gift.

If you're only updating a single property, the entire model is still required.

Examples:

client.update_gift(
  1, gift_type: 'Cash', amount: 5.0, currency_code: 'USD',
  gift_date: Date.today
)



212
213
214
 
# File 'lib/virtuous/client/gift.rb', line 212

def update_gift(id, data)
  parse(put("api/Gift/#{id}", format(data)))
end