Skip to main content
A subscription represents a recurring donation that charges a donor automatically on a set schedule — daily, weekly, monthly, or annually. When you integrate with the subscriptions API, you can build features like donor retention dashboards, automated cancellation flows, payment method update flows, or dynamic giving-amount adjustments without requiring donors to update their information manually.

​
The subscription object

The following fields are returned by GET /v1/subscriptions and GET /v1/subscriptions/{id}.

​
Status values

​
Frequency values

Each successful subscription charge creates a corresponding payment record. You can cross-reference subscriptions and payments using the donor’s email address.
The Subscription object never includes the display-currency fields (displayCurrency, displayAmount, fxRate, fxRateTableId, fxRateAsOf) or lastChargeFx. For a donor who gives in a display currency, those arrive only on the subscription.created, subscription.updated and subscription.cancelled webhooks. See Display-currency fields.

​
What you can do

The subscriptions API supports four categories of operations:

List subscriptions

Retrieve all subscriptions for your account, optionally filtered by status.

Get a subscription

Fetch a single subscription record by its ID.

Update a subscription

Cancel a subscription or change the recurring amount.

Create a payment method update link

Generate a hosted link where a donor can securely update the card or bank account for an active subscription.

​
Updating subscriptions

You can modify an active subscription by cancelling it, changing the recurring amount, or creating a hosted payment method update link for the donor. Status and amount updates use PUT /v1/subscriptions/{id} with a JSON body.
Set status to CANCELLED to stop future charges immediately.

​
Display currency and amount changes

Nonprofits can let donors see amounts in a currency other than USD. This is display only; every charge, refund and payout stays in USD, and so does amount. The subscription record of such a donor carries the five display-currency fields and, after a renewal, lastChargeFx. They are sent on the subscription.created, subscription.updated and subscription.cancelled webhooks, never in /v1/subscriptions responses. When a subscription’s charged total changes — in the dashboard, the donor portal or through PUT /v1/subscriptions/{id} — the same update:
  • Removes the five top-level fields (displayCurrency, displayAmount, fxRate, fxRateTableId, fxRateAsOf) from the subscription. The change arrives as the usual subscription.updated without them. No new event type is added.
  • Keeps lastChargeFx (and lastChargeDonorForeignExchangeAt). It describes a charge that already happened, so a subscription.updated can carry lastChargeFx without the five top-level fields.
Field definitions, examples and the full rules are on the webhooks page.

​
Updating payment methods

To update a subscription’s payment method, call POST /v1/subscriptions/{id}/payment-method-update-link. CharityStack returns a short-lived hosted URL that lets the donor save a new card or bank account without your server handling sensitive payment details. The hosted page supports CARD and PAY_BY_BANK updates for subscriptions processed by Stripe or Finix. Stripe payment details are collected through Stripe’s client-side setup flows. Finix card details are collected through Finix tokenization fields, and Finix bank details are collected through Plaid Link.
Give the link only to the donor after you have authenticated them in your own app. The hosted CharityStack page is protected by the session token in the URL, but the partner app controls who receives the link.
Cancellation is immediate and irreversible through the API. The subscription status will change to CANCELLED and no further charges will be made. To restart a cancelled subscription, the donor must re-enroll through a donation form.