---
title: "Create a donation"
method: POST
path: "/api/v2/donations"
tags: ["Donations"]
---

# Create a donation

`POST /api/v2/donations`

## Request

- Base URL: `https://yournation.nationbuilder.com`
- URL: `https://yournation.nationbuilder.com/api/v2/donations`
- Auth: HTTP bearer

Creates a donation from given data

## Request body

- DonationCreateRequest: The JSON:API top-level document shape for create requests, whose data member carries the new resource's type and attributes.
  - `data` object, required
    - `type` 'donations', required: The JSON:API resource type of the resource being created.
    - `attributes` object: The write-only attributes of a donation.
      - `actblue_order_number` string, nullable: The ActBlue order.
      - `amount_in_cents` integer, nullable: The order amount in cents.
      - `canceled_at` string, date-time, nullable: When the order was canceled.
      - `check_number` string, nullable: Check number.
      - `custom_values` object, nullable: Values for nation-defined fields on donation
      - `donation_tracking_code_id` string, nullable: The associated donation tracking code.
      - `email` string, nullable: Donor's email.
      - `employer` string, nullable: Donor's employer.
      - `external_id` string, nullable: A unique identifier from a third party. Must be unique across donations.
      - `failed_at` string, date-time, nullable: When the donation failed.
      - `first_name` string, nullable: Donor's first name.
      - `is_corporate_contribution` boolean, nullable: Marks the donation as a corporate donation.
      - `is_private` boolean, nullable: Marks the donation as private.
      - `last_name` string, nullable: Donor's last name.
      - `mailing_id` string, nullable: The mailing associated with this donation.
      - `membership_id` string, nullable: The membership given from this donation. Set it to associate a membership, or to null to disassociate it. This works on any donation, including one backed by a merchant account.
      - `middle_name` string, nullable: Donor's middle name.
      - `note` string, nullable: Short description.
      - `occupation` string, nullable: Donor's occupation.
      - `page_id` string, nullable: The page associated with this donation.
      - `payment_type_id` string, nullable: The payment type used.
      - `payment_type_name` string, nullable: The name of the payment type
      - `pending_at` string, date-time, nullable: When the donation was marked as pending.
      - `pledge_id` string, nullable: The associated pledge.
      - `recurring_donation_id` string, nullable: The recurring donation this donation belongs to, if any. Set it to associate the donation, or to null to disassociate it. Both are allowed only for unmanaged recurring donations, which have no merchant account. The recurring donation must belong to the same signup as the donation, so signup_id is required when this is set on create.
      - `signup_id` string, nullable: The signup that donated.
      - `succeeded_at` string, date-time, nullable: When the donation succeeded.
      - `billing_address_attributes` object, nullable: Attribute used to write data to the given donation's Billing address. When an address already exists, provided values will be used to patch the existing address data, only overwriting values provided in the payload. When no address exists, the existing data will be used to persist a new address.
      - `send_admin_notifications` boolean, nullable: Whether admins who receive donation notifications are notified. Has no effect when the nation has email notifications turned off, or when no admin is subscribed to them.
      - `send_donor_receipt` boolean, nullable
      - `work_address_attributes` object, nullable: Attribute used to write data to the given donation's Work address. When an address already exists, provided values will be used to patch the existing address data, only overwriting values provided in the payload. When no address exists, the existing data will be used to persist a new address.

## Response `201`

The newly created donation.

