Skip to main content
PATCH

​
Cancel Subscription

​
Intro

Cancel a subscription by ID. Cancellation is immediate: billing stops right away at the gateway and the subscription’s status flips to cancelled in the same call — there’s no “runs until the end of the current period” option.

​
Context

This is the write endpoint in the subscription trio, alongside the read-only List Subscriptions and Get Subscription. Subscriptions are created by adding subscription_frequency_key to a charge or checkout session — see Subscriptions — and this is the only Partner API endpoint that ends one. Khaime tracks which gateway is billing a given subscription (Stripe or Paystack), and this endpoint cancels it there as well as in Khaime’s own records, so calling it is enough on its own — you don’t need to also cancel the subscription directly with the gateway.

​
Hows

PATCH /subscriptions/{subscription_id}/cancel

​
Path parameters

​
What happens

  1. The subscription is looked up and checked against your merchant and your API key’s environment (sandbox/live), the same as Get Subscription.
  2. If it’s already cancelled, the call fails rather than being treated as a no-op.
  3. If the subscription is billed through Stripe or Paystack, Khaime cancels it there. If the gateway call fails, cancellation still proceeds in Khaime’s records — a subscription is never left half-cancelled because of a transient gateway error.
  4. The subscription’s status is set to cancelled and its cancellation date recorded.

​
Response

​
Errors

​
Whys

Cancellation is immediate rather than deferred to the end of the current billing period because a partner calling this API is almost always reacting to something that already happened elsewhere — a customer closed their account, a fraud check failed, a plan was replaced — and in those cases “stop billing them starting now” is the expected behavior, not “one more charge is still coming.” An immediate cutover also keeps Khaime’s stored status and the gateway’s subscription state from disagreeing with each other, which a deferred cancellation would otherwise require tracking separately until the period actually ends. Ownership and environment are re-checked here exactly as they are on Get Subscription, and for the same reason: a sandbox key can’t discover or affect a live subscription (or someone else’s), so both cases return the same 404 SUBSCRIPTION_PLAN_NOT_FOUND rather than a more specific error that would confirm the ID’s existence.

​
Why nots

  • This endpoint doesn’t schedule a cancellation for a future date or the end of the current period — it cancels now. If you need “let them keep access until they’ve paid for,” build that on your side and call this endpoint when that date arrives.
  • It doesn’t issue a refund for the unused portion of the current period. If the customer is owed money back, issue it separately (see Refunds).
  • It’s not reversible. Once a subscription is cancelled, this endpoint won’t reactivate it — cancelling an already-cancelled subscription returns SUBSCRIPTION_ALREADY_ACTIVE rather than succeeding again. Start a new subscription (a new charge with subscription_frequency_key) if the customer wants to resume.
  • There’s no pause/resume here even though paused is a valid subscription status elsewhere in the system — this endpoint only moves a subscription to cancelled.