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

# List plans

> List both credit ladders: monthly plans and one-time packs.

Lists every plan Leadity sells, both ladders: monthly plans, whose credits last 30 days from each payment, and one-time packs, whose credits never expire. Pass a plan's sku to create_checkout to get a link a person can pay at. An account with a monthly plan can also add credits to it with create_top_up_checkout, in the amounts topUp names.

`GET https://api.leadity.io/v1/billing/plans`

- Scope: `read`
- Spends credits: no
- MCP tool: `list_plans`

## Headers

- `Authorization`, string, required. Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

## Example request

```bash cURL
curl "https://api.leadity.io/v1/billing/plans" \
  -H "Authorization: Bearer $LEADITY_API_KEY"
```

```javascript Node.js
const response = await fetch("https://api.leadity.io/v1/billing/plans", {
  headers: {
    Authorization: `Bearer ${process.env.LEADITY_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
```

```python Python
import os

import requests

response = requests.get(
    "https://api.leadity.io/v1/billing/plans",
    headers={
        "Authorization": f"Bearer {os.environ['LEADITY_API_KEY']}",
    },
)

print(response.json())
```

## Response

- `monthly`, object[], required. The monthly ladder, smallest first.
  - `sku`, string, required. The plan's sku, which create_checkout takes: monthly_pack_<credits> or one_time_pack_<credits>.
  - `cadence`, string, required. monthly renews every 30 days and its credits expire 30 days after each payment; one_time is bought once and never expires. One of: `monthly`, `one_time`.
  - `credits`, integer, required. Credits the plan grants per payment.
  - `priceCents`, integer, required. The price in US cents.
  - `priceLabel`, string, required. The price as printed, e.g. $19.
  - `discountPct`, number, required. The bulk discount against the smallest rung of the same ladder, in percent.
  - `monthlySavingPct`, number, required. On a one-time rung, what subscribing at the same size saves, in percent. 0 on a monthly rung.
  - `firstBonus`, integer, required. Extra credits on the account's first purchase of this rung. 0 when none is offered.
- `oneTime`, object[], required. The one-time ladder, smallest first.
  - `sku`, string, required. The plan's sku, which create_checkout takes: monthly_pack_<credits> or one_time_pack_<credits>.
  - `cadence`, string, required. monthly renews every 30 days and its credits expire 30 days after each payment; one_time is bought once and never expires. One of: `monthly`, `one_time`.
  - `credits`, integer, required. Credits the plan grants per payment.
  - `priceCents`, integer, required. The price in US cents.
  - `priceLabel`, string, required. The price as printed, e.g. $19.
  - `discountPct`, number, required. The bulk discount against the smallest rung of the same ladder, in percent.
  - `monthlySavingPct`, number, required. On a one-time rung, what subscribing at the same size saves, in percent. 0 on a monthly rung.
  - `firstBonus`, integer, required. Extra credits on the account's first purchase of this rung. 0 when none is offered.
- `topUp`, object, required. The amounts create_top_up_checkout takes, for an account with a monthly plan.
  - `min`, integer, required. The smallest top-up, in credits.
  - `max`, integer, required. The largest top-up one purchase may be, in credits.
  - `step`, integer, required. Every top-up is a whole multiple of this many credits.

## Example response

```json 200
{
  "monthly": [
    {
      "sku": "monthly_pack_2000",
      "cadence": "monthly",
      "credits": 2000,
      "priceCents": 4900,
      "priceLabel": "$49",
      "discountPct": 36,
      "monthlySavingPct": 0,
      "firstBonus": 0
    }
  ],
  "oneTime": [
    {
      "sku": "one_time_pack_2000",
      "cadence": "one_time",
      "credits": 2000,
      "priceCents": 6900,
      "priceLabel": "$69",
      "discountPct": 41,
      "monthlySavingPct": 29,
      "firstBonus": 0
    }
  ],
  "topUp": {
    "min": 500,
    "max": 50000,
    "step": 500
  }
}
```

## Errors

Every refusal answers `{ error, message }` with the status below. The full list is on the [Errors](https://docs.leadity.io/errors) page.

| Code | Status | Meaning | Extra fields |
| --- | --- | --- | --- |
| `unauthorized` | 401 | The API key is missing, malformed, revoked or expired. | - |
| `wrong_key_kind` | 401 | This key opens the other surface: an API key works on the HTTP API, an MCP key on the MCP server. | - |
| `account_suspended` | 403 | The account is suspended. | - |
| `email_not_verified` | 403 | The account's email address is not verified yet. | - |
| `rate_limited` | 429 | Too many requests. Wait for the Retry-After seconds and try again. | `retryAfterSeconds`: The seconds to wait, the same number as the Retry-After header. |
| `try_again` | 503 | Leadity could not answer just now. Retry in a moment, with the same Idempotency-Key on a spending call. | `retryAfterSeconds`: When a request with this Idempotency-Key is still being processed: the seconds to wait before retrying with the same key, as the Retry-After header says. |
| `internal_error` | 500 | Something failed on our side. Nothing was charged twice. | `body`: On the MCP server, when Leadity answered in a shape the tool does not publish: that answer as it came. |