# Account

Source: https://phonebox.dev/docs/api-reference/account

> Read the project's balance, reservations, monthly spending, limits, phone counts, price, countries, starter credit, top-up link and plan, and create a checkout link for credits.



The account belongs to the project that the key selects. [Pricing and credits](/docs/billing/pricing) explains balances, reservations and the spending limit.

## Get the account [#get-the-account]

`GET /v1/account` needs the `phones:read` scope.

It reads the project and touches no phone, so it is a cheap way to check that a key works.

```bash
curl https://phonebox.dev/v1/account \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"
```

```json title="Response: account"
{
  "project": "Checkout QA",
  "balance_usd": "21.400000",
  "reserved_usd": "7.200000",
  "available_usd": "14.200000",
  "spend_limit_usd": "100.000000",
  "spent_this_month_usd": "4.120000",
  "limits": { "phones": 10, "running": 5 },
  "running": 1,
  "phones": 3,
  "price": { "per_minute_usd": "0.060000", "minimum_seconds": 60 },
  "countries": [
    { "code": "AR", "name": "Argentina" },
    { "code": "AU", "name": "Australia" },
    { "code": "US", "name": "United States" }
  ],
  "starter_credit": { "claimable": false, "amount_usd": "2.000000", "claim_url": null },
  "top_up_url": "https://phonebox.dev/topup/MS5qZDdhYmMxMjMuMTc5NDc4NzIwMA.3q2-7wQx9Kx0pE3w1n1q0c2l6m8s9v4b7y5z0a1b2c3",
  "plan": {
    "tier": "starter",
    "state": "subscribed",
    "status": "active",
    "trial_ends_at": null,
    "renews_at": "2026-12-06T10:00:00.000Z",
    "limits": {
      "running_phones": 5, "phones": 10, "idle_max_seconds": 3600, "session_max_seconds": 10800, "team_members": 5,
      "recordings": 20, "recording_days": 30, "saved_phone_days": null,
      "features": { "countries": true, "device_writes": true, "recordings": true, "credit": true }
    },
    "next_url": "https://phonebox.dev/topup/MS5qZDdhYmMxMjMuMTc5NDc4NzIwMA.3q2-7wQx9Kx0pE3w1n1q0c2l6m8s9v4b7y5z0a1b2c3"
  }
}
```

