Subscription cancellations
A subscription can be canceled at any point. Cancellation is modelled as a separate resource in the API, so the cancellation has its own ID and its own properties — distinct from the subscription itself.
Immediate vs scheduled cancellation
Both use the same endpoint, but the cancelAt field changes the timing.
Immediate cancellation
Omit cancelAt. The subscription transitions to canceled straight away and no further renewals are charged.
curl -i -X POST \
'https://staging-api.payments.ai/v1/public-api/organizations/:organizationId/subscription-cancellations' \
-H 'Content-Type: application/json' \
-H 'Authorization: ApiKey <keyValue>' \
-d '{
"subscriptionId": "ord_xxx",
"cancelledBy": "customer",
"reason": "did-not-want"
}'
Scheduled cancellation
Set cancelAt to a future date-time. The subscription stays active until that point, continues to renew on schedule, and then transitions to canceled. Until cancelAt passes, the cancellation can be undone — see Subscription reactivation.
curl -i -X POST \
'https://staging-api.payments.ai/v1/public-api/organizations/:organizationId/subscription-cancellations' \
-H 'Content-Type: application/json' \
-H 'Authorization: ApiKey <keyValue>' \
-d '{
"subscriptionId": "ord_xxx",
"cancelledBy": "customer",
"reason": "too-expensive",
"cancelAt": "2026-06-30T23:59:59Z"
}'
Cancellation reason values
| Value | When to use |
|---|---|
did-not-use | Customer reported they did not use the service. |
did-not-want | Customer no longer wants the service. |
missing-features | Service did not have a feature the customer needed. |
bugs-or-problems | Customer experienced technical problems. |
too-expensive | Customer canceled on price. |
do-not-remember | Customer does not remember signing up. |
risk-warning | PaymentsAI risk system flagged the subscription. |
contract-expired | A fixed-term contract reached its end. |
billing-failure | Cancellation triggered by exhausted dunning retries. |
other | Anything not covered above. |
Who canceled
The cancelledBy field records the actor:
| Value | Meaning |
|---|---|
customer | Customer initiated the cancellation. |
merchant | Merchant initiated it. |
system | PaymentsAI initiated it (typically after exhausted dunning). |
CRUD on cancellations
| Method | Path |
|---|---|
| POST | /.../subscription-cancellations (create) |
| GET | /.../subscription-cancellations (list) |
| GET | /.../subscription-cancellations/{id} (one) |
| PATCH | /.../subscription-cancellations/{id} (update) |
| DELETE | /.../subscription-cancellations/{id} (delete) |
A cancellation can be deleted only while it is still in draft state. Once it has applied to the subscription, undoing it requires reactivation — see Subscription reactivation.
Webhook
subscription-canceled fires when the cancellation applies. For terminal churn after dunning, subscription-churned fires instead. See Subscription webhooks for the full event list.