> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# Billing: start the plan that puts automations live

> Build and test automations for free, then start the production plan to publish them and send broadcasts, and read the invoices it brings.

Studio Nord, an agency in Paris, builds the repair shop's automation that tells Camille when her bike is ready. While it builds, everything is free, from drafts to [tests](https://heythere.io/docs/concepts/tests) on a member's own phone. The day the shop wants Camille to get the message for real, Studio Nord starts the production plan of its [organization](https://heythere.io/docs/concepts/organizations-and-workspaces).

## What does the plan allow?

Publishing an automation, sending a [broadcast](https://heythere.io/docs/concepts/broadcasts), and sending a [verification](https://heythere.io/docs/concepts/verifications) code. Each is refused until the plan is live. Every other action stays free.

Heythere can also grant a complimentary plan, shown as `complimentary`: live with no card or invoice until Heythere ends it.

## How does an organization start the plan?

An administrator, or an agent for them, takes three steps:

1. `setOrganizationBillingDetails` sets who the invoices are addressed to, such as Studio Nord SAS, 12 rue Oberkampf, 75011 Paris, with its VAT number. Heythere saves a VAT number once VIES, or HMRC in the United Kingdom, confirms it. The country sets the currency, euros in Europe and US dollars elsewhere, and it stays fixed once the plan first starts.
2. The administrator saves a card or a Link account on the payment page that `getOrganizationBilling` links as `paymentPageUrl`. An agent never sees payment details, so it gives the user that link.
3. `startOrganizationPlan` charges the monthly fee on it, and the plan is live as soon as the payment succeeds.

When the bank asks the cardholder to confirm, the plan waits as `awaiting_payment` until they do on the same payment page.

## What is billed, and when?

The monthly fee at the start of each period, and the [billed conversations](https://heythere.io/docs/concepts/usage) of each period at its end, beyond those the plan includes. `listOrganizationInvoices` lists the 24 latest invoices, with the page where each is paid and its PDF.

When a renewal fails, the plan stays live as `past_due` while the payment is retried. It becomes `unpaid` once the retries stop, and those three actions are refused until the payment page pays the invoice.

## How does an organization stop the plan?

`cancelOrganizationPlan` ends it at the end of the current period, whose conversations are invoiced once it ends. `resumeOrganizationPlan` keeps it renewing, as long as the period has not ended.

After a plan ends or stays `unpaid`, published automations keep running; only those three actions are refused.

Deleting the organization ends its plan at once and erases its billing details.

## In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. [The OpenAPI document](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `getOrganizationBilling`: Get an organization's billing. `GET /api/organizations/{organizationId}/billing`
- `setOrganizationBillingDetails`: Replace an organization's billing details. `PUT /api/organizations/{organizationId}/billing/details`
- `startOrganizationPlan`: Start an organization's production plan. `PUT /api/organizations/{organizationId}/billing/plan`
- `cancelOrganizationPlan`: Cancel an organization's plan at the end of its period. `POST /api/organizations/{organizationId}/billing/plan/cancel`
- `resumeOrganizationPlan`: Keep an organization's plan renewing. `POST /api/organizations/{organizationId}/billing/plan/resume`
- `listOrganizationInvoices`: List an organization's invoices. `GET /api/organizations/{organizationId}/billing/invoices`
