> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing: plans, credits and how they expire

> How plans and credits work in Hamsa: batches that last twelve months, the order they're spent, top-ups, monthly and yearly billing, Enterprise, and who can pay.

Everything you do in Hamsa is paid for in credits: calls with your agents, and speech to text, text to speech and the other Media services. Your plan adds credits every month, and you can buy more. Each batch of credits lasts twelve months from the day it arrives, and the batch that expires soonest is spent first.

Billing is the same in Hamsa Agents and Hamsa Media. It's one account, one plan and one balance for both apps.

## Before you start

* Open Billing from the account menu: click your avatar at the top right, then **Billing**. Billing isn't available on on-premises installations.
* To see the plan and credits, you need **View** on **Billing**. The Owner has it, and can give it to any member.
* To pay, change the plan, buy credits or open **Manage subscription**, you need **Edit** on **Billing**. Only the Owner has it, and it can't be given to anyone else. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

## Credits belong to the owner's account

Credits, the plan, the concurrency limit (how many calls can run at once) and knowledge base storage belong to a person's account, not to a project. Every project that person owns uses the same balance and shares the same limits, and so does every member working in those projects.

* If you own three projects, a call in any of them spends credits from your one balance, and their knowledge base items all count towards your one storage limit.
* If someone invites you to their project, your work there spends their credits, and their Billing page is the one that applies.
* Deleting a project doesn't change your credits or your plan.

## How credits work

| Rule | What it means |
| - | - |
| **Twelve months to use them** | Every batch of credits, from your plan, a top-up or your sign-up gift, stays usable for twelve months from the day it arrives. Whatever is left after that expires. Credits added on 10 March 2026 can be used until 10 March 2027. |
| **Soonest to expire, first to go** | When you make a call or use any service, credits come from the batch that expires soonest, so as little as possible goes unused. |
| **Unused credits carry over** | When your plan renews, what you didn't use stays. The new month's credits are added on top, and each batch keeps its own expiry date. |
| **Original balance never expires** | Credits in your **Original balance** never expire. They are spent last, after every batch that does. |
| **Enterprise credits** | Enterprise credits don't expire. |

For example, on a monthly plan, month 1's credits can be used until the end of month 12, and month 2's until the end of month 13. On a yearly plan, credits still arrive every month, and each month's batch lasts twelve months.

When a batch expires, your balance can take up to an hour to show it. Expired credits can't be used in the meantime.

