---
title: "Cancel an unmanaged recurring donation"
method: PATCH
path: "/api/v2/recurring_donations/{id}/cancel"
tags: ["Recurring Donations"]
---

# Cancel an unmanaged recurring donation

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

## Request

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

Cancels a recurring donation NationBuilder does not bill. Recurring donations NationBuilder
bills are canceled in the control panel or the supporter portal, and return 400 here.

The recurring donation is always canceled immediately: its status becomes `canceled`,
`canceled_date` is set, and a `Recurring Donation Canceled` activity is written. What
happens to the membership it pays for depends on the body.

**`data.canceled_date`** — stamps that date on the recurring donation and its activity
instead of now. Send this to import a series that already ended. It only changes the
recorded date: the membership is still canceled now unless `data.membership_expires_on`
is sent.

**No `data.membership_expires_on`** — the membership is canceled now as well.

**`data.membership_expires_on`** — the membership stays active until that date, with a
`Membership Cancelation Scheduled` activity attributed to the token owner. The nightly
membership job cancels it on that date. Send this to honour the period the donor already
paid for. There is no default; the recurring donation's `next_bill_date` is not used as
one.

## Request body

- RecurringDonationCancelRequest: The optional body for canceling a recurring donation.
  - `data` object, required
    - `membership_expires_on` string, date: Keep the membership this recurring donation pays for active until this date, instead of canceling it now. ISO 8601, today or later. Only valid when the recurring donation pays for an active membership.
    - `canceled_date` string: When the recurring donation was canceled, for importing a series that already ended. ISO 8601 date-time, or a date for the start of that day. Now or earlier, and not before `start_date` or the last successful payment. Defaults to now.

## Response `200`

The canceled 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`: Returned when any of these is true: * The body is not wrapped in `data`. * `data` carries a key other than `membership_expires_on` or `canceled_date`. * NationBuilder bills this recurring donation. * `data.membership_expires_on` was sent for a recurring donation that pays for no membership. * `data.membership_expires_on` is not an ISO 8601 date. * `data.canceled_date` is not an ISO 8601 date or date-time.
- `401`: The access token is missing, expired, or not authorized to access this resource.
- `404`: No resource exists with the provided ID.
- `422`: Returned when any of these is true: * The recurring donation is already canceled. * The membership is no longer active. * `data.membership_expires_on` was sent and another active, failing or pending recurring donation pays for the membership. * `data.membership_expires_on` is in the past. * `data.canceled_date` is in the future. * `data.canceled_date` is before the recurring donation's `start_date`. * `data.canceled_date` is before the recurring donation's last successful payment.
- `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/cancel/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)