Skip to main content
The PUT /v1/subscriptions/{id} endpoint lets you modify an existing subscription. You can cancel a subscription by setting status to CANCELLED, adjust the recurring amount by passing a new amount, or do both in a single request. At least one field must be included in the request body. This endpoint requires the subscriptions:write permission on your API key.
Cancelling a subscription is irreversible through the API. The donor will no longer be charged after the current billing cycle ends.

​
Path parameters

​
id
string
required
The unique identifier of the subscription to update, for example sub_01HABC1234MNOPQR.

​
Request body

​
status
string
New status for the subscription. Accepted values: ACTIVE, CANCELLED.
​
amount
number
New recurring charge amount in US dollars. Must be a positive number.

​
Response

On success the endpoint returns the updated Subscription object.
​
id
string
required
Unique identifier for the subscription.
​
status
string
required
Updated subscription status. One of: ACTIVE, CANCELLED.
​
amount
number
required
Updated recurring charge amount in US dollars.
​
frequency
string
required
Billing frequency. One of: DAILY, WEEKLY, MONTHLY, ANNUALLY.
​
nextBillingDate
string
required
ISO 8601 date of the next scheduled charge.
​
lastBillingDate
string
required
ISO 8601 date of the most recent successful charge.
​
endBillingDate
string
required
ISO 8601 date when the subscription is scheduled to end.
​
coveredFee
boolean
required
Whether the donor elected to cover processing fees on each charge.

​
Response codes

CodeMeaning
200Subscription updated successfully.
400Invalid status value or non-positive amount.
403The subscription belongs to a different merchant account.
404No subscription with that ID exists.

​
Examples

curl -X PUT https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/subscriptions/sub_01HABC1234MNOPQR \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "CANCELLED"}'
Response
{
  "id": "sub_01HABC1234MNOPQR",
  "status": "CANCELLED",
  "amount": 25.00,
  "frequency": "MONTHLY",
  "nextBillingDate": "2025-05-14T00:00:00Z",
  "lastBillingDate": "2025-04-14T00:00:00Z",
  "endBillingDate": "2026-04-14T00:00:00Z",
  "coveredFee": false
}