# Billing Setup

- **Method:** `POST`
- **Path:** `/api/v1/billing/setup`
- **Operation ID:** `billing_setup`
- **Tags:** usage

A SetupIntent to put a card on file, or change it (`stripe.confirmSetup`). The card becomes the one
top-ups and auto-refill charge when Stripe reports the intent succeeded.

## 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: `BillingSetup`, no additional properties

`POST /api/v1/billing/setup`: a SetupIntent for a card Saram may charge off-session (auto-refill). The card
becomes this tenant's card on file when Stripe reports the intent succeeded.

- **`client_secret` (required)**: `string`

  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.
- **`setup_intent_id` (required)**: `string`

**Example:**

```json
{
  "setup_intent_id": "",
  "client_secret": ""
}
```

### 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

### 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

- `BillingSetup` — shown above.