# Cancel subscriptions URL: https://docs.hanzo.ai/docs/openapi/billing/cancelsubscription > Ends a subscription. `POST /v1/billing/subscriptions/{id}/cancel` > [Billing →](https://docs.hanzo.ai/docs/openapi/billing) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | ----------------------------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/billing/subscriptions/{id}/cancel` | | **Method** | `POST` | | **Operation** | `cancelSubscription` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Ends a subscription. It cancels at the END OF THE PAID PERIOD by default, because a customer who cancels has already paid for the period they are in and taking it away is taking money for nothing. `atPeriodEnd: false` ends it at once, which is the caller asking for that. A subscription from another org is not found rather than refused, so an id cannot be probed for existence. A named handler, not a closure, so zipdoc can lift this prose into the registry. ## Request 3 fields, body `application/json` (required). | Field | In | Type | Required | Description | | ------------- | ---- | ------- | -------- | ---------------------------------------------------------------------- | | `id` | path | string | yes | | | `atPeriodEnd` | body | boolean | — | AtPeriodEnd cancels at the end of the paid period rather than at once. | | `id` | body | string | — | | ## Response | Status | Body | Meaning | | --------- | -------------------- | ------- | | `200` | billing.Subscription | ok | | `default` | problem-details | refused | `200` body — 26 fields. | Field | In | Type | Always | Description | | ---------------------- | ---- | ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cancelAtPeriodEnd` | body | boolean | — | CancelAtPeriodEnd reports that the plan ends at CurrentPeriodEnd. | | `canceledAt` | body | string | — | CanceledAt is when it was canceled; absent when it was not. | | `chargedCents` | body | integer (int64) | — | ChargedCents is what the period in hand was actually paid, after any discount and net of refunds. | | `createdAt` | body | string | — | CreatedAt is when the row was written, RFC 3339. | | `currentPeriodEnd` | body | string | — | CurrentPeriodEnd is when it ends, RFC 3339. | | `currentPeriodStart` | body | string | — | CurrentPeriodStart is when the period in hand began, RFC 3339. | | `defaultPaymentMethod` | body | string | — | DefaultPaymentMethod is the saved method a renewal would use. | | `endedAt` | body | string | — | EndedAt is when it ended; absent while it runs. | | `id` | body | string | — | ID is the subscription's own id, the one cancel and reactivate take. | | `mrrCents` | body | integer (int64) | — | MRRCents is what this subscription contributes per month — commerce's own figure, interval-normalized and multiplied by its seats, so no reader re-derives it from price and interval. | | `plan` | body | billing.SubscriptionPlan | — | | | `plan.currency` | body | string | — | Currency is the ISO code the price is in, lower-cased. | | `plan.id` | body | string | — | ID is the plan row the subscription was opened on. | | `plan.interval` | body | string | — | Interval is the billing period: "month" or "year". | | `plan.name` | body | string | — | Name is the plan's display name, e.g. "Max 20x". | | `plan.price` | body | integer (int64) | — | Price is what one period costs per seat, in cents, as the subscription snapshotted it: a later catalog price change does not move it. | | `planId` | body | string | — | PlanID is the plan slug, e.g. "max-20x". | | `providerType` | body | string | — | ProviderType is who collects it: a processor ("square"), "credit" for a plan bought with credits, "internal" or "bundle" for a row nobody paid for. | | `quantity` | body | integer (int64) | — | Quantity is the seat count; a flat plan holds 1. | | `seats` | body | integer (int64) | — | Seats is the seat count the period in hand was paid for — its paid invoice's quantity, or the quantity recorded with an external period — never the row's live Quantity, which the holder may change. | | `settled` | body | string | — | Settled is how the period in hand was paid: "card" (a card paid all of it), "external:\" (a payment recorded as collected outside commerce), "balance", "credit" or "mixed" (prepaid money). | | `status` | body | string | — | Status is trialing, active, past\_due, canceled or unpaid. | | `trialEnd` | body | string | — | TrialEnd is when that trial ends; absent when there was none. | | `trialStart` | body | string | — | TrialStart is when a trial began; absent when there was none. | | `updatedAt` | body | string | — | UpdatedAt is when the row last changed, RFC 3339. | | `userId` | body | string | — | UserID is the billing account that holds it: the org slug for an org's own plan, "\/\" for a member's. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo billing subscriptions cancel ``` **SDK** **.ts** ```ts import { Configuration, BillingApi } from 'hanzoai'; const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.cancelSubscription({ id: 'id', atPeriodEnd: false, id: "" }); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import BillingApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = BillingApi(client).cancel_subscription(id='id', at_period_end=False, id="") ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.BillingAPI.CancelSubscription(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, billing_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = billing_api::cancel_subscription(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.BillingApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new BillingApi(client).cancelSubscription(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/billing/subscriptions//cancel \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "atPeriodEnd": false, "id": "" }' ``` **MCP** Tool `billing`, op `cancelSubscription` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`. ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "billing", "arguments": { "op": "cancelSubscription", "input": { "id": "", "atPeriodEnd": false } } } }' ``` --- [Billing API](https://docs.hanzo.ai/docs/openapi/billing) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)