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

Dashboard

The normal path. Open 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.

API

Open a checkout for one of the four plans.

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:

{"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 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.

Dashboard

Use Manage billing on 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.

API

Mint a portal URL and send the person paying to it.

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:

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

Opening the portal is recorded in the 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.

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:

{
  "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.

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.

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
See what you have spent this month	Usage & runtime credit
Check who opened a checkout or the portal	Audit log
Invoice your own customer	Invoicing your client

Next steps

Plans & pricingThe four plans, the free credit, and the one tier with a hard cap.

Usage & runtime creditWhat is metered and the cap you set yourself.

Invoicing your clientThe other ledger — what you charge your customer.

Roles & permissionsWho may buy, who may only read.