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

# Create a recurring donation

`POST /api/v2/recurring_donations`

## Request

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

Records an unmanaged recurring donation: an external processor bills the donor and
NationBuilder only records the series.

`signup_id`, `amount_in_cents`, `frequency` and `start_date` are required. `payment_type` is
always `donation`. `merchant_account_id` is read-only, so every recurring donation created
here is unmanaged.

**Membership** — to record which membership the series pays for, send the membership as a
relationship. See `recurring_donation_membership_relationship`.

## Request body

- RecurringDonationCreateRequest: 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` 'recurring_donations', required: The JSON:API resource type of the resource being created.
    - `attributes` object, required: The attributes of a recurring_donation that can be both read and written.
      - `amount_in_cents` integer, nullable, required: The amount billed each period, in cents. Must be above zero.
      - `description` string, nullable: A free-text description.
      - `donation_tracking_code_id` string, nullable: The tracking code attached to the recurring donation.
      - `external_id` string, nullable: The identifier of the recurring donation in the external billing system.
      - `frequency` 'monthly' | 'annual' | 'null', nullable, required: How often the recurring donation is billed. Set on create only.
      - `page_id` string, nullable: The page the recurring donation was created on.
      - `private` boolean, nullable: Whether the recurring donation is hidden from public displays.
      - `recruiter_id` string, nullable: The signup credited with recruiting the donor.
      - `signup_id` string, nullable, required: The signup the recurring donation belongs to. Set on create only.
      - `start_date` string, date-time, nullable, required: When the recurring donation started.
      - `status` 'active' | 'completed' | 'failed', nullable: `canceled` cannot be set here; use `PATCH /api/v2/recurring_donations/{id}/cancel`.
    - `relationships` RecurringDonationMembershipRelationship: Associates an existing membership with the recurring donation. Only the link is written: the membership, other recurring donations and donations are not changed. Create or update the membership with `/api/v2/memberships`. Send the membership `id` and no `included` entry; `method` is optional and, when sent, must be `update`. Membership attributes, `method: create`, `method: destroy` and `method: disassociate` return 400. A membership you cannot see returns 404. Returns 422, and writes nothing, when the membership belongs to another signup, when the recurring donation already has a different membership, when another active, failing or pending recurring donation pays for the membership, or when a donation on the recurring donation belongs to another membership.
      - `membership` object
        - `data` object, required: Identifies a related resource written in the same request (a sidepost), an extension to JSON:API. For method create, the temp-id links this relationship entry to the matching object in the request's top-level included array; the other methods identify an existing related resource by id. Omitting method associates an existing resource without modifying it.
          - `type` 'memberships', required: The JSON:API type of the related resource.
          - `id` string, required: The ID of an existing related resource; used with every method except create.
          - `temp-id` string: Client-generated temporary ID tying this relationship to an entry in the included array when creating the related resource.
          - `method` 'update': The sidepost operation to perform on the related resource.

## Response `201`

The newly created recurring donation.

- RecurringDonationShowResponse: 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` 'recurring_donations', required: The JSON:API resource type.
    - `attributes` object: The read-only attributes of a recurring_donation.
      - `amount_in_cents` integer, nullable: The amount billed each period, in cents. Read-only once NationBuilder bills the recurring donation.
      - `description` string, nullable: A free-text description.
      - `donation_tracking_code_id` string, nullable: The tracking code attached to the recurring donation.
      - `external_id` string, nullable: The identifier of the recurring donation in the external billing system.
      - `frequency` 'monthly' | 'annual' | 'null', nullable: How often the recurring donation is billed. Set on create only.
      - `page_id` string, nullable: The page the recurring donation was created on.
      - `private` boolean, nullable: Whether the recurring donation is hidden from public displays.
      - `recruiter_id` string, nullable: The signup credited with recruiting the donor.
      - `signup_id` string, nullable: The signup the recurring donation belongs to. Set on create only.
      - `start_date` string, date-time, nullable: When the recurring donation started.
      - `status` 'pending' | 'active' | 'canceled' | 'completed' | 'failed' | 'failing' | 'null', nullable: The status of the recurring donation.
      - `canceled_date` string, date-time, nullable: When the recurring donation was canceled.
      - `created_at` string, date-time, nullable: When the recurring donation was created.
      - `last_pay_date` string, date-time, nullable: When the last period was paid.
      - `managed` boolean, nullable: Whether NationBuilder bills the recurring donation. Unmanaged recurring donations are billed externally.
      - `merchant_account_id` string, nullable: The merchant account that bills the recurring donation. Null for unmanaged recurring donations. Read-only: which account bills a recurring donation is a transition, not an edit.
      - `next_bill_date` string, date-time, nullable: When the next period is billed. Set by the billing gateway for managed recurring donations; for unmanaged ones, derived from the last recorded donation plus one period.
      - `payment_type` 'donation' | 'invoice' | 'null', nullable: Whether each period produces a donation or an invoice.
      - `updated_at` string, date-time, nullable: When the recurring donation was last updated.
  - `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 could not have been meant. A missing `frequency` or `start_date`, an unknown `frequency`, a read-only attribute such as `merchant_account_id`, a status a client may not set, or a membership relationship that is not a plain `method: update`.
- `401`: The access token is missing, expired, or not authorized to access this resource.
- `422`: The request is well formed but the recurring donation is not. A missing `signup_id` or `amount_in_cents`, an amount of zero or less, cadence and duplicate `external_id` failures land here as a validation error document. A membership that cannot be associated lands here as an error response, and no recurring donation is created.
- `429`: The access token has exceeded its request quota for the current rate-limit window.

## Changes

- **2026-11-05** `d5c88ca497ac`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/changes/api/v2/recurring_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)