Skip to main content

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/${ORGANIZATION_ID}/subscription-cancellations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey ${API_KEY}' \
  -d '{
    "subscriptionId": "ord_xxx",
    "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/${ORGANIZATION_ID}/subscription-cancellations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey ${API_KEY}' \
  -d '{
    "subscriptionId": "ord_xxx",
    "reason":         "too-expensive",
    "cancelAt":       "2026-06-30T23:59:59Z"
  }'

Cancellation reason values​

ValueWhen to use
did-not-useCustomer reported they did not use the service.
did-not-wantCustomer no longer wants the service.
missing-featuresService did not have a feature the customer needed.
bugs-or-problemsCustomer experienced technical problems.
too-expensiveCustomer canceled on price.
do-not-rememberCustomer does not remember signing up.
risk-warningPayments AI risk system flagged the subscription.
contract-expiredA fixed-term contract reached its end.
billing-failureCancellation triggered by exhausted dunning retries.
otherAnything not covered above.

Who canceled​

The cancelledBy field records the actor:

ValueMeaning
customerCustomer initiated the cancellation.
merchantMerchant initiated it.
systemPayments AI initiated it (typically after exhausted dunning).

CRUD on cancellations​

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