# Managing your subscription

**Your subscription is the Workspace's hlix plan and the payment method behind it.** Two actions cover almost everything: a **checkout**, which starts or changes a plan, and the **billing portal**, where the card, the plan and every past receipt already live.

Both belong to the Workspace, not to you personally. Leave the Workspace and the subscription stays.

## Prerequisites

- The `owner` or `admin` role. A `member` can read the plan but cannot open a checkout or the portal; a `client` collaborator cannot see billing at all.
- A Workspace with an owner. A Workspace with nobody to bill cannot subscribe.
- For the API examples: an API key and your Workspace ID.

## Start or change a plan

**The normal path.** Open [Settings → Billing](https://app.hlix.ai/settings/billing) and choose a plan card. You are sent to a hosted checkout, and back to the same page afterwards — the plan card refreshes on return.

Choosing **Free** is not a downgrade to nothing: it is how you put a card on file so work continues past the monthly credit, billed per use. See [Plans & pricing](/billing/plans/#what-free-actually-means).
  **Open a checkout for one of the four plans.**

```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": "pro", "successUrl": "https://app.hlix.ai/settings/billing?status=success"}'
```

Expected output:

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

`successUrl` is optional and must point at the hlix dashboard. Any other address is ignored and the default billing page is used, so a checkout can never redirect to an arbitrary site.

Opening a checkout is recorded in the [audit log](/security/audit-log/) with the plan and the checkout ID.
  ## Change the card, switch plan, or cancel

All three happen in the billing portal, and there is one way in.

**Use Manage billing** on [Settings → Billing](https://app.hlix.ai/settings/billing). It opens the billing portal for this Workspace, where you can update the payment method, change the plan, cancel, and read past invoices.
  **Mint a portal URL and send the person paying to it.**

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

Expected output:

```json
{"url": "https://…/portal/…"}
```

Opening the portal is recorded in the [audit log](/security/audit-log/), because the portal can cancel the plan and read every past invoice.
  **Cancelling takes effect at the end of the paid period, not immediately.** Reading the plan afterwards shows `cancelAtPeriodEnd: true` with the real `currentPeriodEnd` — the date access actually changes. Nothing is deleted at that point: the Workspace drops to the free tier and keeps every project it already has, even if that is more than the free ceiling allows. You simply cannot create new ones until you are under it again.

## Receipts and past charges

The last ten orders come back with the plan state, and the dashboard lists them under [Settings → Invoices](https://app.hlix.ai/settings/invoices).

```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, trimmed to the order history:

```json
{
  "orders": [
    {
      "id": "ord_…",
      "status": "paid",
      "amount": 50000,
      "currency": "EUR",
      "createdAt": "2026-08-01T04:11:29.000Z",
      "product": { "name": "Hlix-Pro" }
    }
  ]
}
```

`amount` is in minor units and is **what the card was charged**, tax included — so `50000` on a €500 plan is €500.00, not the amount net of tax.

<Aside type="note" title="This is not your customer's invoice">
These are receipts for what **you** pay hlix. The invoices you issue **your** customer are a different document in a different ledger, with their own numbering and their own PDF — see [Invoicing your client](/clients/invoicing/).
</Aside>

## If a subscription action fails

- **`403` with `{"error": "Admin or owner role required"}`** — a `member` tried to check out or open the portal. Reading the plan is fine for any agency role; committing the Workspace to a charge is not.
- **`403` with `{"error": "Billing is agency-only"}`** — you are acting as a client collaborator.
- **`400` on checkout** — the plan is not one of `free`, `basic`, `pro` or `ultra`.
- **`409` with `This workspace has no member to bill. Add an owner before subscribing.`** — the Workspace has no owner to put on the payment. Add one and retry.
- **`409` with `… is already the billing contact for another workspace, and no per-workspace variant of it can be formed. Set a different owner email for this workspace before subscribing.`** — the same address is already billing another Workspace. Give this Workspace a different owner email.
- **`503` with `{"error": "Billing is not configured for this deployment."}`** — billing is not available on this server. Contact hlix support.
- **`502` with `{"error": "Billing provider is unavailable. Try again shortly."}`** — payment processing did not respond. Your plan is unaffected; retry shortly.
- **You paid and the plan still reads as free.** Refresh the billing page — the plan is re-read after a checkout returns. If it persists, confirm the checkout was opened from this Workspace: a subscription is bound to the Workspace it was bought from, and one bought elsewhere is invisible here.

## Where to go next

| If you want to… | Read |
| --- | --- |
| Compare what each plan allows | [Plans & pricing](/billing/plans/) |
| See what you have spent this month | [Usage & runtime credit](/billing/usage-and-credit/) |
| Check who opened a checkout or the portal | [Audit log](/security/audit-log/) |
| Invoice your own customer | [Invoicing your client](/clients/invoicing/) |

## Next steps

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