Update a Donation
Update fields on an existing donation. Fields set in the request body are written (including empty
strings and zeros). Fields listed in clear_fields are nulled — only nullable columns are clearable.
Fields that are neither set nor listed are left unchanged. A field path may not be cleared and carry
a value in the same request.
An update to a deleted or merged donation returns 409. The problem
type is donation_deleted or donation_merged. A merged donation
carries the ID of the donation it was merged into.
Changing or clearing the source_id of a donation that is reconciled to a deposit returns 400.
To move the donation, unreconcile it from the deposit first.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Headers
Request
The request to update fields on an existing donation.
- Fields set in the body are written, including empty strings and zeros.
- Objects such as
recipientorattribution.primary_donorupdate key by key. Only the fields you set inside the object change. metadatareplaces the stored map as a whole.- Fields listed in
clear_fieldsare nulled. Only nullable columns may be cleared; a path that resolves to a NOT NULL column is rejected. - Fields that are neither set nor listed are left unchanged.
A field path may not be cleared and carry a value in the same request.
Field paths to null (dot notation, e.g. note, attribution.primary_donor.email).
Unknown paths are rejected. So are amount_gross, amount_fee, currency,
and effective_date, which have no empty representation.
The identifier of the Source that sent this donation. The source must already exist. It can’t be changed or cleared while the donation is reconciled to a deposit.
The total amount of the donation in minor units of the currency. Must be non-negative. For dollars, for example, this is cents.
The amount of the fee that was deducted from the donation in minor units of the currency.
amount_net is always amount_gross minus amount_fee, so you can’t set it.
The ISO 4217 code for every amount on the donation. Can’t be cleared.
The exchange rate used to convert the donation into target_currency, when the
source reported one. Send both target_currency and value: the rate replaces the
stored one as a whole. To remove it, name exchange_rate in clear_fields.
The kind of gift.
individual: a gift from an individual donor.match: a company’s match of an employee’s gift.daf: a grant from a donor-advised fund.other: any other kind of gift.unknown: the kind of gift wasn’t specified.
Whether the donor set the gift to repeat.
one_time: the donor gave once.recurring: the donor set the gift to repeat.unknown: it wasn’t specified whether the gift repeats.
Arbitrary key-value pairs recorded against the donation. The keys you send are added to
the stored map. A key that already exists gets the new value. Stored keys you don’t send
don’t change. To remove all metadata, name metadata in clear_fields.
Only valid with a payment_status of RECEIVED_OUTSIDE_CHARIOT.
Response
The ISO 4217 code for every amount on the donation. Defaults to USD unless the source reports another currency.
The identifier of the Source that sent this donation.
The exchange rate used to convert the donation into target_currency.
Null when currency is already the target currency, or when no rate was reported.
The kind of gift.
individual: a gift from an individual donor.match: a company’s match of an employee’s gift.daf: a grant from a donor-advised fund.other: any other kind of gift.unknown: the source did not report the kind of gift.
Whether the donor set the gift to repeat.
one_time: the donor gave once.recurring: the donor set the gift to repeat.unknown: the source did not report whether the gift repeats.
Arbitrary key-value pairs recorded against the donation. Use this for reconciliation data, campaign identifiers, or other integration data.
A list of source artifacts that were used to create the donation. These can include the raw source files (PDFs, CSVs, etc.) that were received from upstream platforms or systems.
When the donation was deleted or merged. Null for a live donation.
GET /v1/donations/{id} still returns a deleted or merged donation,
but GET /v1/donations (list) excludes it. Expressed in RFC 3339
format.
The donation this one was merged into. Set only for a merged donation, as a donation ID. Null for a live or plain-deleted donation. Follow it to the donation that now holds the gift.
Deprecated. Use source_id.

