# Manage billing and subscriptions

> Purchase a plan, review changes, manage invoices and recover failed payments.

Canonical page: https://anectico.com/docs/manage/billing/


Billing is a person's decision, so you do it in the Console: open **Billing and usage** (`/billing`)
and use the **Billing** card. See the [Console guide](/docs/manage/console#billing-and-usage). Confirm
the organization shown before continuing to payment; its subscription covers all its projects and
includes unlimited seats. Owners and administrators can manage billing. A project-specific API key
cannot manage organization billing.

## Ask your agent

> "Which plan are we on, and when does it renew?"

> "Show me what changing from Pro monthly to Pro annual would cost and when it takes effect. Do not
> confirm it."

| Job | MCP tool or action | CLI command |
| --- | --- | --- |
| List plans | `list_billing_plans` | `anectico billing plans` |
| Read the subscription | `get_billing_subscription` | `anectico billing status` |
| Preview a plan change | `preview_billing_change`, `get_billing_change_preview` | `anectico billing preview --plan <plan>`, `anectico billing preview-get <preview-id>` |
| Start checkout | `create_billing_checkout` | `anectico billing checkout --plan <plan> --idempotency-key <uuid>` |
| Confirm or clear a scheduled change | `confirm_billing_change`, `clear_billing_change` | `anectico billing confirm`, `anectico billing clear` |
| Open the customer portal | `create_billing_portal` | `anectico billing portal` |

Billing uses its own scopes, `billing:read` and `billing:write`; see
[API, CLI and agents](#api-cli-and-agents). The agent prepares the change and returns a link. The
person opens the link and completes payment, because payment is a person's decision.

## What your agent gets back

A plan or subscription read returns the plan, interval, period, scheduled changes and effective
dates. A preview returns the target allowances, recurring price, effective date, estimated
immediate charge and tax notice, and it expires after ten minutes. Checkout and portal calls return
a hosted session link once. These results have no proof page. The **Billing and usage** page in the
Console shows the same subscription.

## Plans and payment

| Plan | Monthly commitment | Annual commitment |
| --- | --- | --- |
| Free | $0 | — |
| Solo | $12 | — |
| Pro | $39 | $348 |
| Scale | $129 | $1,188 |

Prices are in USD, before applicable taxes. Polar provides secure checkout, collects payment,
and acts as merchant of record. The checkout shows the final tax and total. Annual prices are
charged annually; the monthly equivalents are $29 for Pro and $99 for Scale. Solo is monthly only.
Purchasing is available only where Billing is enabled. Sandbox payments are test transactions.

Choose a plan, confirm the organization and billing contact, then complete Polar checkout.
Returning to Anectico does not itself activate a plan: **Processing** means payment or access
verification is still underway. Refresh Billing before retrying. An unfinished checkout can be
reopened for the same plan while it remains valid. A failed or expired checkout grants no access.

Use **Manage payment, invoices and cancellation** to open the customer portal. It provides invoices,
payment-method updates, cancellation and cancellation reversal. Change plans inside Anectico so
that its timing and confirmation rules apply. Treat checkout and portal links as private: anyone
with a valid link may be able to use that session.

## Changing plans

Review the target allowances, recurring price, effective date, estimated immediate charge and
tax notice before confirming. Increasing the plan tier takes effect after the prorated payment
succeeds. The payment provider calculates the final amount. A failed upgrade leaves the existing
plan in place. Decreasing the tier, or changing only the billing interval, takes effect at renewal.
When both change, the tier determines whether the change is immediate or scheduled.

The Billing card shows scheduled changes and their effective dates. **Keep current plan** removes a
scheduled change. Cancellation preserves paid access until the paid period ends; use the portal
to reverse cancellation before then. To return to Free, cancel and let the paid period finish.
Refund requests are handled by support; a refund by itself does not cancel a subscription.

Lower limits do not erase this month's consumed usage. Lower retention can permanently expire
older history. A later upgrade cannot recover expired data. Replay retention and the product and
technical history policy are shown separately on the same Console page; operator-approved overrides
can affect the final allowances. Review [usage, model prices and decision scoring](/docs/manage/usage-and-ai-settings) for
those controls.

## Renewal, allowances and recovery

Billing renewal and usage allowance reset are separate dates. Usage allowances reset at **00:00 UTC
on the first day of each calendar month**, including on annual subscriptions. Changing plans never
resets consumed events or replays. There is no automatic overage billing.

A failed renewal retains paid access for seven days from the original payment failure, unless the
provider revokes access earlier. Repeated failed retries do not extend this deadline. Update the
payment method through the portal; confirmed recovery restores the paid plan. After grace expires,
Free limits and its retention rules apply. A temporary billing-provider outage preserves confirmed
access except for cancellation or grace deadlines that were already known.

An organization with a renewing subscription, remaining paid access or an unresolved checkout
cannot be deleted. Cancel first, wait until paid access ends and resolve pending payments.

## API, CLI and agents

Organization-wide API keys need explicit `billing:read` and/or `billing:write` scopes. The MCP
read gateway also needs `mcp:read`; the write gateway needs `mcp:write`. Hosted checkout confirmation
uses both billing scopes because it reads the price before requesting payment. Billing is not
included in the external OAuth delegation ceiling; use an explicitly scoped organization API key.

| Operation | REST | CLI | MCP action |
| --- | --- | --- | --- |
| List plans | `GET /api/v1/billing/plans` | `anectico billing plans` | `list_billing_plans` |
| Subscription | `GET /api/v1/billing/subscription` | `anectico billing status` | `get_billing_subscription` |
| Checkout | `POST /api/v1/billing/checkout` | `anectico billing checkout --plan solo/month --idempotency-key UUID` | `create_billing_checkout` |
| Portal | `POST /api/v1/billing/portal` | `anectico billing portal` | `create_billing_portal` |
| Preview change | `POST /api/v1/billing/changes/preview` | `anectico billing preview --plan pro/year` | `preview_billing_change` |
| Read preview | `GET /api/v1/billing/changes/{previewId}` | `anectico billing preview-get UUID` | `get_billing_change_preview` |
| Confirm change | `POST /api/v1/billing/changes/confirm` | `anectico billing confirm --preview-id UUID --idempotency-key UUID` | `confirm_billing_change` |
| Clear change | `POST /api/v1/billing/changes/clear` | `anectico billing clear --expected-revision REVISION --idempotency-key UUID` | `clear_billing_change` |

Every billing write through MCP or CLI first prints the complete current subscription and
server proposal, its required scopes and consequences. All need `mcp:write`, `billing:read`
and `billing:write`. Repeat identical arguments with `--confirm-token` only after approval.
This includes portal creation and storing a plan-change preview. `billing plans` accepts
`--limit` and `--cursor`; the MCP action accepts `limit` and `cursor`. Each is a page; follow
`next_cursor` until `has_more` is false before treating it as the complete price catalogue.

Plan-change preparation also requires a stable UUID retry key and fixed RFC3339 `priced_at` /
`--priced-at` within the last ten minutes. CLI prints these if omitted on preparation;
preserve them on confirmation. Preparation is read-only and shows the complete estimate.
Confirming preparation stores that immutable estimate without buying the change. Applying
it is a separate `confirm_billing_change` preview/confirmation. Portal creation also takes a
stable UUID key. Identical creation retries return the first operation and never a new session. Reuse an idempotency UUID for identical retries; never change it to work
around an uncertain payment. A confirmed failure requires a new request. A preview expires after
ten minutes and must be recreated if subscription state changes. Hosted session links are returned
once in response text and never in receipts, activity or cached retries. An identical retry
returns metadata only. If a URL was lost, inspect operation/subscription state before requesting
a separately approved new session.

### Reading refused CLI actions

The governed `billing checkout`, `portal`, `preview`, `confirm` and `clear` commands print the
returned receipt to stdout even when the MCP tool refuses the action. Use `-o json` for the
complete JSON receipt, including `content[].text` and any `structuredContent`; `-o table`
prints the server preview or receipt text verbatim. A refusal still exits with code **1** and writes
a separate diagnostic to stderr. Receiving a receipt does not mean the action succeeded.

Keep stdout and stderr separate when capturing these commands. Read the receipt's reason and
recovery guidance before deciding whether to retry; the CLI does not automatically retry the
mutation. HTTP failures or invalid MCP responses may have no validated receipt, so stdout can
be empty in those cases. Always check the exit status and stderr as well.

The checkout proposal includes the billing contact it will save and the organization deletion
fence it will set. The current plan stays in place until payment is verified. The subscription
read states whether deletion is currently blocked and gives the pending checkout identifier, plan,
expiry and submission time. A submitted checkout retry leaves its contact and subscription unchanged
and returns metadata only; the person can reopen a still-valid checkout in Billing. An unsubmitted
attempt can finish preparation after a new server preview, which shows the contact it will save.
Stored billing contact and workspace text remain marked as untrusted data in MCP reads.