> This page is for version v2026-10-01. > For other versions, use one of these documentation indexes: > - v2026-04-01 (default): https://docs.givechariot.com/v2026-04-01/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.givechariot.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.givechariot.com/_mcp/server. # Create a Donation POST https://api.givechariot.com/v1/donations Content-Type: application/json Creates a new donation. Include `source_id` to attribute the donation to a specific source. Reference: https://docs.givechariot.com/v2026-10-01/api/donations/create-donation ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://api.givechariot.com` (Production, default) - `https://sandboxapi.givechariot.com` (Sandbox) ## Request ### Headers - `Idempotency-Key` (string, optional) — The idempotency key for the request. ### Body (application/json) This endpoint expects an object. - `amount_gross` (long, required) — The total amount of the donation in minor units of the currency. Must be non-negative. For dollars, for example, this is cents. - `source_id` (string, optional) — The identifier of the [Source](/api-reference/sources) that sent this donation. The source must already exist. - `external_id` (string, optional) — The identifier for the donation as reported by its source, such as the transaction ID. Use it to reconcile the donation in Chariot against the original source donation record. - `amount_fee` (long, optional) — 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_amount` (long, optional) — The portion of the gross amount contributed directly by the donor. - `currency` (string, optional) — The [ISO 4217 code](https://en.wikipedia.org/wiki/ISO_4217) for every amount on the donation. Defaults to USD. - `exchange_rate` (ExchangeRate, optional) — The exchange rate used to convert the donation into `target_currency`, when the source reported one. - `donation_type` (enum, optional) — 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. - Allowed values: `individual`, `match`, `daf`, `other` - `frequency` (enum, optional) — Whether the donor set the gift to repeat. - Allowed values: `one_time`, `recurring` - `effective_date` (datetime, optional) — The date of the donation, as reported by the source. Defaults to the current date. Expressed in RFC 3339 format. - `grantor` (GrantorInput, optional) — The entity responsible for issuing a grant or payment to a recipient. - `external_distribution_id` (string, optional) — 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, optional) — The nonprofit the donation was made out to, as named by the source. - `purpose` (string, optional) — A description of the donor's intent for the donation. For example, "Where needed most" or "General Operating Support" or "Specific Campaign". - `note` (string, optional) — An informational note from the donor to the nonprofit about the donation. - `attribution` (V1DonationsPostRequestBodyContentApplicationJsonSchemaAttribution, optional) — How the donation is attributed to a donor. - `initiation` (DonationInitiationInput, optional) — How and where the donor initiated the gift. - `donor_advised_fund_grant` (DafGrantInput, optional) — Details specific to Donor Advised Fund donations. Leave it out when the donation did not come from a DAF provider. - `corporate_match` (CorporateMatchInput, optional) — Details specific to matched donations. Leave it out when no corporate sponsor matched the donation. - `metadata` (map from string to any, optional) — Arbitrary key-value pairs recorded against the donation. Use this for reconciliation data, campaign identifiers, or other integration data. - `artifact_file_ids` (list of string, optional) — Files to attach to the donation, as File identifiers your organization owns. ## Response ### 201 The donation was created. - `id` (string, required) — The unique identifier for the donation in Chariot's system. - `amount_gross` (long, required) — The total amount of the donation in minor units of the currency. For dollars, for example, this is cents. - `amount_net` (long, 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` (long, 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. - `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. - `created_at` (datetime, required) — The date and time the donation record was created in Chariot. - `external_id` (string, optional) — The identifier for the donation as reported by its source, such as the transaction ID. Use it to reconcile the donation in Chariot against the original source donation record. - `source_id` (string, optional) — The identifier of the [Source](/api-reference/sources) that sent this donation. - `individual_gift_amount` (long, optional, nullable) — The portion of the gross amount contributed directly by the donor. - `exchange_rate` (ExchangeRate, optional, nullable) — 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. - `donation_type` (enum, optional, nullable) — 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. - Allowed values: `individual`, `match`, `daf`, `other` - `frequency` (enum, optional, nullable) — Whether the donor set the gift to repeat. Null when the source didn't report it. - Allowed values: `one_time`, `recurring` - `effective_date` (datetime, optional) — The date of the donation, as reported by the source. Expressed in RFC 3339 format. - `grantor` (Grantor, optional) — The entity responsible for issuing a grant or payment to a recipient. - `created_by` (DonationCreator, optional) — Who created the donation. - `external_distribution_id` (string, optional) — 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, optional) — The nonprofit the donation was made out to, as named by the source. - `purpose` (string, optional) — 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, optional) — 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, optional) — How the donation is attributed to a donor. - `initiation` (DonationInitiation, optional) — How and where the donor initiated the gift. - `settlement` (DonationSettlement, optional) — How the funds are moving from the donor to the recipient. - `donor_advised_fund_grant` (DafGrant, optional) — Details specific to Donor Advised Fund donations. Empty when the donation did not come from a DAF provider. - `metadata` (map from string to any, optional) — Arbitrary key-value pairs recorded against the donation. Use this for reconciliation data, campaign identifiers, or other integration data. - `corporate_match` (CorporateMatch, optional) — Details specific to matched donations. Empty when no corporate sponsor matched the donation. - `properties` (list of PropertyAssignment, optional) — A list of custom properties for the donation. - `artifacts` (list of Artifact, optional) — 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. - `linked_objects` (list of LinkedObject, optional) — Other objects connected to this donation, such as the [Grant](/api/grants) or [Mail Item](/api/mail-items) that produced it. Each entry names the object's type and identifier; fetch the object itself for its details. - `updated_at` (datetime, optional) — The date and time when the donation was last updated. - `canceled_at` (datetime, optional, 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. - `payment_status` (enum, optional) — The payment status of the donation. Indicates the current state of the payment lifecycle. - Allowed values: `INCOMING_TO_CHARIOT`, `INCOMING_OUTSIDE_CHARIOT`, `RECEIVED_IN_CHARIOT`, `RECEIVED_OUTSIDE_CHARIOT`, `CANCELED` - `payment_source_id` (string, optional, deprecated) — Deprecated. Use `source_id`. - `platform` (DonationPlatform, optional, deprecated) — Deprecated. Information about the platform that facilitated the donation. Empty when no platform facilitated the donation. ## Errors ### 400 Bad Request Error The request is invalid or contains invalid parameters - `type` (string, required) — A URI reference identifying the problem type. - `title` (string, required) — A short, human-readable summary of the problem type. - `status` (integer, required) — The HTTP status code for this error. - `detail` (string, required) — A human-readable explanation specific to this occurrence. ### 401 Unauthorized Error Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller. - `type` (string, required) — A URI reference identifying the problem type. - `title` (string, required) — A short, human-readable summary of the problem type. - `status` (integer, required) — The HTTP status code for this error. - `detail` (string, required) — A human-readable explanation specific to this occurrence. ### 403 Forbidden Error Access denied - `type` (string, required) — A URI reference identifying the problem type. - `title` (string, required) — A short, human-readable summary of the problem type. - `status` (integer, required) — The HTTP status code for this error. - `detail` (string, required) — A human-readable explanation specific to this occurrence. ### 409 Conflict Error Resource Conflicts - `type` (string, required) — A URI reference identifying the problem type. - `title` (string, required) — A short, human-readable summary of the problem type. - `status` (integer, required) — The HTTP status code for this error. - `detail` (string, required) — A human-readable explanation specific to this occurrence. ### 500 Internal Server Error Internal Server Error - `type` (string, required) — A URI reference identifying the problem type. - `title` (string, required) — A short, human-readable summary of the problem type. - `status` (integer, required) — The HTTP status code for this error. - `detail` (string, required) — A human-readable explanation specific to this occurrence. ## Types ### 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. ### GrantorInput The entity responsible for issuing a grant or payment to a recipient. - `organization_name` (string, optional) — The legal organization responsible for issuing the grant or payment. - `program_name` (string, optional) — A specific program, initiative, or branded offering associated with the grantor organization through which the grant or payment is made. ### RecipientInput The nonprofit the donation was made out to, as named by the source. - `primary_name` (string, optional) — The name of the nonprofit recipient, usually its legal name. - `secondary_name` (string, optional) — Another name for the recipient, such as the name it does business as. - `address` (string, optional) — The recipient's address, as a single line. ### V1DonationsPostRequestBodyContentApplicationJsonSchemaAttribution How the donation is attributed to a donor. - `primary_donor` (DonorInput, optional) — The primary donor. - `joint_donor` (JointDonorInput, optional) — A second donor jointly credited with the gift. ### DonationInitiationInput Where and how the donor initiated the donation before it reached Chariot. - `initiated_at` (datetime, optional) — Time when the donation was initiated. Expressed in RFC 3339 format. - `amount_initiated` (long, optional) — 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` (enum, optional) — 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). - Allowed values: `INTEGRATED`, `UNINTEGRATED` - `web_location_url` (string, optional) — The URL of the web location where the donation was initiated. - `dafpay_tracking_id` (string, optional) — The tracking ID for the donation as generated by DAFpay. - `form` (string, optional) — The form where the donor initiated the donation. - `identifier` (string, optional) — The initiating platform's own identifier for the donation. Use it to reconcile the donation against records in the platform's system. - `metadata` (map from string to string, optional) — Additional key-value pairs the platform captured when the donation was initiated. ### DafGrantInput Details specific to Donor Advised Fund donations. - `donor_fund_name` (string, optional) — The name of the donor's fund at the Donor Advised Fund sponsor, such as the Doe Family Fund. ### CorporateMatchInput Details specific to matched donations. - `match_amount` (long, optional) — The amount of the corporate match for the donation in minor units of the donation currency. - `company_name` (string, optional) — The name of the company that matched the donation. - `source` (string, optional) — The source of the corporate match. ### Grantor The entity responsible for issuing a grant or payment to a recipient. - `organization_name` (string, optional) — The legal organization responsible for issuing the grant or payment. - `program_name` (string, optional) — A specific program, initiative, or branded offering associated with the grantor organization through which the grant or payment is made. ### DonationCreator Who created a donation. - `name` (string, optional) — The name of the person, integration, or application that created the donation. ### DonationRecipient The nonprofit a donation was made out to. - `primary_name` (string, optional) — The name of the nonprofit recipient, usually its legal name. - `secondary_name` (string, optional) — Another name for the recipient, such as the name it does business as. - `address` (string, optional) — The recipient's address, as a single line. ### DonationAttribution How the donation is attributed to a donor. - `primary_donor` (Donor, optional) — The primary donor. - `joint_donor` (JointDonor, optional) — A second donor jointly credited with the gift. ### DonationInitiation A subhash describing where and how the donation was initiated by the donor before it reached Chariot. - `initiated_at` (datetime, optional) — Time when the donation was initiated. Expressed in RFC 3339 format. - `amount_initiated` (long, optional, 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` (enum, optional) — 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). - Allowed values: `INTEGRATED`, `UNINTEGRATED` - `web_location_url` (string, optional) — The URL of the web location where the donation was initiated. - `dafpay_tracking_id` (string, optional) — The tracking ID for the donation as generated by DAFpay. - `form` (string, optional) — The form where the donor initiated the donation. - `identifier` (string, optional) — The initiating platform's own identifier for the donation. Use it to reconcile the donation against records in the platform's system. - `metadata` (map from string to string, optional) — Additional key-value pairs the platform captured when the donation was initiated. - `frequency` (enum, optional, deprecated) — Deprecated. Use the donation's top-level `frequency`. - Allowed values: `ONE_TIME`, `MONTHLY` - `fundraising_platform_name` (string, optional, deprecated) — Deprecated. Use `initiation.form`. - `dafpay_form` (string, optional, deprecated) — Deprecated. Use `initiation.form`. - `dafpay_metadata` (map from string to string, optional, deprecated) — Deprecated. Use `initiation.metadata`. ### DonationSettlement How the funds moved from the donor to the recipient. - `type` (enum, 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. - Allowed values: `chariot`, `external` - `received_at` (datetime, required) — When the funds were received by the recipient. Expressed in RFC 3339 format. - `settled_at` (datetime, optional) — 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, optional) — The identifier of the deposit that carried the funds. Only set when `type` is `chariot`. ### DafGrant Grant details from a Donor-Advised Fund sponsor. The sponsor's name is on `grantor.organization_name`. - `donor_fund_name` (string, optional) — The name of the donor's fund at the Donor Advised Fund sponsor, such as the Doe Family Fund. - `sponsor_grant_id` (string, optional, deprecated) — Deprecated. Use `external_id`. - `organization_name` (string, optional, deprecated) — Deprecated. Use `grantor.organization_name`. - `program_name` (string, optional, deprecated) — Deprecated. Use `grantor.program_name`. ### CorporateMatch Corporate match details for the donation. - `match_amount` (long, optional) — The amount of the corporate match for the donation in minor units of the donation currency. - `company_name` (string, optional) — The name of the company that matched the donation. - `source` (string, optional) — The source of the corporate match. - `program_name` (string, optional, deprecated) — Deprecated. Use `grantor.program_name`. ### PropertyAssignment A property assignment is a key-value pair that is associated with a donation. - `property_id` (string, optional) — The unique identifier for the property. - `value` (PropertyValue, optional) ### Artifact An artifact is a source file that was used to create the donation. - `name` (string, optional) — The name of the artifact. - `file_id` (string, optional) — The unique identifier for the file that the artifact is associated with. - `created_at` (datetime, optional) — The date and time when the artifact was created. - `id` (string, optional, deprecated) — Deprecated. The unique identifier for the artifact. ### LinkedObject A reference to another object connected to a donation. - `type` (string, required) — The kind of object. It matches the object's name in the API, such as `grant` or `mail_item`. - `id` (string, required) — The identifier of the linked object. ### DonationPlatform Deprecated. Information about the platform that facilitated the donation. Empty when no platform facilitated the donation. - `name` (string, optional) — The name of the platform. - `platform_grant_id` (string, optional) — The identifier for the grant within the platform's system. - `metadata` (map from string to string, optional) — Additional key value pairs that were passed to the platform during the donation initiation. - `acceptance` (PlatformAcceptance, optional) — Information about the acceptance of the grant from the platform. This is only present if the platform requires grant acceptance before disbursing funds. ### 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, optional) — The full name of the donor. Maximum length: 255 characters. - `first_name` (string, optional) — The first name of the donor. Maximum length: 255 characters. - `last_name` (string, optional) — The last name of the donor. Maximum length: 255 characters. - `email` (string, optional) — The email address of the donor. Maximum length: 255 characters. - `phone` (string, optional) — The phone number of the donor. Maximum length: 20 characters. - `address` (AddressInput, optional) — 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. ### 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, optional) — The full name of the donor. Maximum length: 255 characters. - `first_name` (string, optional) — The first name of the donor. Maximum length: 255 characters. - `last_name` (string, optional) — The last name of the donor. Maximum length: 255 characters. ### Donor The donor information for the transaction - `full_name` (string, optional) — The full name of the donor. Maximum length: 255 characters. - `first_name` (string, optional) — The first name of the donor. Maximum length: 255 characters. - `last_name` (string, optional) — The last name of the donor. Maximum length: 255 characters. - `email` (string, optional) — The email address of the donor. Maximum length: 255 characters. - `phone` (string, optional) — The phone number of the donor. Maximum length: 20 characters. - `address` (Address, optional) ### JointDonor The name of a second donor jointly credited with a gift. - `full_name` (string, optional) — The full name of the donor. Maximum length: 255 characters. - `first_name` (string, optional) — The first name of the donor. Maximum length: 255 characters. - `last_name` (string, optional) — The last name of the donor. Maximum length: 255 characters. ### PropertyValue - `type` (enum, required) — The data type of a property. - Allowed values: `text`, `enum`, `user`, `boolean`, `date` - `text_value` (string, optional) — The text value of the property. - `enum_value_id` (string, optional) — The unique identifier for the enum value. - `user_value_id` (string, optional) — The unique identifier for the user. - `boolean_value` (boolean, optional) — The boolean value of the property. - `date_value` (datetime, optional) — The date value of the property. - `empty` (boolean, optional) — Whether the property value is empty. Can use this to unset property values when assigning a property. ### PlatformAcceptance Information about the acceptance of the grant from the platform. - `accepted` (boolean, optional) — Whether the grant was accepted from the platform. - `expires_at` (datetime, optional) — The date and time when the acceptance of the grant will expire. ### 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, optional) — Street address. - `line2` (string, optional) — Apartment, suite, or unit. - `city` (string, optional) — City. - `state` (string, optional) — State or province. - `postal_code` (string, optional) — Postal or ZIP code. - `country` (string, optional) — Country. ### 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. - `postal_code` (string, required) — ZIP or postal code. Maximum length: 40 characters. - `state` (string, required) — State, county, province, or region - `line2` (string, optional) — Address line 2 (e.g. apartment, suite, unit, or building). Maximum length: 255 characters. ## Examples **Request** ```json { "amount_gross": 10000, "source_id": "source_01m12tn300eh20gdqscje7s5jw", "external_id": "PAYROLL-2026-01-EMP-1234", "currency": "USD", "effective_date": "2026-01-15T00:00:00Z", "purpose": "General Operating Support", "attribution": { "primary_donor": { "first_name": "Jane", "last_name": "Rivera", "email": "jrivera@example.com" } } } ``` **Response** ```json { "id": "donation_01j8rs605a4gctmbm58d87mvsj", "amount_gross": 25000, "amount_net": 25000, "amount_fee": 0, "currency": "USD", "created_at": "2026-09-25T14:00:00Z", "external_id": "INV-12345", "source_id": "source_01m12tn300eh20gdqscje7s5jw", "individual_gift_amount": 25000, "donation_type": "daf", "frequency": "one_time", "effective_date": "2026-09-24T00:00:00Z", "grantor": { "organization_name": "Fidelity Charitable" }, "created_by": { "name": "Fidelity Charitable" }, "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": { "city": "New York", "country": "US", "line1": "123 Main St.", "postal_code": "10001", "state": "NY" } } }, "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", "form": "Givebutter", "identifier": "L9E182VBGP", "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" }, "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" } ], "linked_objects": [ { "type": "mail_item", "id": "mail_item_01j8rs605a4gctmbm58d87mvsj" } ], "updated_at": "2026-09-25T18:00:00Z", "canceled_at": null, "payment_status": "RECEIVED_IN_CHARIOT", "payment_source_id": "payment_source_01m12tn300eh20gdqscje7s5jw" } ```