Work across more than one business

A key is scoped to one or more businesses. list_businesses returns the ones it can act on; when there is exactly one, business_id can be omitted everywhere, and when there are several, every write needs the business it belongs to.

Written and reviewed by the Billr team. Published 2026-09-20, last reviewed 2026-09-20.

Who this is for: People who run more than one freelance entity, brand or company from the same Billr account.
Billr capabilities used: list_businessesget_businesscreate_clientcreate_invoice

What you need first

More than one business on the account, or a key you intend to widen.
A key with the Read and draft profile if the agent has to create records.
The business each piece of work belongs to, decided before the prompt runs.

Step by step

01Ask what the key can reach
list_businesses returns every business in scope with its default currency and invoice prefix. It takes no arguments and is the safest first call in any session.
Example
```
list_businesses  {}
```
02Pass the business when a tool needs to choose one
With two or more businesses in scope, tools that create a record or list a business's records need business_id: create_client, create_item, log_time, log_expense, create_invoice, create_estimate, list_invoices, list_estimates, list_items, list_time_entries, list_expenses, list_unbilled, revenue_summary and the task tools. Tools that act on one existing record by id, such as update_client, update_draft_invoice, send_invoice, record_payment, update_time_entry and update_expense, resolve the business from that record and do not take the field.
03Read the defaults that come with it
get_business returns the currency, invoice prefix, payment terms and notes template a new document will inherit. Those defaults explain most surprising output, such as a due date two weeks out.
04Keep clients where they belong
Clients, items, invoices and logged work all belong to exactly one business. The same client name can exist in two businesses as two separate records with separate balances.

Worked example

Fictional account, field names as returned by the server

You say

Which businesses can you bill for, and what is Harbor & Lane billed as?

Your agent calls

list_businesses {}
list_clients { "business_id": "b7c1e5a0-51de-4b2c-9f0a-8f2c4d1e6a33", "search": "Harbor" }

Expected responses, abridged

{
  "summary": "2 businesses in scope: Fieldstone Digital, Fieldstone Labs.",
  "businesses": [
    {
      "id": "b7c1e5a0-51de-4b2c-9f0a-8f2c4d1e6a33",
      "name": "Fieldstone Digital",
      "currency": "USD",
      "invoice_prefix": "INV"
    }
  ]
}

Limits and gotchas

Work cannot be moved between businesses after the fact. Choose the business before the first write.
Out-of-scope records answer with the same generic error as records that do not exist, on purpose, so a key cannot probe another business.
Reports and summaries run per business; there is no combined figure across two legal entities.
A key still cannot exceed its profile. Extra businesses do not imply extra permissions.

Troubleshooting

A write is refused with a scope message: The key covers several businesses and the tool creates or lists records, so business_id is required. Call list_businesses and pass the id the work belongs to.
The agent says a client does not exist: The client may live in the other business. Repeat the read with the other business_id from list_businesses.
Only one business shows up: The key is scoped to a single business. Create a key for the other one if the same session needs both.

Sources

Reviewed 2026-09-20 against Billr's own tool implementations and the client documentation linked above.