# Billing Cancel

- **Method:** `DELETE`
- **Path:** `/api/v1/billing/subscription`
- **Operation ID:** `billing_cancel`
- **Tags:** usage

Cancel Saram Pro at the end of the month already paid for; the tenant then moves to Free. The month's
included credit stays until it expires, because the month's fee bought it.

## Effective servers

- `https://api.saram.sh`

  Saram

## Authentication

- **HTTPBearer**: HTTP bearer

  a Saram API key (`sk_saram_<env>_...`) or a person's AuthKit access token, as `Authorization: Bearer <credential>`. Both are told apart by shape and produce the same principal.

## Responses

### 200 Successful Response

**Content type:** `application/json`

schema: `BillingSubscription`, no additional properties

`POST` and `DELETE /api/v1/billing/subscription`: the Saram Pro subscription and, while its first invoice
is unpaid, the secret the Payment Element pays it with.

The tenant's plan becomes `pro` when Stripe reports the subscription active, not when this answers: an
abandoned checkout leaves the tenant where it was, and expires at Stripe within a day.

- **`cancel_at_period_end` (required)**: `boolean`

  Pro ends when the month already paid for does; the tenant then moves to Free.
- **`status` (required)**: `string`

  Stripe's: `incomplete` until the first invoice is paid, then `active`; `past_due` when a renewal failed; `canceled` once it has ended.
- **`subscription_id` (required)**: `string`
- **`client_secret`**: `string | null`

  What the Payment Element confirms in the browser (stripe.confirmPayment / confirmSetup), where SCA happens. Present only while there is something to confirm. Saram never sees the card.

**Example:**

```json
{
  "subscription_id": "",
  "status": "",
  "client_secret": "",
  "cancel_at_period_end": true
}
```

### 403 this credential may not manage billing: an API key without the keys:admin scope, or a person whose role in this tenant is not owner or admin

### 409 the tenant is already on Saram Pro or on a subscription an operator moves; or the top-up would pass the tenant's own monthly budget

### 422 an amount out of bounds, or auto-refill turned on without a threshold, amount or card

### 502 Stripe refused the request or could not be reached; the detail is Stripe's own message

### 503 this deployment has no Stripe key configured, or its Stripe account is not set up for what was asked, so nothing is started and nothing is charged

## Schemas

- `BillingSubscription` — shown above.