latestOpenAPI 3.0.02026-08-1535120202.6 KB

f59881dadecd

Donations

Update a donation and its associated recurring plan

This request allows you to update the details of a donation that was made through an API call.

You can make updates to:

Enrich data.
Modify parameter values.
Remove parameter values.

<p class="callout callout--warning">This action is only available within 24 hours of the donation being created.<br/><br/>Donations created outside of the API, such as through the Checkout modal, Campaign Page, or Virtual Terminal, cannot be edited through the API.</p>

The donation ID must belong to the account associated with the API key.

Donations from subaccounts cannot be updated using the API key of the parent account. Attempting to do so will result in an error. To update a donation in a subaccount, you must use the API key of that subaccount.

For the update to be successful, the donation object must match the current campaign settings, otherwise the operation will fail with a validation error.

Parallel requests to update one object are not allowed and will result in an error.

Any parameters or child parameters that are not provided will remain unchanged.

A successful update will modify the donation receipt, but no emails will be sent as a result.

If you update recurring plan, the changes will apply to both the specific installment and all future installments.

post/v1/donations/{id}

Path parameters

idstring required

Example:DXXXXXXX

Unique identifier of the donation, formatted as D[A-Z]{7}.

Request body

campaignstring

Campaign ID. Must belong to the account that owns the API key, otherwise an error will occur. Must be active and accept money-based donations, otherwise an error will occur.

commentstring nullable

Updated comment, maximum 256 characters.

designationstring

The ID of the fund, program, or initiative the donation goes to. You can use the ID of any designation created in your account, whether or not it is linked to a campaign. Only one designation can be set for a single donation. To create multiple donations with different designations, make separate API calls. You can find the ID in the Designations section of the Dashboard.

livemodeboolean

Specifies whether the request is executed in live or test mode. Required for API keys created after 30th January 2026.

Example request

{
  "campaign": "FUNXXXXXXXX",
  "custom_fields": [
    {
      "name": "Field1",
      "value": "Value1"
    }
  ],
  "designation": "EXXXXXXX",
  "livemode": true,
  "questions": [
    {
      "id": "QXXXXXXX",
      "checked": true,
      "date": "1990-05-15",
      "options": [
        "Option 1",
        "Option 2"
      ],
      "text": "Example answer"
    }
  ],
  "supporter": {
    "address": {
      "city": "Nashville",
      "country": "us",
      "line1": "123 Main St",
      "line2": "Apt 1",
      "postal_code": "111111",
      "region": "Tennessee"
    },
    "email": "example@example.com",
    "employer": {
      "name": "Fundraise Up Inc."
    },
    "employment_status": "employed",
    "first_name": "Alex",
    "last_name": "Garcia",
    "occupation": "Software Engineer",
    "phone": "+1 (111) 111111",
    "title": "mr"
  }
}

Response

On success, the API returns the donation object. If the parameters are invalid, the call will return an error.

amountstring required

Donation amount in the transaction currency.

amount_before_fees_coveredstring required

Amount before fees were covered by supporter.

amount_before_fees_covered_in_default_currencystring required

Donation amount before any fees were covered by the supporter. Displayed in the organization's default currency at the time of donation.

amount_in_default_currencystring required

Donation amount converted to the organization's default currency.

anonymousboolean required

Indicates if the donation was made anonymously (true) or not (false).

commentstring nullable required

Optional comment provided by the supporter at the time of donation.

created_atstring required

Timestamp in ISO 8601 format, indicating when the donation was created in UTC.

