Account
Read the project's balance, reservations, monthly spending, limits, phone counts, price and the countries phones can be created in, and create a checkout link for credits.
The account belongs to the project that the key selects. Pricing and credits explains balances, reservations and the spending limit.
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.
curl https://phonebox.dev/v1/account \
-H "Authorization: Bearer $PHONEBOX_API_KEY"{
"project": "Checkout QA",
"balance_usd": "21.400000",
"reserved_usd": "7.200000",
"spend_limit_usd": "100.000000",
"spent_this_month_usd": "4.120000",
"limits": { "phones": 10, "running": 2 },
"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" }
]
}| 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. What you can spend on a new session is balance_usd minus reserved_usd. |
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. The example shows three of them. A country is where the phone appears to be. |
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 apply.
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 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 | 10 | The credit to buy, in whole US dollars, from 10 to 1000. |
{
"amount_usd": 25
}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:
{
"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 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 10 to 1000, or the body has another field. |
403 insufficient_scope | The key is Read-only. |
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 apply too.