Cancel a subscription from the API — at period end

Anyway Team

· 2 min read ·

From 9 November 2026, you can cancel a customer subscription through the Anyway Merchant API. POST /v1/subscriptions/{id}/cancel stops further renewals and leaves the customer with access until the current paid period ends.

The call does not issue a refund. It matches the period-end cancel you can already make in the dashboard, and the one a buyer can make on the self-serve page described in Customers and subscriptions.

This is a standalone post about the endpoint. It does not replace the combined November 2026 product update. The public reference is Cancel a subscription.

What the call does

Send POST /v1/subscriptions/{id}/cancel to https://merchant-api-prod.anyway.sh, with your key in the X-API-Key header. The documented behavior is a period-end cancel: cancelAtPeriodEnd is true, and the customer keeps access until currentPeriodEnd.

The effect is the same as canceling in the dashboard:

  • The customer receives an email.

  • The subscription event notifications you already configured still go out, including webhooks.

  • This cancel itself does not refund the customer. Process a refund separately if your refund policy requires one.


Repeat calls return normally and do not change the subscription again. If you are following a subscription in the dashboard, the order and subscription timeline is the place to see a scheduled cancellation without treating that state as already ended.

Permission and errors

The new permission is sales:subscriptions:write. In the dashboard it appears under scoped permissions → create and edit → Cancel subscription. A key without that permission is rejected with 403 INSUFFICIENT_SCOPE.

Existing all-permission keys can call the new endpoint. Scoped keys are unchanged unless you add this permission. You can only grant permissions your own role has; see authentication and Roles and permissions.

Other responses called out in the 9 November product-update record:

  • 409 SUBSCRIPTION_NOT_CANCELABLE if the subscription is no longer in a state that can be canceled

  • 502 PROVIDER_ERROR if the provider is temporarily unavailable; you can retry

The public reference page also lists 401, 404, and 500 among the documented HTTP statuses for this endpoint. This article does not invent messages for those codes beyond what that page and the product-update record state.

This update is for merchants who already have subscriptions and who use Merchant API keys (Developers → Merchant API keys).

Frequently asked questions

Does this cancel the subscription immediately?

No. The documented behavior is a period-end cancel. cancelAtPeriodEnd is true, and access continues until currentPeriodEnd.

Does calling cancel also refund the customer?

No. This cancel itself does not issue a refund. Process a refund separately if you need one.

Which permission does the key need?

sales:subscriptions:write. Existing all-permission keys can call the endpoint. Scoped keys need that permission added.

What if I call the endpoint twice?

The 9 November record says a repeat call returns normally and does not change the subscription again.

You might also like