> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instapods.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing

> Manage subscriptions, payment methods, invoices, and credits.

All billing is scoped to the active team. Amounts are in **cents** (e.g., `300` = \$3.00).

## Subscription

### Get Subscription

```
GET /api/billing/subscription
```

**Response: `200 OK`**

```json theme={null}
{
  "id": "sub_abc123",
  "team_id": "team_xyz",
  "plan_slug": "build",
  "status": "active",
  "current_period_start": "2026-02-01T00:00:00Z",
  "current_period_end": "2026-03-01T00:00:00Z",
  "created_at": "2026-01-15T10:00:00Z"
}
```

**Subscription statuses:** `active`, `cancelled`, `past_due`, `trialing`

### Subscribe

```
POST /api/billing/subscribe
```

```json theme={null}
{
  "plan_slug": "build"
}
```

**Response: `201 Created`** — returns the subscription object.

### Change Plan

```
PUT /api/billing/subscription/plan
```

```json theme={null}
{
  "plan_slug": "grow"
}
```

Changes take effect immediately. Billing is prorated.

### Cancel

```
POST /api/billing/subscription/cancel
```

```json theme={null}
{ "status": "cancelled" }
```

### Resume

```
POST /api/billing/subscription/resume
```

Reactivates a cancelled subscription before the period ends.

***

## Invoices

### List Invoices

```
GET /api/billing/invoices
```

**Response: `200 OK`**

```json theme={null}
[
  {
    "id": "inv_abc123",
    "status": "paid",
    "amount_due": 700,
    "amount_paid": 700,
    "currency": "usd",
    "period_start": "2026-02-01T00:00:00Z",
    "period_end": "2026-03-01T00:00:00Z",
    "paid_at": "2026-02-05T10:30:00Z",
    "created_at": "2026-02-01T00:00:00Z"
  }
]
```

**Invoice statuses:** `draft`, `open`, `paid`, `void`, `uncollectible`

### Get Invoice

```
GET /api/billing/invoices/{invoiceId}
```

Returns the full invoice object including line items.

***

## Payment Methods

### List Payment Methods

```
GET /api/billing/payment-methods
```

**Response: `200 OK`**

```json theme={null}
[
  {
    "id": "pm_abc123",
    "type": "card",
    "card_brand": "visa",
    "card_last4": "4242",
    "card_exp_month": 12,
    "card_exp_year": 2027,
    "is_default": true,
    "created_at": "2026-01-15T10:00:00Z"
  }
]
```

### Add Payment Method

```
POST /api/billing/payment-methods
```

```json theme={null}
{
  "stripe_payment_method_id": "pm_xxx"
}
```

**Response: `201 Created`** — returns the payment method with card details fetched from Stripe.

### Set Default

```
POST /api/billing/payment-methods/default
```

```json theme={null}
{
  "payment_method_id": "pm_abc123"
}
```

### Remove

```
DELETE /api/billing/payment-methods/{pmId}
```

### Create SetupIntent

```
POST /api/billing/setup-intent
```

**Response: `200 OK`**

```json theme={null}
{
  "client_secret": "seti_xxx_secret_yyy"
}
```

Used by the frontend Stripe Elements flow to securely collect card details.

***

## Credits & Upcoming Charges

### Get Credits

```
GET /api/billing/credits
```

```json theme={null}
{
  "available": 5000,
  "credits": [
    {
      "id": "cred_abc",
      "amount": 5000,
      "remaining": 2000,
      "type": "promo",
      "reason": "Welcome bonus",
      "expires_at": "2026-12-31T23:59:59Z"
    }
  ]
}
```

**Credit types:** `promo`, `bonus`, `refund`

### Preview Upcoming Charges

```
GET /api/billing/upcoming
```

```json theme={null}
{
  "charges": [
    {
      "pod_name": "my-app",
      "pod_status": "running",
      "plan_slug": "build",
      "plan_name": "Build",
      "monthly_rate": 700,
      "daily_rate": 23,
      "active_days": 20,
      "amount": 460
    }
  ],
  "subtotal": 460,
  "credits_available": 200,
  "estimated_total": 260,
  "period_start": "2026-02-01T00:00:00Z",
  "period_end": "2026-03-01T00:00:00Z"
}
```

<Note>
  Pods are billed daily based on their plan. Stopped pods still incur charges — only deleting a pod stops billing.
</Note>