CHchariot-giving
donations

Update a Donation

Changed on

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.

patch/v1/donations/{id}

Request

  • Base URL
    https://sandboxapi.givechariot.com
  • URL
    https://sandboxapi.givechariot.com/v1/donations/{id}
  • Auth
    HTTP bearer

Path parameters

idstring required

The unique identifier for the donation

Request body

clear_fieldsstring[]

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.

source_idstring

The identifier of the Source that sent this donation. The source must already exist.

external_idstring

Identifier provided by the source or granting organization, when present.

amount_grossinteger

The total amount of the donation in minor units of the currency. Must be non-negative. For dollars, for example, this is cents.

amount_feeinteger

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.

individual_gift_amountinteger

The portion of the gross amount contributed directly by the donor.

currencystring

The ISO 4217 code for every amount on the donation. Can't be cleared.

donation_type'individual' | 'match' | 'daf' | 'other' | 'unknown'

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.
frequency'one_time' | 'recurring' | 'unknown'

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.
effective_datestring date-time

The date of the donation, as reported by the source. Expressed in RFC 3339 format.

external_distribution_idstring

The platform's identifier for the payout that carried this donation. Platforms such as Benevity batch many donations into one payout, so several donations can share the same value.

purposestring

A description of the donor's intent for the donation. For example, "Where needed most" or "General Operating Support" or "Specific Campaign".

notestring

An informational note from the donor to the nonprofit about the donation.

metadataobject

Arbitrary key-value pairs recorded against the donation. Setting this field replaces the stored map. Naming metadata in clear_fields removes it.

artifact_file_idsstring[]

Files to attach to the donation, as File identifiers your organization owns. Existing artifacts stay attached. Repeating an identifier has no effect.

Example request

{
  "purpose": "Capital Campaign",
  "amount_fee": 250,
  "attribution": {
    "primary_donor": {
      "email": "warrenBuffet@example.com"
    }
  },
  "clear_fields": [
    "note"
  ]
}

Response

The donation was updated

idstring required

The unique identifier for the donation in Chariot's system.

external_idstring

Identifier provided by the source or granting organization, when present.

source_idstring

The identifier of the Source that sent this donation.

payment_source_idstring

Deprecated. Use source_id.

amount_grossinteger required

The total amount of the donation in minor units of the currency. For dollars, for example, this is cents.

amount_netinteger required

The amount of the donation that the nonprofit will receive after processing fees are deducted in minor units of the currency. For dollars, for example, this is cents.

amount_feeinteger required

The amount of the fee that was deducted from the donation in minor units of the currency. For dollars, for example, this is cents.

individual_gift_amountinteger nullable

The portion of the gross amount contributed directly by the donor.

currencystring required

The ISO 4217 code for every amount on the donation. Defaults to USD unless the source reports another currency.

donation_type'individual' | 'match' | 'daf' | 'other' | 'unknown'

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.
frequency'one_time' | 'recurring' | 'unknown'

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.
effective_datestring date-time

The date of the donation, as reported by the source. Expressed in RFC 3339 format.

external_distribution_idstring

The platform's identifier for the payout that carried this donation. Platforms such as Benevity batch many donations into one payout, so several donations can share the same value.

purposestring

A description of the donor's intent for the donation. This is useful to understand how the donor intended the donation to be used. For example, "Where needed most" or "General Operating Support" or "Specific Campaign".

notestring

An informational note from the donor to the nonprofit about the donation. This may contain a message or other useful information that the donor wants to share with the nonprofit.

metadataobject

Arbitrary key-value pairs recorded against the donation. Use this for reconciliation data, campaign identifiers, or other integration data.

created_atstring date-time required

The date and time the donation record was created in Chariot.

updated_atstring date-time

The date and time when the donation was last updated.

canceled_atstring date-time nullable

When the donation was canceled. If set, the donor's payment did not complete and the recipient did not receive the gift. Expressed in RFC 3339 format.

deleted_atstring date-time nullable

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.

merged_into_donation_idstring nullable

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.

payment_status'INCOMING_TO_CHARIOT' | 'INCOMING_OUTSIDE_CHARIOT' | 'RECEIVED_IN_CHARIOT' | 'RECEIVED_OUTSIDE_CHARIOT' | 'CANCELED'

The payment status of the donation. Indicates the current state of the payment lifecycle.

Example response

{
  "id": "donation_01j8rs605a4gctmbm58d87mvsj",
  "external_id": "INV-12345",
  "source_id": "source_01m12tn300eh20gdqscje7s5jw",
  "payment_source_id": "payment_source_01m12tn300eh20gdqscje7s5jw",
  "amount_gross": 25000,
  "amount_net": 25000,
  "amount_fee": 0,
  "individual_gift_amount": 25000,
  "currency": "USD",
  "donation_type": "daf",
  "frequency": "one_time",
  "effective_date": "2026-09-24T00:00:00Z",
  "created_by": {
    "name": "Chariot Data Sync"
  },
  "purpose": "Where needed most",
  "note": "Please dedicate in memory of grandma",
  "attribution": {
    "primary_donor": {
      "full_name": "Jane Rivera",
      "first_name": "Jane",
      "last_name": "Rivera",
      "email": "jrivera@example.com",
      "phone": "415-555-1212",
      "address": {
        "line1": "123 Main St.",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      }
    }
  },
  "initiation": {
    "initiated_at": "2026-09-20T15:04:05Z",
    "amount_initiated": 25000,
    "channel": "INTEGRATED",
    "web_location_url": "https://givebutter.com/example-nonprofit",
    "dafpay_tracking_id": "L9E182VBGP",
    "identifier": "L9E182VBGP",
    "form": "Givebutter",
    "metadata": {
      "campaign_id": "spring-appeal"
    }
  },
  "settlement": {
    "type": "chariot",
    "received_at": "2026-09-25T14:00:00Z",
    "settled_at": "2026-09-25T18:00:00Z",
    "deposit_id": "deposit_01j8rs605a4gctmbm58d87mvsj"
  },
  "grantor": {
    "organization_name": "Fidelity Charitable"
  },
  "donor_advised_fund_grant": {
    "donor_fund_name": "The Rivera Family Fund"
  },
  "metadata": {
    "crm_id": "0035e00000ABCDE"
  },
  "properties": [
    {
      "property_id": "prop_01j8rs605a4gctmbm58d87mvsj",
      "value": {
        "type": "text",
        "text_value": "Fall Gala"
      }
    }
  ],
  "artifacts": [
    {
      "name": "grant_letter.pdf",
      "file_id": "file_01j8rs605a4gctmbm58d87mvsj",
      "created_at": "2026-09-25T14:00:00Z"
    }
  ],
  "created_at": "2026-09-25T14:00:00Z",
  "updated_at": "2026-09-25T18:00:00Z",
  "canceled_at": null,
  "deleted_at": null,
  "merged_into_donation_id": null,
  "payment_status": "RECEIVED_IN_CHARIOT"
}

Changes

  • 2026-10-01d2a4ff2fdda5Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 2026-10-015004365b29b6Revision changes
    • warning

      added the new UNKNOWN enum value to the ///// response property for the response status

    • info

      added the new UNKNOWN enum value to the request property /////