# Account and billing endpoints

> Read your Vigilbase One account, active services, endpoints and billing summary, and open the Stripe billing portal, over the One API.

Source: https://docs.vigilbase.com/one/api/account-and-billing

These endpoints work on the organisation your token belongs to and take no customer ID. None has a v1 operation yet: they are on `https://one.vigilbase.com`, and answer in [One's older shapes](https://docs.vigilbase.com/one/api#older-error-shapes). Sign-in, permissions, rate limits and error shapes are on [Vigilbase One API](https://docs.vigilbase.com/one/api).

| Method and path | Permission | CLI command |
| --- | --- | --- |
| `GET /api/account` | Any member | `vigilbase account` |
| `GET /api/account/services` | `read:services` | `vigilbase account services` |
| `GET /api/account/endpoints` | `read:services` | `vigilbase account endpoints` |
| `GET /api/account/organization` | Any member | `vigilbase account organization` |
| `GET /api/account/billing` | `read:billing` | `vigilbase billing` |
| `POST /api/billing/portal` | `write:billing` and a recent sign-in | |

When your organisation has no customer record yet, the reads below answer `200` with `customer: null` and empty lists, not `404`.

## Your account

`GET /api/account` returns who you are and the organisation and customer the token is for.

```json
{
  "success": true,
  "user": { "id": "…", "email": "you@example.com", "name": "…" },
  "organization": { "id": "…", "name": "…", "slug": "…", "role": "owner" },
  "customer": { "id": "…", "name": "…", "domain": "example.com", "status": "customer", "isPartner": false },
  "isInternal": false
}
```

`customer` is filled in only when your role has `read:customers` or `read:partner_customers`; otherwise it is `null` and the request still succeeds. `customer.id` is the customer ID that other endpoints take.

## Services

`GET /api/account/services` lists your active services, newest first.

| Field | Contents |
| --- | --- |
| `customer` | Your customer: `id`, `name`, `domain`, `status`, `isPartner` |
| `services` | Each active service: `id`, `tool`, `status`, `domain`, `createdAt` |
| `serviceTypes` | The distinct service types |
| `endpointCount` | How many endpoints your organisation has |

## Endpoints

`GET /api/account/endpoints` returns `customer` and `endpoints`, sorted by display name. Each endpoint has `id`, `displayName`, `systemName`, `dnsName`, `deviceType`, `integration`, `isOffline` and `lastContact`. The list isn't paged.

## Organisation and members

`GET /api/account/organization` returns:

- `organization`: the token's organisation, with `id`, `name`, `displayName` and your `role`. `name` is the organisation's short name (slug); `displayName` is the name people see.
- `members`: its members, each with `userId`, `email`, `name` and `role`.
- `organizations`: every organisation you belong to, in the same shape. `role` is set only for the token's organisation.

## Billing summary

`GET /api/account/billing` returns an overview without Stripe IDs:

```json
{
  "success": true,
  "billing": {
    "customer": { "id": "…", "name": "…", "domain": "…", "status": "customer", "isPartner": false },
    "hasStripeCustomer": true,
    "serviceCount": 3,
    "endpointCount": 12,
    "serviceTypes": ["cloudflare"]
  }
}
```

`billing` is `null` when your organisation has no customer record. Invoices and subscriptions are on [Customers](https://docs.vigilbase.com/one/api/customers#invoices-and-subscriptions).

## Open the billing portal

`POST /api/billing/portal` creates a Stripe Customer Portal session for your organisation's Stripe customer. It needs `write:billing` (owners and admins) and a [sign-in from the last 10 minutes](https://docs.vigilbase.com/one/api#changes-that-need-a-recent-sign-in).

Send a new random UUID as `operationId` with each new request:

```json
{ "operationId": "3f1c2a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f" }
```

The body must contain only `operationId`. Sending the same `operationId` again returns the same portal session rather than creating another one, so you can retry safely.

```json
{
  "success": true,
  "data": {
    "operationId": "3f1c2a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f",
    "replayed": false,
    "url": "https://billing.stripe.com/p/session/…"
  }
}
```

Open `data.url` in a browser. The portal's return link goes to **Billing** in One (`/dashboard/billing`).

| Status | When |
| --- | --- |
| `400` | The body is missing, isn't JSON, or isn't exactly `{ "operationId": "<uuid>" }` |
| `401` | The sign-in is older than 10 minutes |
| `403` | Your role lacks `write:billing` |
| `404` | Your organisation has no customer record, or no Stripe customer |
| `409` | Billing changes aren't available for this account right now, or the account is billed through a partner |

Customers billed through a partner manage billing with that partner, so the portal isn't available to them. See [Billing](https://docs.vigilbase.com/one/billing).