# Plans & pricing

**A plan is what your Workspace pays hlix.** It sets one ceiling — how much agent runtime you may spend before the platform stops — and, on the free tier, how many active projects you may hold. Everything else in hlix is on every plan.

This page is your **own** hlix bill. What you invoice *your* customer for delivered work is a separate ledger — see [Invoicing your client](/clients/invoicing/).

## Prerequisites

- A Workspace. Signing up creates one and puts you on Free.
- The `owner` or `admin` role to change a plan. A `member` can read the plan but not buy one; a `client` collaborator cannot see it at all. See [Roles & permissions](/security/roles-and-permissions/).
- For the API examples: an API key and your Workspace ID from [Developer tools → API keys](https://app.hlix.ai/developer-tools/api-keys).

## The plans

| Plan | Price | Runtime allowance | Projects |
| --- | --- | --- | --- |
| **Free** | €0/mo | $5.00 of metered agent spend every month, then pay as you go | 10 active projects |
| **Basic** | €99/mo | €99 hard cap — the run stops rather than costing more | Unlimited |
| **Pro** | €500/mo | Metered beyond the plan | Unlimited |
| **Ultra** | €2000/mo | Metered beyond the plan | Unlimited |

**Basic is the only tier with a hard plan cap.** On Pro and Ultra, usage past the plan is metered rather than refused — the run continues and the overage is billed. On Basic it stops, which is the point of the tier: a fixed monthly maximum you cannot exceed by accident.

Every plan, Free included, also honours a **spend cap you set yourself**, and the tighter of the two ceilings is the one that fires. See [Usage & runtime credit](/billing/usage-and-credit/).

**Two currencies, and neither is converted:** Plans are priced and charged in **EUR**. The free credit is a **USD** figure because agent cost is measured in dollars of model spend. Neither is converted into the other, so neither figure changes with the exchange rate.

## What "Free" actually means

Free is a real plan, not a trial, and it has two phases.

**Phase one — no card on file.** You get $5.00 of metered agent spend per calendar month. There is no rollover: an unused month is not credit, and the grant resets at 00:00 UTC on the 1st. When the $5.00 is gone, dispatching new work is refused until the reset.

**Phase two — a card on file.** Checking out the Free plan puts a payment method on the Workspace and carries the same $5.00 as a monthly credit, plus a metered price beyond it. Nothing about the tier changes except that running past the credit is billed instead of refused — this is pay as you go, on the same plan.

So "add a card" and "upgrade" are different actions. If you are stopped by the credit and do not want a €99 plan, the answer is the Free checkout, not Basic.

The **10 active projects** ceiling applies to the free tier in *both* phases — adding a card does not lift it. It counts non-archived projects and is checked when you create one, so a Workspace that drops off a paid plan keeps every project it already built. Archiving a project frees a slot.

## Change your plan

**Use this unless you are automating.** Open [Settings → Billing](https://app.hlix.ai/settings/billing). The current plan is shown at the top; the four plan cards below it open a checkout. After payment you are returned to the same page and the plan card updates.

To change or cancel an existing plan, use **Manage billing** on the same page — it opens the billing portal, where the card, the plan and past invoices all live.
  **Read the plan, then open a checkout.** Both operations are in the published contract.

```bash
curl -sS "$HLIX_BASE_URL/v1/api/billing" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"
```

Expected output — the live plan, its meters, recent orders, and the entitlement verdict:

```json
{
  "configured": true,
  "activeSubscriptions": [
    {
      "id": "sub_…",
      "status": "active",
      "product": { "name": "Hlix-Pro" },
      "amount": 50000,
      "currency": "EUR",
      "recurringInterval": "month",
      "currentPeriodEnd": "2026-09-28T00:00:00.000Z",
      "cancelAtPeriodEnd": false
    }
  ],
  "activeMeters": [
    { "id": "…", "name": "agent_run_cost", "consumedUnits": 128400, "creditedUnits": 0, "balance": -128400 }
  ],
  "orders": [],
  "entitlement": { "kind": "subscription", "subscription": { "planSlug": "pro", "…": "…" } }
}
```

`amount` is in the currency's minor units, so `50000` is €500.00.

```bash
curl -sS -X POST "$HLIX_BASE_URL/v1/api/billing/checkout" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H 'content-type: application/json' \
  -d '{"plan": "basic"}'
```

Expected output:

```json
{"url": "https://…/checkout/…", "checkoutId": "…"}
```

Send the person paying to `url`. The accepted plan values are `free`, `basic`, `pro` and `ultra` — the same four the dashboard offers.
  ## Who is billed

**The Workspace is the customer, not the person who pressed the button.** A subscription belongs to the Workspace, so every member's runs draw on the same plan and the same cap, and a person who leaves takes nothing with them. Two Workspaces of the same owner are two customers with two bills.

## If a plan action fails

- **`402` with `Your free credit is used for this month (5.00 of 5.00). Add a payment method in Settings → Billing to continue pay-as-you-go, or wait for the reset on 2026-09-01.`** — the free tier's monthly grant is spent. Check out the Free plan to continue pay as you go, or wait for the reset date the message names.
- **`402` with `Plan cap reached on Hlix-Basic. Upgrade to Hlix-Pro or Hlix-Ultra to continue.`** — Basic's hard cap. It is the only plan that refuses rather than meters.
- **`402` with `Monthly usage limit reached (25.00 of your workspace's own cap). Raise or remove it in Settings → Usage to continue.`** — not the plan; the cap **you** set. Raise or clear it in [Settings → Usage](https://app.hlix.ai/settings/usage).
- **`402` with `The free plan allows 10 active projects, and this workspace already has 10. Upgrade in Settings → Billing, or archive a project to make room.`** — the project ceiling, checked when you create a project. Archive one or move to a paid plan.
- **`403` with `{"error": "Admin or owner role required"}`** — a `member` tried to open a checkout or the portal. Reading the plan is open to every agency role; committing the Workspace to a charge is not.
- **`403` with `{"error": "Billing is agency-only"}`** — you are acting as a client collaborator. There is no client-facing view of the agency's own plan.
- **`400` with `{"error": …}` on checkout** — the plan name is not one of `free`, `basic`, `pro` or `ultra`.
- **`503` with `{"error": "Billing is not configured for this deployment."}`** — billing is not available on this server, and `GET /v1/api/billing` reports `configured: false`. Contact hlix support.
- **`502` with `{"error": "Billing provider is unavailable. Try again shortly."}`** — payment processing did not respond. Your plan is unaffected; retry shortly.

## Where to go next

| If you want to… | Read |
| --- | --- |
| See what you have spent and set your own ceiling | [Usage & runtime credit](/billing/usage-and-credit/) |
| Change the card, cancel, or find a receipt | [Managing your subscription](/billing/subscription/) |
| Bill your own customer for delivered work | [Invoicing your client](/clients/invoicing/) |
| Know who may press which button | [Roles & permissions](/security/roles-and-permissions/) |

## Next steps

[Usage & runtime credit](/billing/usage-and-credit/)
  [Managing your subscription](/billing/subscription/)
  [Invoicing your client](/clients/invoicing/)
  [Roles & permissions](/security/roles-and-permissions/)