---
title: "Cancel a subscription"
method: POST
path: "/gateway/subscriptions/{id}/cancel"
tags: ["Subscriptions"]
---

# Cancel a subscription

`POST /gateway/subscriptions/{id}/cancel`

## Request

- Base URL: `https://api.agentaos.ai/api/v1`
- URL: `https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/cancel`
- Auth: API key in header `x-api-key`

Cancels at the end of the current paid period by default: the subscriber keeps what they already paid for, no refund. Pass `atPeriodEnd: false` to cancel immediately instead. Calling cancel again on an already-`canceled` subscription is a no-op. Returns `400` if the subscription never completed a first successful charge (`stripeSubscriptionId` is `null`).

## Path parameters

- `id` string, uuid, required

## Request body

- CancelSubscriptionRequest
  - `atPeriodEnd` boolean: true schedules the cancellation for period end. false cancels now.

## Response `200`

The subscription's updated cancellation state.

- CancelSubscriptionResponse
  - `status` 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | 'paused', required
  - `currentPeriodEnd` string, date-time, nullable, required
  - `cancelAtPeriodEnd` boolean, required
  - `effectiveCancelDate` string, date-time, nullable, required

## Other responses

- `400`: A required field is missing, out of range, or the wrong type. `ValidationPipe` also rejects any field not in the documented schema.
- `401`: Missing or invalid `x-api-key`.
- `403`: The key is valid but the resource belongs to a different organization.
- `404`: Resource not found (or not visible to your key; the two are not distinguished).

---

[API](https://skmtc.dev/agentaos/apis/agentaos-gateway-api.md) · [All operations](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/revisions/3a8ad3c6b965?raw)