# Shared billing for independent businesses

> Split selected project work into separate drafts, or group invoices that already exist.

Source: https://app.getoatmilk.com/docs/shared-billing

An invoice belongs to one legal billing business. A shared billing group identifies the work that several businesses pay for. It links invoices without creating another revenue record. Project collaborators remain separate from billing recipients.

In the invoice creator, select the work as usual. Open **Split between businesses** only when you need it. Name the group and phase, choose the project, then choose each business and its share, billing contact, sales tax and payment terms. Add as many businesses as the generated action schema permits. No equal split or tax treatment is selected for you. The same split can cover the selected work, or each item can have its own allocation. Combining phases and allocating responsibility are separate choices.

The live share total explains what remains to assign. The review shows each business's bill-to details, lines, base, configured tax, due date and terms. **Create separate drafts** creates the whole batch in one transaction. The original unsplit draft is voided in that transaction. Nothing is emailed, issued, scheduled for sending or charged. Cancel before creation to return to the ordinary draft. Review and issue each new draft separately through the existing invoice workflow.

Invoices keep independent numbers, recipients, taxes, payment records, statuses and balances. Issuance freezes their financial and billing snapshots. New split invoices use the chosen billing contact, and their default send and reminder recipients keep that issued email snapshot. Retrospectively grouped invoices keep their existing delivery behavior. Changing a billing profile or planned allocation never rewrites an issued invoice.

Before issuance, edit the allocation and preview again to replace the generated drafts together. Old drafts become void and remain in history. Issued, scheduled or detached invoices cannot be silently replaced. Future phases use another named group with their own selected work and allocation; a discovery split never becomes a project-wide default. Stable work item IDs prevent the same selected work from being generated twice within a project. Reuse an item's ID when referring to the same work.

## Group invoices after the fact

Select the invoices in **Invoices**, then choose **Group as split bill**. Name the shared work and choose or create its project in place. The selected invoices can belong to different billing businesses, but must share a currency and have no existing billing group. Saving creates the group and ties every selected invoice to that project in one transaction. The review shows any project change before saving.

You can also open **Invoices → New → Shared billing groups → Existing invoices** to select invoices already tied to a project. Open an existing group to attach more invoices or remove associations. Grouped invoices and project views link back to the shared group.

Retrospective grouping changes associations only. It leaves issued amounts, bill-to details, taxes, invoice numbers, status and payment history intact. The bulk action explicitly ties the selected invoices to the chosen project; attaching to an existing group requires the project already to match. Invoices from another currency, workspace or existing group are refused. A group with a planned allocation also checks its configured payers. Every association change is audited and uses current group and invoice revisions. Removing an association preserves the invoice and its generation provenance.

## Reporting

Open a group to see planned base separately from actually invoiced totals and drafts. Each payer has their own owed balance and linked invoice statuses. Drafts are not billed revenue. Voids remain visible but contribute no revenue or balance. Archived invoices stay in the group's accounting view. Payments and written-off amounts use the existing invoice accounting model. Negative invoice balances appear as credits separately from positive receivables; they are not automatically applied to a different business. A credit adjusts actual billed totals, while a planned allocation remains a plan. Group totals summarize linked invoices and must never be added to those same invoice totals in another report.

A group can contain partially billed work through existing invoice associations. Its remaining planned base compares the saved plan with net issued base amounts, not tax-inclusive totals. A group without a plan reports actual invoices and explicitly has no planned allocation. New split plans accept nonnegative billable lines; use the existing invoice model for separate credit adjustments. Attaching credit invoices is subject to the same project, currency and payer checks.

## MCP, API and terminal

All surfaces use the same action catalog, schemas, authorization and server validation. The invoicing MCP toolset exposes the `invoices.groups.*` actions. Use the action reference for current limits and exact schemas.

1. `invoices.groups.save` saves the project, group context, currency and optional allocation plan. Every selected item belongs to exactly one allocation. Percentages total exactly 100; fixed shares total the selected base in currency minor units.
2. `invoices.groups.preview` takes `id` and `expectedRevision`. It returns each invoice and `previewHash` bound to the saved revision, current billing profiles and tax settings.
3. `invoices.groups.createDrafts` takes the reviewed `previewHash`, `id`, `expectedRevision` and `idempotencyKey`. Optional `sourceDraftId` and `sourceDraftRevision` replace the matching unsplit draft atomically. A stale preview requires another review.
4. `invoices.groups.groupSelected` takes the chosen `projectId`, `name`, `currency`, selected invoice IDs and revisions, and `idempotencyKey`. It creates a group and sets the project and group on all selected invoices atomically. A stale invoice refuses the whole change.
5. `invoices.groups.attach` and `invoices.groups.detach` take group and invoice revisions. `invoices.groups.get` returns the saved plan, group report and individual invoice statuses. `invoices.groups.list` filters by project. `invoices.list` accepts `billingGroupId`.

The terminal's **Invoices → Shared billing groups** offers guided setup, previews, group reports and association controls. Headless commands retain structured JSON:

```sh
oatmilk actions invoices.groups.save --json
oatmilk api invoices.groups.save @group.json --idempotency-key discovery-plan-001
oatmilk api invoices.groups.preview '{"id":"GROUP_UUID","expectedRevision":1}'
oatmilk api invoices.groups.createDrafts @reviewed-batch.json --idempotency-key discovery-drafts-001
oatmilk api invoices.groups.get '{"id":"GROUP_UUID"}'
```

Keep the same idempotency key and identical input when retrying an uncertain response. A failed transaction creates no partial batch. A lost successful response replays the saved result; another key for an already generated revision returns the same invoice IDs. Reusing a key with changed input fails. The terminal retains interrupted writes during the session and offers to resume the same request identity. It does not claim drafts were issued or delivered.

Amounts are integer currency minor units on the API. Percentage arithmetic uses integers with up to four decimal places. Largest remainders allocate residual units, with stable party IDs breaking ties. Item amounts reconcile to payer amounts and to the selected base exactly; no hidden rounding loss is added to project revenue.