Each service uses a different number of credits. The [Plans tab](#plans) shows what each plan includes.

## See your credits

Your credits show in three places, for members with **View** on **Billing**:

* **The ring around your avatar** at the top of the page. Hover it to see "remaining / total credits remaining". The ring turns red when less than 10% is left.
* **The account menu**, which shows your plan and **Credits remaining**.
* **Home**, which shows how many credits are left of your total.

Click any of them to open **Your credits**: every batch you have, in the order it will be spent, with the rules above and a link to **Plans and billing**.

![The Your credits dialog: Plan credits marked Used next with an expiry date, a Top-up, and the Original balance with No expiry, then How credits work](https://mintcdn.com/hamsa-452fa79a/Xv7E3FdzqmP9jZy0/images/overview/billing/your-credits-dialog-light.webp?fit=max\&auto=format\&n=Xv7E3FdzqmP9jZy0\&q=85\&s=f352f2d6d50ffe231b025d6781f8aa36)

### The Billing page

The **Overview** tab opens first. It has:

* **Current plan**: the plan's name, price, whether it is **Billed monthly** or **Billed yearly**, its credits a month, and how many days until it resets.
* **Credits left**: your balance against your total, and when the next batch expires (for example "1,200 credits expire in 5 days") or **None of your credits expire**. A date within 7 days turns amber.
* **Your credits**: the full list of batches, in the order they are spent.
* **How credits work**: the rules, with an example.

![The Billing page on the Overview tab: Current plan, Credits left and the start of Your credits](https://mintcdn.com/hamsa-452fa79a/Xv7E3FdzqmP9jZy0/images/overview/billing/billing-overview-light.webp?fit=max\&auto=format\&n=Xv7E3FdzqmP9jZy0\&q=85\&s=d606584dd02e8d5b908d222aced974ab)

Each batch in **Your credits** shows its kind, "remaining of total left", and **Expires** with a date, or **No expiry**. The first one says **Used next**.

| Kind | Where it came from |
| - | - |
| **Plan credits** | Your monthly plan. |
| **Yearly plan monthly refill** | Your yearly plan's credits for one month. |
| **Top-up** | Credits you bought. |
| **Promotional credits** | Your sign-up gift, and other credits Hamsa gave you. |
| **Original balance** | Credits that never expire, spent last. |
| **Other credits** | Anything else. |

![Your credits on the Billing page, every batch in the order it is spent, and How credits work below](https://mintcdn.com/hamsa-452fa79a/Xv7E3FdzqmP9jZy0/images/overview/billing/billing-your-credits-light.webp?fit=max\&auto=format\&n=Xv7E3FdzqmP9jZy0\&q=85\&s=427ea7f61b4e6da019bbacbb020a0618)

## Plans

The **Plans** tab lists the plans you can move to: **Starter**, **Creator** (marked **Most popular**), **Pro**, **Business** and **Enterprise**. Use the **Monthly** and **Yearly** switch at the top to compare prices. Yearly shows how much you save.

Each plan card shows the plan's credits, the minutes it gives for voice agents, speech to text and text to speech, the number of concurrent calls, and the knowledge base storage. Open **Compare all features** for the full table, and the questions at the bottom for common answers.

![The Plans tab with the Monthly and Yearly switch and the Starter, Creator, Pro, Business and Enterprise cards](https://mintcdn.com/hamsa-452fa79a/Xv7E3FdzqmP9jZy0/images/overview/billing/billing-plans-light.webp?fit=max\&auto=format\&n=Xv7E3FdzqmP9jZy0\&q=85\&s=d8849dbc717b3551b2d23393e3c566d7)

### The Free plan

Every new account gets free credits to try Hamsa, usable for twelve months. They are granted once, at sign-up. The Free plan never renews and you are never charged. If you're on it, a banner at the top of the Plans tab says so.

## Subscribe or move to a higher plan

**1. Open the Plans tab**

In **Billing**, click **Plans**, or click **Change plan** (or **Upgrade** on the Free plan) on the Overview tab.

**2. Pick monthly or yearly**

Choose **Monthly** or **Yearly** at the top.

**3. Choose the plan**

Click **Upgrade plan** on the plan you want. Payment opens on a secure Stripe page.

**4. Pay**

Complete the payment. You come back to Billing with a confirmation, for example "Subscribed to the Pro plan (Monthly)."

If you cancel on the payment page, Billing shows "Checkout was canceled. You can try again anytime."

Only the Owner sees the buttons on the plan cards. If a previous payment was left incomplete, finish or cancel it first.

## Monthly or yearly billing

* **Monthly to yearly**: switch any time. On your current plan's card, with **Yearly** selected, click **Switch to yearly**.
* **Yearly to monthly**: you can't switch your plan to monthly directly. Its card reads **Can't downgrade to monthly**. Cancel your yearly subscription in **Manage subscription**, wait for the year to end, then subscribe to a monthly plan. A higher plan's monthly price is the exception: it counts as an upgrade, so you can pick it on the Plans tab straight away.

On a yearly plan you pay for the year up front, and the credits arrive month by month. Each month's batch lasts twelve months.

### Moving to a lower plan

The Plans tab offers only moves up: lower plans have no button. To move down, cancel your subscription in **Manage subscription**, wait for the current period to end, then subscribe to the plan you want.

## Buy more credits

On plans that offer a top-up, the Owner can buy extra credits at any time.

**1. Open Billing**

Open **Billing** on the Overview tab.

**2. Buy**

On the **Credits left** card, click the buy button, for example **Buy 1,000 more credits**. The number depends on your plan. Payment opens on a secure Stripe page.

When you come back, Billing shows "Credits purchased." Top-up credits last twelve months from the day you buy them, like plan credits, so buy them when you expect to use them within that time.

If your plan has no top-up, the button doesn't appear and the **Insufficient credits** dialog says "Credit top-up is not available for your current plan."

## Manage your subscription, card and invoices

**Manage subscription**, on the **Current plan** card, opens Stripe's billing portal. Change your card, see and download invoices, and cancel your subscription there. There is no invoice list inside Hamsa. Only the Owner sees this button.

## When you run out of credits

* **A call in progress is never cut short.** It finishes, and your balance can go below zero.
* **Nothing new can start** until you add credits. New credits cover the amount below zero first.
* **In the app**, the **Insufficient credits** dialog opens with **Upgrade plan** and **Buy credits**. Members who can't pay see "You do not have permission to change the plan or buy credits. Ask a project owner to do it." On the highest plan, it says "You're already on the highest available plan."
* **Through the API**, requests that need credits are refused with `402` and "Balance is insufficient, please renew or upgrade your plan!".

The account owner gets a notification and an email when 90%, 95% and 100% of the credits are used, at most once a day for each. See [Notification settings](https://docs.tryhamsa.com/overview/account-settings/notification-settings.md).

## Concurrent calls

Your plan sets how many voice agent calls can run at the same time. The limit is for the owner's whole account: calls in all of the owner's projects count toward it. Calls over the limit are turned away, and the **Calls and integrations** notifications tell you when that happens.

## Enterprise

An Enterprise agreement is set up with the Hamsa team for your organization. To ask about one, the Owner opens the Plans tab and clicks **Contact sales** on the **Enterprise** card.

With an agreement in place:

* **Current plan** shows **Enterprise** with your monthly payment, monthly credits and monthly minutes.
* The second tab is **Agreement** instead of Plans.
* Enterprise credits don't expire.

The wording on the card differs between the apps:

| | Hamsa Agents | Hamsa Media |
| - | - | - |
| Under the title | "Your organization has a custom enterprise agreement" | "Custom billing and support for your organization" |
| Buttons | **Payment link** and **Contact support** | **Open payment link** and **Contact the enterprise team** |

To change your agreement, its limits or the billing details, or to leave Enterprise, contact support.

## In Hamsa Media

Billing in Hamsa Media is the same page, with the same plan, the same credits and the same expiry: every batch lasts twelve months from the day it arrives, whichever app you use it in. Open it the same way, from your avatar and then **Billing**. The credit ring, **Your credits** and the credits on Home work as described above.

![The Billing page in Hamsa Media on Overview: Current plan billed yearly, Credits left with the next batch to expire, and Your credits with the yearly refill marked Used next](https://mintcdn.com/hamsa-452fa79a/Xv7E3FdzqmP9jZy0/images/overview/billing/media-billing-overview-light.webp?fit=max\&auto=format\&n=Xv7E3FdzqmP9jZy0\&q=85\&s=3acf78f1e59f01c78c2f8bcc0a037602)

![Hamsa Media's Your credits dialog: two yearly plan refills, a top-up and the Original balance with No expiry, then How credits work](https://mintcdn.com/hamsa-452fa79a/Xv7E3FdzqmP9jZy0/images/overview/billing/media-your-credits-dialog-light.webp?fit=max\&auto=format\&n=Xv7E3FdzqmP9jZy0\&q=85\&s=d4e8db083ff855a3f4799378e15f1190)

What's different in Hamsa Media:

* **Credits pay for Media's services.** Speech to text, text to speech, voice overs, AI docs and the other services spend credits from the project owner's balance, the same one that pays for calls. When there aren't enough, the **Insufficient credits** dialog opens, as described in [When you run out of credits](#when-you-run-out-of-credits).
* **Some features need a minimum plan.** The [web reader](https://docs.tryhamsa.com/media/web-reader/overview.md) needs **Pro** or higher. Opening it on a lower plan offers an upgrade, which opens the Plans tab with only the plans that include it.
* **The Plans tab's questions in Hamsa Media don't cover credit expiry.** The rules on this page apply in both apps: unused credits carry over, and each batch expires twelve months after it arrives.
* **Without View on Billing**, the page says "You don't have access to this feature." instead of the Agents message.

![The Plans tab in Hamsa Media: the Monthly and Yearly switch, the Starter, Creator and Pro cards, and the current Business plan](https://mintcdn.com/hamsa-452fa79a/Xv7E3FdzqmP9jZy0/images/overview/billing/media-billing-plans-light.webp?fit=max\&auto=format\&n=Xv7E3FdzqmP9jZy0\&q=85\&s=137d12f8e7fe09944408954d11046806)

## Good to know

* Receipts and other account emails are always sent, whatever your notification settings.
* On the Free plan, the **Current plan** card says "Your sign-up credits. They don't renew."
* When a subscription ends, the **Current plan** card says **Your plan has ended**. Credits you already have keep their own expiry dates.

## Related

> [card] [Projects](https://docs.tryhamsa.com/overview/projects/overview.md)
>
> What belongs to a project and what belongs to your account.

> [card] [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md)
>
> Who can see billing and who can pay.

> [card] [Notification settings](https://docs.tryhamsa.com/overview/account-settings/notification-settings.md)
>
> Low-credit and expiry notices.

> [card] [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md)
>
> Keys your server uses, and the errors they get.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.