Storing donations in Movement

Movement can store both one-off donations and recurring donations.

One-off Donation Fields

Parameter	Type	Required	Description
campaign_id	Integer	No	ID of the associated campaign
regular_donation_id	Integer	No	ID of the associated regular donation
amount	Float	Yes	Donation amount
currency	String	Yes	ISO 4217 currency code (e.g., USD, EUR, GBP)
donated_at	Timestamp	Yes	Timestamp of when the donation was made
refunded_at	Timestamp	No	Date when the donation was refunded
processor	String	No	Payment processor used
external_id	String	Yes	External identifier for the donation
statement_descriptor	String	No	Statement descriptor for the donation
status	String	Yes	Donation status. One of: pending, processed, refunded, error
payment_method	String	No	Payment method used
is_anonymous	Boolean	No	Whether the donation is anonymous
gift_aid_eligible	Boolean	No	Whether the donation is eligible for gift aid
dedication_type	String	No	Type of dedication
dedication_name	String	No	Name for the dedication
dedication_message	String	No	Message for the dedication
notes	String	No	Additional notes about the donation
metadata	Hash	No	Additional metadata for the donation
source	String	No	Source information. See below for more details

Recurring Donation Fields

Parameter	Type	Required	Description
campaign_id	Integer	No	ID of the associated campaign
amount	Float	Yes	Donation amount
currency	String	Yes	ISO 4217 currency code
frequency	String	Yes	Frequency of the recurring donation
start_date	Date	Yes	Start date of the recurring donation
end_date	Date	No	End date of the recurring donation
processor	String	No	Payment processor used
external_id	String	Yes	External identifier for the donation
status	String	Yes	Regular donation status. One of: pending, active, cancelled, error
payment_method	String	No	Payment method used
is_anonymous	Boolean	No	Whether the donation is anonymous
gift_aid_eligible	Boolean	No	Whether the donation is eligible for gift aid
notes	String	No	Additional notes about the donation
metadata	Hash	No	Additional metadata for the donation
source	String	No	Source information. See below for more details

How to create a donation

Below is an example of logging a donation against a Target:

curl https://subdomain.yourmovement.org/api/donations \
 -X POST \
 -H 'Authorization: Bearer API_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "donation": {
    "target_id": 1,
    "external_id": "DON-01",
    "currency": "GBP",
    "amount": 10,
    "donated_at": "2024-06-01 00:00:00",
    "status": "processed"
  }
}'

These are the mandatory fields all donations require. Status can be one of:

pending
processed
refunded
error

The external ID should refer to a reference you hold in your external system, as this is the identifier that's used to update or delete donations via other API endpoints.

If you have additional metadata, such as specific compliance information, or country-specific requirements, you can store these in the metadata field.

How to create a supporter record and a donation

If your integration does not store information about Targets in Movement, you can first use API endpoints to determine whether a supporter is new, or whether to upsert data on them, before storing a donation.

Example: Look up by email, upsert if not found, then log a donation

Search for the target by email/phone number/external ID

curl "https://subdomain.yourmovement.org/api/targets/search?field=email&[email protected]" \
 -H "Authorization: Bearer API_TOKEN"

You can lookup a Target by name, phone number, email, and external ID. Please see the Targets -> Search API documentation page for details.

If the target is not found, upsert a new target

curl https://subdomain.yourmovement.org/api/targets/upsert \
 -X POST \
 -H "Authorization: Bearer API_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
  "record": {
    "external_id": "SUP-01",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+441234567890"
  },
  "conflict_strategy": "reject"
}'

See all supported columns

Please see the Targets -> Upsert API documentation page for further information.

After confirming the target exists (either found or created), log the donation:

curl https://subdomain.yourmovement.org/api/donations \
 -X POST \
 -H "Authorization: Bearer API_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
  "donation": {
    "target_id": 1,  // Use the ID returned from step 1 or 2
    "external_id": "DON-01",
    "currency": "GBP",
    "amount": 10,
    "donated_at": "2024-06-01 00:00:00",
    "status": "processed",
    "source": "email_id:1"
  }
}'

This process ensures that you have a valid target record before associating a donation with it. If provided, the source.email_id field will link the donation to the specific email that prompted the donation. The source parameter containing email_id:ID links this donation to an email sent via Movement.

Source tracking

source can be any value, but if passed as email_id:ID it will link the donation to a sent email.