---
title: "Update recurring donation with provided ID"
method: PATCH
path: "/api/v2/recurring_donations/{id}"
tags: ["Recurring Donations"]
---

# Update recurring donation with provided ID

`PATCH /api/v2/recurring_donations/{id}`

## Request

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

Updates a recurring donation. Which fields you may send depends on who bills it.

**Unmanaged** — the non-billing fields plus `amount_in_cents` and `status`.

**Managed** — the non-billing fields only. Sending `amount_in_cents` or `status` returns
400, because NationBuilder bills the donor and the gateway owns them.

`signup_id` and `frequency` are create-only. `merchant_account_id` is read-only. `canceled`
is not a `status` you can send; cancel with
`PATCH /api/v2/recurring_donations/{id}/cancel`.

A membership relationship associates a membership with a recurring donation that has none.
Sending the membership it already has changes nothing. See
`recurring_donation_membership_relationship`.

## Request body

- RecurringDonationUpdateRequest: The JSON:API top-level document shape for update requests, whose data member identifies the resource by type and id and carries the changed attributes.
  - `data` object, required
    - `id` string, required: The ID of the resource being updated.
    - `type` 'recurring_donations', required: The JSON:API resource type of the resource being updated.
    - `attributes` object: The attributes of a recurring_donation that can be both read and written.
      - `amount_in_cents` integer, nullable: Unmanaged recurring donations only. Sending it for a recurring donation NationBuilder bills returns 400.
      - `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` 'active' | 'completed' | 'failed', nullable: Unmanaged recurring donations only. Sending it for a recurring donation NationBuilder bills returns 400. `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 `200`

The updated 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`: A field this kind of recurring donation may not change, a create-only field, a status a client may not set, `start_date` or `external_id` set to null, 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.
- `404`: No resource exists with the provided ID.
- `422`: The recurring donation failed validation, such as a duplicate `external_id`, as a validation error document. A membership that cannot be associated lands here as an error response.
- `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/:id/patch.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)