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

# Quota & billing

> How AcreLens charges, how free trial reports work, and how to control spend.

## Plans & billing models

**New accounts are created on a subscription model — the Free plan**, which includes **3 reports per month**. Reports run against this monthly allotment; when it's exhausted, `POST /v1/analyze` returns `429 quota_exceeded` until your period resets.

```json theme={null}
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly report limit reached (3/3). Upgrade your plan or wait until next month.",
    "request_id": "req_01HY2Z...",
    "retriable": false,
    "docs_url": "https://docs.acrelens.com/errors/quota_exceeded"
  }
}
```

| Plan | Price | Reports / month | Saved parcels | API access |
| - | - | - | - | - |
| **Free** | \$0 | 3 | 5 | — |
| **Starter** | \$19/mo | 25 | 25 | — |
| **Pro** | \$49/mo | 150 | 250 | ✓ |
| **Enterprise** | [Contact us](mailto:support@acrelens.com) | 5,000 | 5,000 | ✓ |

REST API and MCP access are **included on Pro and above**. Enterprise is custom-priced for high-volume teams — [contact us](mailto:support@acrelens.com) for a quote.

**Legacy pay-as-you-go (PAYG).** Existing PAYG customers keep a prepaid balance, with each report deducting **\$3.99**. New accounts are not created in PAYG mode. The rest of this page describes the legacy PAYG model.

## Per-report cost (legacy PAYG)

| Item | Price |
| - | - |
| Single report | **\$3.99** |
| Batch report (per item) | **\$3.99** |
| Quick score (via [MCP](/guides/mcp-server)) | **\$1.00** |
| State profile (via MCP) | free |
| Solar potential (via MCP) | free |

Webhook delivery and the dashboard are all included — no separate charges.

## Free trial reports (legacy PAYG)

Legacy PAYG accounts that completed signup (and added a card) were granted **4 free reports**. Free reports:

* Apply automatically on the first 4 successful `POST /v1/analyze` requests
* Decrement before any balance is charged
* Show up in the dashboard as `Free reports remaining`
* Don't expire — they sit on your account until used

Failed reports don't consume free reports.

## Balance & top-ups

Your current balance lives at the top of your dashboard:

```
$15.00  prepaid balance
```

To add funds:

* **Manual top-up.** Click **Add funds** in the dashboard. Pick a quick amount ($5, $10, $25, $50, $100) or enter a custom amount. Minimum top-up is **$5.00\*\*, maximum is **\$10,000.00** per transaction. Stripe Checkout handles the payment.
* **Auto-recharge.** In the dashboard under **Billing**, configure a threshold (e.g. when balance \< $5) and a recharge amount (e.g. add $20). When balance falls below the threshold, AcreLens charges your saved card and tops up automatically. Off-session — no Checkout flow on each top-up.

When an auto-recharge charge fails (declined card, expired card, insufficient funds), AcreLens logs the failure and emails you to update your card. It does not change your account status — your balance simply isn't topped up, so once it falls below `$3.99` with no free reports left, requests return `402 insufficient_balance` until you add funds.

## Spend caps

To protect against runaway costs (a buggy loop, a leaked key, a spike in your own traffic), you can set:

* **Daily cap** — max spend per UTC day
* **Monthly cap** — max spend per calendar month

Configure both in the dashboard under **Billing**. When a request would exceed a cap, the API returns `402` with code `DAILY_CAP_EXCEEDED` or `MONTHLY_CAP_EXCEEDED`:

```json theme={null}
{
  "error": {
    "code": "DAILY_CAP_EXCEEDED",
    "message": "Daily spend cap reached. Try again tomorrow.",
    "request_id": "req_01HY2Z...",
    "retriable": false,
    "docs_url": "https://docs.acrelens.com/errors/DAILY_CAP_EXCEEDED"
  }
}
```

Caps reset automatically — daily at 00:00 UTC, monthly on the first.

## Insufficient balance

If your balance is below `$3.99` *and* you have no free reports left, the API returns `402` with code `insufficient_balance`. Top up and retry — AcreLens does not auto-queue requests.

```json theme={null}
{
  "error": {
    "code": "insufficient_balance",
    "message": "Balance too low to complete this report.",
    "request_id": "req_01HY2Z...",
    "retriable": false,
    "docs_url": "https://docs.acrelens.com/errors/insufficient_balance"
  }
}
```

## Refunds

Failed reports don't auto-refund — see [report lifecycle](/concepts/report-lifecycle#what-you-get-back-when-it-fails). If you have a legitimate billing dispute (duplicate charges, repeated failures on a valid address, system outages), email [support@acrelens.com](mailto:support@acrelens.com) with the affected `request_id` or `report_id` values. Manual credits land in your balance as `REFUND` transactions.

## Programmatic balance & usage

You can pull the same numbers the dashboard shows:

| Endpoint | Returns |
| - | - |
| `GET /v1/balance` | Current balance, free reports remaining, last 10 transactions |
| `GET /v1/usage` | Same plus period start/end and rate per report |

See the [endpoint reference](/reference/endpoint-reference) for full response shapes.

## Enterprise

Volume discounts, custom contracts, and higher rate limits are available. Reach out at [support@acrelens.com](mailto:support@acrelens.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.