- DonationShowResponse: The JSON:API top-level document shape for responses returning a single resource under the data member.
  - `data` object, required: A JSON:API resource identifier object, the type/id pair that uniquely identifies a single resource.
    - `id` string, required: Unique identifier of the resource.
    - `type` 'donations', required: The JSON:API resource type.
    - `attributes` object: The read-only attributes of a donation.
      - `actblue_order_number` string, nullable: The ActBlue order.
      - `amount_in_cents` integer, nullable: The order amount in cents.
      - `canceled_at` string, date-time, nullable: When the order was canceled.
      - `check_number` string, nullable: Check number.
      - `custom_values` object, nullable: Values for nation-defined fields on donation
      - `donation_tracking_code_id` string, nullable: The associated donation tracking code.
      - `email` string, nullable: Donor's email.
      - `employer` string, nullable: Donor's employer.
      - `external_id` string, nullable: A unique identifier from a third party. Must be unique across donations.
      - `failed_at` string, date-time, nullable: When the donation failed.
      - `first_name` string, nullable: Donor's first name.
      - `is_corporate_contribution` boolean, nullable: Marks the donation as a corporate donation.
      - `is_private` boolean, nullable: Marks the donation as private.
      - `last_name` string, nullable: Donor's last name.
      - `mailing_id` string, nullable: The mailing associated with this donation.
      - `membership_id` string, nullable: The membership given from this donation. Set it to associate a membership, or to null to disassociate it. This works on any donation, including one backed by a merchant account.
      - `middle_name` string, nullable: Donor's middle name.
      - `note` string, nullable: Short description.
      - `occupation` string, nullable: Donor's occupation.
      - `page_id` string, nullable: The page associated with this donation.
      - `payment_type_id` string, nullable: The payment type used.
      - `payment_type_name` string, nullable: The name of the payment type
      - `pending_at` string, date-time, nullable: When the donation was marked as pending.
      - `pledge_id` string, nullable: The associated pledge.
      - `recurring_donation_id` string, nullable: The recurring donation this donation belongs to, if any. Set it to associate the donation, or to null to disassociate it. Both are allowed only for unmanaged recurring donations, which have no merchant account. The recurring donation must belong to the same signup as the donation, so signup_id is required when this is set on create.
      - `signup_id` string, nullable: The signup that donated.
      - `succeeded_at` string, date-time, nullable: When the donation succeeded.
      - `amount` string, nullable: The order amount.
      - `created_at` string, date-time, nullable
      - `import_id` string, nullable: The import that created this donation.
      - `payout_id` string, nullable: The ID of the payout in which this NationBuilder Payments donation was included
      - `status` 'succeeded' | 'pending' | 'failed' | 'canceled' | 'null', nullable: The status of the donation.
      - `updated_at` string, date-time, nullable
  - `included` Resource[]: Sideloaded resources requested via the include query parameter. Each entry is a full resource object whose shape is documented under its own resource type.
    - `id` string, required: Unique identifier of the resource.
    - `type` string, required: The JSON:API resource type.
    - `attributes` object: The attributes of the resource, as documented for its resource type.
    - `relationships` object: References from this resource to other resources in the document.
  - `meta` object: Non-standard information about the document. Empty unless the endpoint has metadata to convey.

## Other responses

- `400`: The request body or query parameters are invalid, such as an unknown attribute, filter, filter operator, sort field, or sideload.
- `401`: The access token is missing, expired, or not authorized to access this resource.
- `422`: Model validations failed for the resource being created or updated. Unlike this API's other errors, validation failures are returned as a JSON:API errors document locating each invalid field.
- `429`: The access token has exceeded its request quota for the current rate-limit window.

## Changes

- **2026-11-05** `d5c88ca497ac`: 4 breaking, 1 warning, 8 info
  - added `#/components/schemas/create_request_document, subschema #2` to the request body `allOf` list
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `201`
  - removed the required property `data` from the response with the `201` status
  - …9 more
- **2026-02-14** `31995b0a1e61`: 1 warning, 5 info
  - removed the optional property `data/attributes/allOf[#/components/schemas/donation_read_only_attributes]/succeeded_at` from the response with the `201` status
  - added the new optional request property `data/attributes/allOf[#/components/schemas/donation_read_write_attributes]/pending_at`
  - added the new optional request property `data/attributes/allOf[#/components/schemas/donation_read_write_attributes]/succeeded_at`
  - added the optional property `data/attributes/allOf[#/components/schemas/donation_read_only_attributes]/status` to the response with the `201` status
  - …2 more

[Operation history](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/changes/api/v2/donations/post.md)

---

[API](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api.md) - [All operations](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/revisions/d5c88ca497ac?raw)