CHchariot-giving
donations

Create a Donation

Changed on

Creates a new donation. Include source_id to attribute the donation to a specific source.

post/v1/donations

Request

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

Headers

Idempotency-Keystring

The idempotency key for the request.

Request body

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 required

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.

currencystring

The ISO 4217 code for every amount on the donation. Defaults to USD.

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. Defaults to the current date. 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. Use this for reconciliation data, campaign identifiers, or other integration data.

artifact_file_idsstring[]

Files to attach to the donation, as File identifiers your organization owns.

Example request

{
  "source_id": "source_01m12tn300eh20gdqscje7s5jw",
  "effective_date": "2026-01-15T00:00:00Z",
  "amount_gross": 10000,
  "currency": "USD",
  "purpose": "General Operating Support",
  "external_id": "PAYROLL-2026-01-EMP-1234",
  "attribution": {
    "primary_donor": {
      "first_name": "Jane",
      "last_name": "Rivera",
      "email": "jrivera@example.com"
    }
  }
}

Response

The donation was created.

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 /////