currency'shp' | 'eur' | 'aed' | 'afn' | 'xcd' | 'all' | 'amd' | 'aoa' | 'ars' | 'usd' | 'aud' | 'ang' | 'xcg' | 'awg' | 'azn' | 'bam' | 'bbd' | 'inr' | 'pkr' | 'bdt' | 'xof' | 'bgn' | 'bhd' | 'bif' | 'bmd' | 'myr' | 'bnd' | 'bob' | 'brl' | 'bsd' | 'btn' | 'nok' | 'zar' | 'bwp' | 'byn' | 'bzd' | 'cad' | 'cdf' | 'xaf' | 'chf' | 'nzd' | 'clp' | 'cny' | 'cop' | 'crc' | 'cve' | 'czk' | 'djf' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'mad' | 'etb' | 'fjd' | 'fkp' | 'jpy' | 'gbp' | 'gel' | 'ghs' | 'gip' | 'gmd' | 'gnf' | 'gtq' | 'gyd' | 'hkd' | 'hnl' | 'hrk' | 'htg' | 'huf' | 'idr' | 'ils' | 'isk' | 'jmd' | 'jod' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'krw' | 'kwd' | 'kyd' | 'kzt' | 'lak' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mro' | 'mur' | 'mvr' | 'mwk' | 'mxn' | 'mzn' | 'nad' | 'xpf' | 'ngn' | 'nio' | 'sek' | 'npr' | 'omr' | 'pab' | 'pen' | 'pgk' | 'php' | 'pln' | 'pyg' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sgd' | 'sll' | 'sle' | 'sos' | 'srd' | 'std' | 'svc' | 'szl' | 'thb' | 'tjs' | 'tnd' | 'top' | 'try' | 'ttd' | 'twd' | 'tzs' | 'uah' | 'uyu' | 'uzs' | 'vnd' | 'vuv' | 'wst' | 'yer' | 'zmw' | 'btc' | 'eth' | 'usdt' | 'usdc' | 'sol' | 'dot' | 'doge' | 'shib' | 'ltc' | 'bch' | 'xtz' | 'fil' | 'ftm' | 'gala' | 'paxg' | 'zec' required

Three-letter ISO currency code, in lowercase.

failed_atstring nullable required

Timestamp in ISO 8601 format, indicating when the donation failed in UTC.

idstring required

Unique identifier for the donation.

installmentstring nullable required

Indicates the installment number for recurring donations. Returns null for one-time donations.

livemodeboolean required

Test mode indicator. true for live mode donations, false for test mode donations.

on_behalf_ofstring nullable required

Name of the organization the donation was made on behalf of.

receipt_idstring nullable required

Unique identifier for the donation receipt.

refunded_atstring nullable required

Timestamp in ISO 8601 format, indicating when the donation was refunded in UTC.

Indicates the source of the donation.

source_of_funds'own_money' | 'on_behalf_of' | 'fundraising_or_collection' nullable required

Indicates the source of funds for the donation in the context of Gift Aid eligibility.

Current status of the donation.

succeeded_atstring nullable required

Timestamp in ISO 8601 format, indicating when the donation succeeded in UTC.

supporter_covered_feestring required

Amount of fees covered by the supporter.

supporter_covered_fee_in_default_currencystring required

Amount of fees covered by the supporter and converted to the organization's default currency.

urlstring nullable required

URL from which the donation was made.

one_time_to_recurring_upgrade_linkstring nullable

A permanent, pre-authenticated link that the supporter can use to upgrade this donation to a recurring plan. Returned only when the request includes include=upgrade_link and the donation is eligible.

Example response

