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}.
FieldTypeDescription
idstringUnique identifier for the subscription
statusstringCurrent subscription status (see below)
amountnumberRecurring charge amount in dollars
frequencystringBilling cadence (see below)
nextBillingDatestringISO 8601 date of the next scheduled charge
lastBillingDatestringISO 8601 date of the most recent successful charge
endBillingDatestringISO 8601 date when the subscription is scheduled to end
coveredFeebooleanWhether the donor opted to cover processing fees

​
Status values

ValueMeaning
ACTIVESubscription is running and will charge on schedule
CANCELLEDSubscription has been cancelled and will not charge again

​
Frequency values

ValueBilling cadence
DAILYCharged every day
WEEKLYCharged every week
MONTHLYCharged every month
ANNUALLYCharged once per year
Each successful subscription charge creates a corresponding payment record. You can cross-reference subscriptions and payments using the donor’s email address.

​
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.
curl -X PUT https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/subscriptions/sub_123 \
  -H "Authorization: Bearer cs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "CANCELLED"}'

​
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.