| Field                       | Type           | Meaning                                                                                                                                                                                                                                                   |
| --------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`                   | string         | The project's name.                                                                                                                                                                                                                                       |
| `balance_usd`               | money          | Your credit, before reservations.                                                                                                                                                                                                                         |
| `reserved_usd`              | money          | The credit held by open sessions.                                                                                                                                                                                                                         |
| `available_usd`             | money          | What a new session can reserve: `balance_usd` minus `reserved_usd`, never below zero.                                                                                                                                                                     |
| `spend_limit_usd`           | money          | The monthly spending limit.                                                                                                                                                                                                                               |
| `spent_this_month_usd`      | money          | What sessions that ended this calendar month, in UTC, were charged.                                                                                                                                                                                       |
| `limits.phones`             | integer        | The most phones the project can have, not counting deleted or failed ones.                                                                                                                                                                                |
| `limits.running`            | integer        | The most phones the project can run at once. The limit counts all of your projects together.                                                                                                                                                              |
| `running`                   | integer        | Phones with an open session: `creating`, `starting` or `ready`.                                                                                                                                                                                           |
| `phones`                    | integer        | Phones that count toward the phone limit: every phone that isn't deleted or failed.                                                                                                                                                                       |
| `price.per_minute_usd`      | money          | The price of a phone-minute.                                                                                                                                                                                                                              |
| `price.minimum_seconds`     | integer        | The shortest time a session is billed for.                                                                                                                                                                                                                |
| `countries`                 | array          | The countries a phone can be created in, as `{code, name}`, sorted by name. Pass a `code` as `country` when you [create a phone](/docs/api-reference/phones#create-a-phone). The example shows three of them. A country is where the phone appears to be. |
| `starter_credit.claimable`  | boolean        | Whether the project's owner can still unlock the one-time starter credit into this project by answering one question. Only an account's first project receives it.                                                                                        |
| `starter_credit.amount_usd` | money          | The starter credit's amount.                                                                                                                                                                                                                              |
| `starter_credit.claim_url`  | string or null | Where the owner signs in and answers the question, while `claimable` is true; otherwise `null`. Send your user here before you offer a paid top-up.                                                                                                       |
| `top_up_url`                | string         | A page where a member of this project signs in and pays for its credit, from $20. Give it to your user when credit runs out. It works for 30 days, and is the same link all day.                                                                          |

Treat `top_up_url` like a key you'd share with your user only: anyone who has it can pay for this project's credit, though it shows nothing but the project's name and grants nothing else. Every `insufficient_credits` error on a project that can buy credit carries the same link in `details.top_up_url`.

### The plan [#the-plan]

`plan` says which plan the project is on and what to do next. The `limits` under it are what the plan allows; the top-level `limits` above are the project's own phone limits, which can be lower.

| Field                                                             | Type            | Meaning                                                                                                                                                                                                |
| ----------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `plan.tier`                                                       | string          | `legacy` (a project from before plans), `lapsed` (no plan), `trial` (the free week), `starter` or `pro`.                                                                                               |
| `plan.state`                                                      | string          | What to do next: `no_trial` (the free week can start), `trialing`, `subscribed`, `lapsed` (start a plan again) or `legacy`. The same value is `details.plan_state` on an `insufficient_credits` error. |
| `plan.status`                                                     | string or null  | The subscription's status, such as `trialing`, `active` or `past_due`; `null` with no plan.                                                                                                            |
| `plan.trial_ends_at`                                              | string or null  | When the free week ends and the paid plan starts; `null` outside a free week.                                                                                                                          |
| `plan.renews_at`                                                  | string or null  | When the plan renews; `null` with no plan or one set to end.                                                                                                                                           |
| `plan.limits.running_phones`                                      | integer         | Phones that can run at once.                                                                                                                                                                           |
| `plan.limits.phones`                                              | integer         | Phones the project can hold.                                                                                                                                                                           |
| `plan.limits.idle_max_seconds`, `plan.limits.session_max_seconds` | integer         | The longest idle timeout and session a phone can have.                                                                                                                                                 |
| `plan.limits.team_members`                                        | integer         | People on the project, pending invites included.                                                                                                                                                       |
| `plan.limits.recordings`, `plan.limits.recording_days`            | integer         | Recordings kept, and for how many days. `0` means none.                                                                                                                                                |
| `plan.limits.saved_phone_days`                                    | integer or null | Days a parked phone is kept; `null` keeps it for good.                                                                                                                                                 |
| `plan.limits.features`                                            | object          | `countries`, `device_writes`, `recordings` and `credit`, each true or false. A false one answers `403 plan_required`.                                                                                  |
| `plan.next_url`                                                   | string          | A page where a member of the project signs in to take the next step for its state: start the free week, start Starter now, start a plan again, or add credit.                                          |

The balance, reservations, spending, limits and price are always the project's. For a key limited to certain phones, `running` and `phones` count only the phones that key may use.

This endpoint returns no errors of its own. The [common errors](/docs/api-reference#common-errors) apply.

## Create a checkout link [#create-a-checkout-link]

`POST /v1/credits/checkout` needs the `phones:control` scope.

Creates a checkout page where a person buys credits for the key's project. It is the same purchase as on the console's [Billing](/app/billing) page, so an agent or a terminal can ask for credit without sending anyone to the console. The body is optional.

| Field        | Type    | Default | Rules                                                    |
| ------------ | ------- | ------- | -------------------------------------------------------- |
| `amount_usd` | integer | 20      | The credit to buy, in whole US dollars, from 20 to 1000. |

```json title="POST /v1/credits/checkout"
{
  "amount_usd": 25
}
```

```bash
curl https://phonebox.dev/v1/credits/checkout \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 25}'
```

It answers `201 Created`:

```json title="Response: checkout"
{
  "url": "https://checkout.example.com/c/9f2b7c1e",
  "amount_usd": 25
}
```

| Field        | Type    | Meaning                                                                                                                                               |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`        | string  | The checkout page, on our payment provider's site. Give it to a person, who pays there. Tax is added at checkout, and a discount code can be entered. |
| `amount_usd` | integer | The credit the purchase adds, before tax and any discount.                                                                                            |

Nothing is charged until the person pays. The credit is added when the payment is confirmed, not when the page closes, so poll [the account](#get-the-account) until `balance_usd` shows it. A link that nobody pays costs nothing.

| Error                        | When                                                                                                                                                           |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 validation_failed`      | `amount_usd` isn't a whole number from 20 to 1000, or the body has another field.                                                                              |
| `403 insufficient_scope`     | The key is Read-only.                                                                                                                                          |
| `403 plan_required`          | The project is on the free week or has no plan, which can't buy credit (`details.feature` is `credit`). `details.upgrade_url` is where a person starts a plan. |
| `429 rate_limited`           | The project created 10 checkout links within the hour. `Retry-After` says when the next one can be created.                                                    |
| `503 billing_not_configured` | Payments aren't connected on this deployment.                                                                                                                  |

The [common errors](/docs/api-reference#common-errors) apply too.