{
  "account": {
    "code": "Code-1",
    "id": "AXXXXXXX",
    "name": "Example Account"
  },
  "amount": "99.99",
  "amount_before_fees_covered": "99.99",
  "amount_before_fees_covered_in_default_currency": "59.99",
  "amount_in_default_currency": "59.99",
  "benefit": {
    "code": "TSHIRT-001",
    "fair_market_value": "25.99",
    "fair_market_value_currency": "usd",
    "id": "GXXXXXXX",
    "name": "T-shirt",
    "option": {
      "code": "SIZE-M",
      "name": "Size",
      "value": "M"
    },
    "shipping": {
      "address": {
        "city": "Nashville",
        "country": "us",
        "line1": "123 Example St.",
        "line2": "Apt. 1",
        "postal_code": "111111",
        "region": "Tennessee"
      },
      "recipient_first_name": "Alex",
      "recipient_last_name": "Garcia"
    }
  },
  "campaign": {
    "code": "Code-1",
    "id": "FUNXXXXXXXX",
    "name": "My Campaign"
  },
  "comment": "Comment example.",
  "consent": {
    "customized": {
      "email": "opted_in",
      "phone_calls": "opted_out",
      "postal_mail": "opted_in",
      "sms": "opted_in",
      "social_media": "opted_out"
    },
    "general": "opted_in"
  },
  "created_at": "2024-12-20T00:00:00.000Z",
  "currency": "usd",
  "custom_fields": [
    {
      "name": "Field1",
      "value": "Value1"
    }
  ],
  "designation": {
    "code": "Code-1",
    "id": "EXXXXXXX",
    "name": "My Designation"
  },
  "device": {
    "browser": "Chrome",
    "ip": {
      "address": "111.111.111.111",
      "city": "Nashville",
      "country_name": "United States",
      "region": "Tennessee"
    },
    "os": "MacOS",
    "type": "desktop",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
  },
  "element": {
    "id": "XXXXXXXX",
    "name": "My Element",
    "type": "donationForm"
  },
  "failed_at": "2024-12-20T00:00:00.000Z",
  "fundraiser": {
    "id": "NXXXXXXX",
    "name": "Run for hope"
  },
  "gift_aid": {
    "claimed": true,
    "legal_text": "I am a UK taxpayer and want to claim Gift Aid."
  },
  "id": "DXXXXXXX",
  "installment": "3",
  "livemode": true,
  "on_behalf_of": "Example Inc.",
  "payment": {
    "bank_account": {
      "last4": "1234"
    },
    "credit_card": {
      "exp_month": "12",
      "exp_year": "2023",
      "last4": "1234",
      "type": "Visa"
    },
    "daf_external_id": "010c5aa7-28f5-426f-b31f-9ba77754055f",
    "daf_sponsor_fund": "Fidelity Charitable",
    "daf_tracking_id": "1e60800e-849b-43d1-870e-57afc8d75473",
    "email": "example@example.com",
    "error_message": "Something went wrong",
    "id": "ch_1I9nHHHUtU5Pnu8b93DuxyzE",
    "method": "paypal",
    "processor": "stripe"
  },
  "payout": {
    "amount": "99.99",
    "amount_in_default_currency": "59.99",
    "currency": "usd"
  },
  "platform_fee": {
    "amount": "99.99",
    "amount_in_default_currency": "59.99",
    "currency": "usd"
  },
  "processing_fee": {
    "amount": "99.99",
    "amount_in_default_currency": "59.99",
    "currency": "usd"
  },
  "questions": [
    {
      "code": "Code-1",
      "id": "QXXXXXXX",
      "checked": true,
      "options": [
        "OK",
        "Good"
      ],
      "text": "Example answer"
    }
  ],
  "recurring_plan": {
    "created_at": "2024-12-20T00:00:00.000Z",
    "ended_at": "2024-12-20T00:00:00.000Z",
    "frequency": "monthly",
    "id": "RXXXXXXX",
    "next_installment_at": "2024-12-20T00:00:00.000Z",
    "status": "active"
  },
  "refunded_at": "2024-12-20T00:00:00.000Z",
  "source": "website",
  "status": "succeeded",
  "succeeded_at": "2024-12-20T00:00:00.000Z",
  "supporter": {
    "address": {
      "city": "Nashville",
      "country": "us",
      "line1": "123 Example St.",
      "line2": "Apt. 1",
      "postal_code": "111111",
      "region": "Tennessee"
    },
    "email": "example@example.com",
    "employer": {
      "name": "Fundraise Up Inc."
    },
    "employment_status": "employed",
    "first_name": "Alex",
    "id": "SXXXXXXXX",
    "language": "en-CA",
    "last_name": "Garcia",
    "occupation": "Software Engineer",
    "phone": "+1 (111) 111111",
    "title": "mr"
  },
  "supporter_covered_fee": "99.9",
  "supporter_covered_fee_in_default_currency": "99.9",
  "tribute": {
    "honoree": "Zhang Wei",
    "id": "TXXXXXXX",
    "sharing": {
      "from": "Alex Garcia",
      "message": "In loving memory of Jordan",
      "recipient": {
        "address": {
          "city": "Nashville",
          "country": "us",
          "line1": "123 Example St.",
          "line2": "Apt. 1",
          "postal_code": "111111",
          "region": "Tennessee"
        },
        "email": "example@example.com",
        "first_name": "Sidney",
        "last_name": "Jones",
        "title": "mr"
      },
      "type": "email"
    },
    "type": "in_honor"
  },
  "url": "https://example.com/DXXXXXXX",
  "utm": {
    "campaign": "giving_tuesday",
    "content": "textlink",
    "medium": "email",
    "source": "google",
    "term": "how_to_support_penguins"
  }
}