---
title: "Create a Donation"
method: POST
path: "/v1/donations"
tags: ["donations"]
---

# Create a Donation

`POST /v1/donations`

## Request

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

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

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `source_id` string: The identifier of the [Source](/api-reference/sources) that sent this donation. The source must already exist.
  - `external_id` string: Identifier provided by the source or granting organization, when present.
  - `amount_gross` integer, 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_fee` integer: 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.
  - `currency` string: The [ISO 4217 code](https://en.wikipedia.org/wiki/ISO_4217) for every amount on the donation. Defaults to USD.
  - `exchange_rate` ExchangeRate: An exchange rate from a donation's currency to a target currency.
    - `target_currency` string, required: The [ISO 4217 code](https://en.wikipedia.org/wiki/ISO_4217) of the currency the rate converts into, usually USD.
    - `value` string, required: The number of units of `target_currency` equal to one unit of the donation's `currency`, as a decimal string.
  - `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_date` string, date-time: The date of the donation, as reported by the source. Defaults to the current date. Expressed in RFC 3339 format.
  - `grantor` GrantorInput: The entity responsible for issuing a grant or payment to a recipient.
    - `organization_name` string: The legal organization responsible for issuing the grant or payment.
    - `program_name` string: A specific program, initiative, or branded offering associated with the grantor organization through which the grant or payment is made.
  - `external_distribution_id` string: 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.
  - `recipient` RecipientInput: The nonprofit the donation was made out to, as named by the source.
    - `primary_name` string: The name of the nonprofit recipient, usually its legal name.
    - `secondary_name` string: Another name for the recipient, such as the name it does business as.
    - `address` string: The recipient's address, as a single line.
  - `purpose` string: A description of the donor's intent for the donation. For example, "Where needed most" or "General Operating Support" or "Specific Campaign".
  - `note` string: An informational note from the donor to the nonprofit about the donation.
  - `attribution` object: How the donation is attributed to a donor.
    - `primary_donor` DonorInput: The donor information for the donation. Provide either `full_name` or the `first_name`/`last_name` pair, depending on how the source reports the donor.
      - `full_name` string: The full name of the donor. Maximum length: 255 characters.
      - `first_name` string: The first name of the donor. Maximum length: 255 characters.
      - `last_name` string: The last name of the donor. Maximum length: 255 characters.
      - `email` string: The email address of the donor. Maximum length: 255 characters.
      - `phone` string: The phone number of the donor. Maximum length: 20 characters.
      - `address` AddressInput: A postal address to record on a donation. Every field is optional; supply as much as you know so downstream matching and receipting keep working when parts of the address are missing.
        - `line1` string: Street address.
        - `line2` string: Apartment, suite, or unit.
        - `city` string: City.
        - `state` string: State or province.
        - `postal_code` string: Postal or ZIP code.
        - `country` string: Country.
    - `joint_donor` JointDonorInput: The name of a second donor jointly credited with a gift. Provide either `full_name` or the `first_name`/`last_name` pair.
      - `full_name` string: The full name of the donor. Maximum length: 255 characters.
      - `first_name` string: The first name of the donor. Maximum length: 255 characters.
      - `last_name` string: The last name of the donor. Maximum length: 255 characters.
  - `initiation` DonationInitiationInput: Where and how the donor initiated the donation before it reached Chariot.
    - `initiated_at` string, date-time: Time when the donation was initiated. Expressed in RFC 3339 format.
    - `amount_initiated` integer: The amount the donor intended to give when they initiated the gift, in minor units of `currency`. This can differ from `amount_gross` if the gift changed before it settled.
    - `channel` 'INTEGRATED' | 'UNINTEGRATED' | 'UNKNOWN': The DAFpay integration channel used to initiate the donation. - `INTEGRATED` - The donation was initiated through an integrated DAFpay instance where the DAF sponsor processes the grant electronically via the DAFpay network. - `UNINTEGRATED` - The donation was initiated through an unintegrated DAFpay flow where the donor completes the grant manually on the DAF sponsor's website (e.g., Luminate Online, standalone embeds). - `UNKNOWN` - It wasn't specified how the donation was initiated.
    - `web_location_url` string: The URL of the web location where the donation was initiated.
    - `dafpay_tracking_id` string: The tracking ID for the donation as generated by DAFpay.
    - `form` string: The form where the donor initiated the donation.
    - `identifier` string: The initiating platform's own identifier for the donation. Use it to reconcile the donation against records in the platform's system.
    - `metadata` object: Additional key-value pairs the platform captured when the donation was initiated.
  - `donor_advised_fund_grant` DafGrantInput: Details specific to Donor Advised Fund donations.
    - `donor_fund_name` string: The name of the donor's fund at the Donor Advised Fund sponsor, such as the Doe Family Fund.
  - `corporate_match` CorporateMatchInput: Details specific to matched donations.
    - `match_amount` integer: The amount of the corporate match for the donation in minor units of the donation currency.
    - `company_name` string: The name of the company that matched the donation.
    - `source` string: The source of the corporate match.
  - `metadata` object: Arbitrary key-value pairs recorded against the donation. Use this for reconciliation data, campaign identifiers, or other integration data.
  - `artifact_file_ids` string[]: Files to attach to the donation, as File identifiers your organization owns.

## Response `201`

The donation was created.

- Donation: A Donation is a gift of money to a nonprofit organization.
  - `id` string, required: The unique identifier for the donation in Chariot's system.
  - `external_id` string: Identifier provided by the source or granting organization, when present.
  - `source_id` string: The identifier of the [Source](/api-reference/sources) that sent this donation.
  - `payment_source_id` string: Deprecated. Use `source_id`.
  - `amount_gross` integer, required: The total amount of the donation in minor units of the currency. For dollars, for example, this is cents.
  - `amount_net` integer, 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_fee` integer, 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_amount` integer, nullable: The portion of the gross amount contributed directly by the donor.
  - `currency` string, required: The [ISO 4217 code](https://en.wikipedia.org/wiki/ISO_4217) for every amount on the donation. Defaults to USD unless the source reports another currency.
  - `exchange_rate` ExchangeRate: An exchange rate from a donation's currency to a target currency.
    - `target_currency` string, required: The [ISO 4217 code](https://en.wikipedia.org/wiki/ISO_4217) of the currency the rate converts into, usually USD.
    - `value` string, required: The number of units of `target_currency` equal to one unit of the donation's `currency`, as a decimal string.
  - `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_date` string, date-time: The date of the donation, as reported by the source. Expressed in RFC 3339 format.
  - `grantor` Grantor: The entity responsible for issuing a grant or payment to a recipient.
    - `organization_name` string: The legal organization responsible for issuing the grant or payment.
    - `program_name` string: A specific program, initiative, or branded offering associated with the grantor organization through which the grant or payment is made.
  - `created_by` DonationCreator: Who created a donation.
    - `name` string: The name of the person, integration, or application that created the donation.
  - `external_distribution_id` string: 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.
  - `recipient` DonationRecipient: The nonprofit a donation was made out to.
    - `primary_name` string: The name of the nonprofit recipient, usually its legal name.
    - `secondary_name` string: Another name for the recipient, such as the name it does business as.
    - `address` string: The recipient's address, as a single line.
  - `purpose` string: 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".
  - `note` string: 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.
  - `attribution` DonationAttribution: How the donation is attributed to a donor.
    - `primary_donor` Donor: The donor information for the transaction
      - `full_name` string: The full name of the donor. Maximum length: 255 characters.
      - `first_name` string: The first name of the donor. Maximum length: 255 characters.
      - `last_name` string: The last name of the donor. Maximum length: 255 characters.
      - `email` string: The email address of the donor. Maximum length: 255 characters.
      - `phone` string: The phone number of the donor. Maximum length: 20 characters.
      - `address` Address
        - `city` string, required: City, district, suburb, town, or village. Maximum length: 255 characters.
        - `country` string, required: Two-letter country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
        - `line1` string, required: Address line 1 (e.g. street, PO Box, or company name). Maximum length: 255 characters.
        - `line2` string: Address line 2 (e.g. apartment, suite, unit, or building). Maximum length: 255 characters.
        - `postal_code` string, required: ZIP or postal code. Maximum length: 40 characters.
        - `state` string, required: State, county, province, or region
    - `joint_donor` JointDonor: The name of a second donor jointly credited with a gift.
      - `full_name` string: The full name of the donor. Maximum length: 255 characters.
      - `first_name` string: The first name of the donor. Maximum length: 255 characters.
      - `last_name` string: The last name of the donor. Maximum length: 255 characters.
  - `platform` object: Deprecated. Information about the platform that facilitated the donation. Empty when no platform facilitated the donation.
    - `name` string: The name of the platform.
    - `platform_grant_id` string: The identifier for the grant within the platform's system.
    - `metadata` object: Additional key value pairs that were passed to the platform during the donation initiation.
    - `acceptance` PlatformAcceptance: Information about the acceptance of the grant from the platform.
      - `accepted` boolean: Whether the grant was accepted from the platform.
      - `expires_at` string, date-time: The date and time when the acceptance of the grant will expire.
  - `initiation` DonationInitiation: A subhash describing where and how the donation was initiated by the donor before it reached Chariot.
    - `initiated_at` string, date-time: Time when the donation was initiated. Expressed in RFC 3339 format.
    - `amount_initiated` integer, nullable: The amount the donor intended to give when they initiated the gift, in minor units of `currency`. This can differ from `amount_gross` if the gift changed before it settled.
    - `channel` 'INTEGRATED' | 'UNINTEGRATED' | 'UNKNOWN': The DAFpay integration channel used to initiate the donation. - `INTEGRATED` - The donation was initiated through an integrated DAFpay instance where the DAF sponsor processes the grant electronically via the DAFpay network. - `UNINTEGRATED` - The donation was initiated through an unintegrated DAFpay flow where the donor completes the grant manually on the DAF sponsor's website (e.g., Luminate Online, standalone embeds). - `UNKNOWN` - It wasn't specified how the donation was initiated.
    - `web_location_url` string: The URL of the web location where the donation was initiated.
    - `dafpay_tracking_id` string: The tracking ID for the donation as generated by DAFpay.
    - `form` string: The form where the donor initiated the donation.
    - `identifier` string: The initiating platform's own identifier for the donation. Use it to reconcile the donation against records in the platform's system.
    - `metadata` object: Additional key-value pairs the platform captured when the donation was initiated.
    - `frequency` 'ONE_TIME' | 'MONTHLY': Deprecated. Use the donation's top-level `frequency`.
    - `fundraising_platform_name` string: Deprecated. Use `initiation.form`.
    - `dafpay_form` string: Deprecated. Use `initiation.form`.
    - `dafpay_metadata` object: Deprecated. Use `initiation.metadata`.
  - `settlement` DonationSettlement: How the funds moved from the donor to the recipient.
    - `type` 'chariot' | 'external', required: Where the funds settled. - `chariot` — the funds arrived through a Chariot deposit. `deposit_id` and `settled_at` apply. - `external` — the funds arrived outside Chariot's rails, straight to the recipient.
    - `received_at` string, date-time, required: When the funds were received by the recipient. Expressed in RFC 3339 format.
    - `settled_at` string, date-time: When the funds became available in the recipient's Chariot account. Only set when `type` is `chariot`. Expressed in RFC 3339 format.
    - `deposit_id` string: The identifier of the deposit that carried the funds. Only set when `type` is `chariot`.
  - `donor_advised_fund_grant` DafGrant: Grant details from a Donor-Advised Fund sponsor. The sponsor's name is on `grantor.organization_name`.
    - `donor_fund_name` string: The name of the donor's fund at the Donor Advised Fund sponsor, such as the Doe Family Fund.
    - `sponsor_grant_id` string: Deprecated. Use `initiation.identifier`.
    - `organization_name` string: Deprecated. Use `grantor.organization_name`.
    - `program_name` string: Deprecated. Use `grantor.program_name`.
  - `metadata` object: Arbitrary key-value pairs recorded against the donation. Use this for reconciliation data, campaign identifiers, or other integration data.
  - `corporate_match` CorporateMatch: Corporate match details for the donation.
    - `match_amount` integer: The amount of the corporate match for the donation in minor units of the donation currency.
    - `company_name` string: The name of the company that matched the donation.
    - `source` string: The source of the corporate match.
    - `program_name` string: Deprecated.
  - `properties` PropertyAssignment[]: A list of custom properties for the donation.
    - `property_id` string: The unique identifier for the property.
    - `value` PropertyValue
      - `type` 'text' | 'enum' | 'user' | 'boolean' | 'date', required: The data type of a property.
      - `text_value` string: The text value of the property.
      - `enum_value_id` string: The unique identifier for the enum value.
      - `user_value_id` string: The unique identifier for the user.
      - `boolean_value` boolean: The boolean value of the property.
      - `date_value` string, date-time: The date value of the property.
      - `empty` boolean: Whether the property value is empty. Can use this to unset property values when assigning a property.
  - `artifacts` Artifact[]: 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.
    - `id` string: Deprecated. The unique identifier for the artifact.
    - `name` string: The name of the artifact.
    - `file_id` string: The unique identifier for the file that the artifact is associated with.
    - `created_at` string, date-time: The date and time when the artifact was created.
  - `created_at` string, date-time, required: The date and time the donation record was created in Chariot.
  - `updated_at` string, date-time: The date and time when the donation was last updated.
  - `canceled_at` string, 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_at` string, 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_id` string, 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.

## Other responses

- `400`: The request is invalid or contains invalid parameters
- `401`: Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.
- `403`: Access denied
- `409`: Resource Conflicts
- `500`: Internal Server Error

## Changes

- **2026-11-02** (2026-10-01) `d2a4ff2fdda5`: 2 info
  - added the optional property `deleted_at` to the response with the `201` status
  - added the optional property `merged_into_donation_id` to the response with the `201` status
- **2026-10-19** (2026-10-01) `5004365b29b6`: 1 warning, 1 info
  - added the new `UNKNOWN` enum value to the `initiation/allOf[#/components/schemas/DonationInitiation]/channel` response property for the response status `201`
  - added the new `UNKNOWN` enum value to the request property `initiation/allOf[#/components/schemas/DonationInitiationInput]/channel`
- **2026-10-14** (2026-10-01) `24c792014720`: 4 warning, 2 info
  - removed the request property `individual_gift_amount`
  - removed the optional property `linked_objects` from the response with the `201` status
  - added the new `unknown` enum value to the `donation_type` response property for the response status `201`
  - added the new `unknown` enum value to the `frequency` response property for the response status `201`
  - …2 more

[Operation history](https://skmtc.dev/chariot-giving/apis/chariot-api-5/changes/v1/donations/post.md)

---

[API](https://skmtc.dev/chariot-giving/apis/chariot-api-5.md) - [All operations](https://skmtc.dev/chariot-giving/apis/chariot-api-5/llms.txt) - [OpenAPI document](https://skmtc.dev/chariot-giving/apis/chariot-api-5/revisions/d2a4ff2fdda5?raw)