# Plan, billing & credits

> Your plan, invoices, credits and changing or pausing your subscription.

Every section below does the same job: in the dashboard (Guide), from your code (API) or through an AI assistant (MCP).

## Guide — In the dashboard

Source: /docs/account/billing

Billing shows your plan, invoices and payment method; Credit history shows every credit used and refunded. Only account owners can change billing.

<DemoFrame guide="invoice-cc" to="/billing" />

1. **Billing:** plan, invoices, invoice emails (with a CC).
2. **Credit history:** every charge and refund, by source.
3. **Change, pause or cancel** the plan from Billing (owners only). A cancelled plan stays usable until the end of the period you paid for, and you can restart it before then.

<DemoFrame guide="credit-history" to="/credit-history/{workspace}" />

### Every control on this screen [#every-control-on-this-screen]

Every button, field and switch, with what it does.

<ScreenControls screens={["billing", "billing-cancel", "owner-only-billing", "paused", "upgrade", "upgrade-payment", "upgrade-success", "credit-history", "payment-success", "payment-canceled", "paywall", "trial-extension", "churn-modal", "freemium-upgrade", "redeem-code", "coupon", "deal", "bonus"]} />


---

## API — From your code

Source: /docs/account/billing/api

Authenticated with `?privateKey=YOUR_KEY` (see [Authentication](/docs/authentication)). Plans, invoices and payment methods change only in the dashboard or through the [MCP tools](/docs/account/billing/mcp).

<Endpoints ops={["GET /v3/websites/{websiteId}/credit-history", "GET /v3/billing/invoices", "GET /v3/billing/auto-topup", "PUT /v3/billing/auto-topup", "GET /v3/credits/summary", "GET /v3/billing/domains", "GET /v3/billing/open-invoices"]} />

<ApiPlayground
  ops={["GET /v3/websites/{websiteId}/credit-history", "GET /v3/billing/invoices", "GET /v3/billing/auto-topup", "PUT /v3/billing/auto-topup", "GET /v3/credits/summary", "GET /v3/billing/domains", "GET /v3/billing/open-invoices"]}
  method="get"
  path="/v3/websites/{websiteId}/credit-history"
  tool="get_website_credit_history"
  args={`{
  "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9"
}`}
/>

### Use case: Alert before credits run out [#use-case-alert-before-credits-run-out]

Read the latest snapshot every morning: when `creditsRemaining` falls below a tenth of `creditsLimit`, post to your team chat.


---

## MCP — AI agents

Source: /docs/account/billing/mcp

Connect the [MCP server](/docs/mcp#quickstart), then just ask.

<Tools names={["get_account", "get_billing", "get_credit_history", "get_subscription", "preview_plan_change", "upgrade_plan", "downgrade_plan", "pause_subscription", "cancel_subscription", "reactivate_subscription", "get_website_credit_history", "list_invoices", "get_auto_topup", "set_auto_topup", "get_credit_summary", "list_billing_domains", "list_open_invoices"]} />

### Use case [#use-case]

> How many credits do I have left this month?

<McpToolCall name="get_account">

```json
{}
```

</McpToolCall>

> How many credits did we use last month, and on what?

<McpToolCall name="get_credit_summary">

```json
{ "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9", "cycle": 1 }
```

</McpToolCall>

The answer splits the cycle by source (website visitors, Prospector, enrichment…) and by day. `cycle` goes back up to 5 billing cycles.

> Where did my Prospector credits go this month?

<McpToolCall name="get_credit_history">

```json
{ "source": "PROSPECTOR", "operation": "CHARGE", "from": "2026-10-01" }
```

</McpToolCall>

> When is my next bill, and how much will it be?

<McpToolCall name="get_subscription">

```json
{}
```

</McpToolCall>

It answers the plan, leads per month, price, billing interval (monthly or yearly), next billing date and whether the plan is set to cancel, paused or downgrading. Without a paid subscription the price fields are empty.

> Is auto top-up on, and what's my monthly limit?

<McpToolCall name="get_auto_topup">

```json
{ "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9" }
```

</McpToolCall>

> Turn on auto top-up: 500 leads at a time, no more than $300 a month.

<McpToolCall name="set_auto_topup">

```json
{ "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9", "enabled": true, "packLeads": 500, "capUsd": 300 }
```

</McpToolCall>

> Which of our sending domains renew in the next two months, and for how much?

<McpToolCall name="list_billing_domains">

```json
{ "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9" }
```

</McpToolCall>

Each domain comes with its yearly price, renewal date and whether it renews automatically. Domains you brought yourself (`source: "imported"`) renew at your own registrar and are never billed here.

> Show my unpaid invoices and what my next bill will be.

<McpToolCall name="list_open_invoices">

```json
{ "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9" }
```

</McpToolCall>

> We don't need 5,000 leads a month any more. Move us to 3,000 from the next bill.

<McpToolCall name="downgrade_plan">

```json
{ "leads": 3000 }
```

</McpToolCall>

Nothing is charged or refunded now: the smaller plan starts at the next billing date, and your current credits stay until then. Plans go up to 1,000,000 leads a month; for more, contact us.

> Cancel my subscription. It's too expensive for us right now, the budget was cut.

<McpToolCall name="cancel_subscription">

```json
{ "reason": "expensive", "feedback": "Budget was cut this quarter." }
```

</McpToolCall>

Your assistant asks you to confirm before it cancels. The plan stays usable until the end of the billing period, and `reactivate_subscription` undoes the cancellation before then. If you would rather keep your data and pay less, ask it to pause (`pause_subscription`) or downgrade (`downgrade_plan`) instead.