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

# Media billing entity configuration

> Configure and preview the legal entity intended for Apostra-cleared media invoices

Media billing entities let an organization configure and preview the legal
recipient intended for an **Apostra-cleared** media invoice. They do not
decide whether Apostra invoices a transaction: that comes from its billing party
(`agent` vs `operator` vs `advertiser`).

<Warning>
  This surface is currently configuration and preview only. You can create
  entities, attach advertisers/accounts, and inspect the most-specific match,
  but the media-invoice producer does not yet consume that resolution. Creating
  or attaching an entity does not by itself change invoice issuance or delivery.
</Warning>

## Two streams, kept separate

* **Apostra fees** — platform fees and IU bundles/overage when your
  organization's commercial terms enable them.
* **Media billing** — legal-recipient configuration for media transactions
  whose billing party is `agent`. This page covers that preview model.

A surface, invoice, or line item is always identifiably one stream or the
other — never a blended "billing." See
[Plan & Billing page](/v2/buyer/billing/plan-and-billing) for where each
stream renders.

## The resolution hierarchy

Media billing entities are configured at up to three levels and resolved
**most-specific-first**. The presence of an entity at a level is what makes the
preview resolver select it:

| Level            | Rule                                                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Advertiser**   | If an advertiser has its own billing entity attached, the preview resolves to that entity.                              |
| **Account**      | Else, if the advertiser's child account has an attached entity, the preview resolves there.                             |
| **Organization** | Else, the preview uses the organization's primary entity when one exists; without one it returns `resolvedVia: "none"`. |

"Most specific wins": an advertiser's own entity beats its account's, which
beats the organization default.

## Country is metadata, not a routing key

A billing entity's country is stored identity metadata. Currency is configured
independently; this preview does not derive tax treatment, currency, or address
format from country. **Country never participates in resolution.** Matching is
purely structural (advertiser → account → organization); it never looks at
where media delivered or where an advertiser operates.

To preview different entity matches by market, model each market with a
**market-scoped advertiser** (for example, "Acme Beverages South Africa") and
attach it to the corresponding configured entity. This matches how agencies
structure market P\&Ls without introducing a separate geo-resolution key. The
invoice producer does not consume this preview yet.

## Entities

A media billing entity carries:

* **Entity name** — the legal entity's name
* **Country** — stored ISO 3166-1 alpha-2 identity metadata
* **Currency** — ISO 4217 currency stored for the configuration preview
* **Billing email(s)** — invoicing contact
* **Address** — street, city, state/region, postal code
* **Tax ID** — optional (e.g. VAT number, EIN)

When an organization has entities, exactly one can be **primary** as the
organization-level fallback. Your first entity automatically becomes primary;
promoting a different entity demotes the previous one in the same step. The
current product does not require an entity before a buy and can resolve to
`none` when the organization has not configured one.

## Attachments

An attachment associates one advertiser or one account with a specific entity
for resolution preview — exactly one of the two per attachment.

## In the product

The **Media billing** tab of the
[Plan & Billing page](/v2/buyer/billing/plan-and-billing) is where this model
renders. It appears for organizations with buyer capability (a pure seller
can have platform fees and payouts, but not media-billing configuration) and shows:

* **Billing entities** — your entities as cards: name, country, currency,
  billing email, and an "Org default" tag on the primary. An entity missing
  its tax ID is flagged. When you have no entities yet, the tab explains that
  no entity exists yet and offers the setup action.
* **Resolution** — one row per attachment (advertiser or account → entity),
  plus an "Everything else" row showing the organization default when one
  exists.
* **Which configured entity matches?** — an inline inspector: pick any advertiser or
  account and see the three resolution steps (advertiser attachment, account
  attachment, organization default) with the matching step highlighted, then
  the resolved entity with its country and currency—or `none` when nothing is
  configured.

The tab writes through the same admin-gated API documented below. UI and API
share the same configuration rules; neither path is wired into invoice
production yet.

## For agents

<CardGroup cols={2}>
  <Card title="List media billing entities" icon="list">
    `GET /api/v2/billing/media-entities`
  </Card>

  <Card title="Create media billing entity" icon="plus">
    `POST /api/v2/billing/media-entities` (admin)
  </Card>

  <Card title="Update media billing entity" icon="pen">
    `PUT /api/v2/billing/media-entities/{entityId}` (admin)
  </Card>

  <Card title="Delete media billing entity" icon="trash">
    `DELETE /api/v2/billing/media-entities/{entityId}` (admin)
  </Card>

  <Card title="List attachments" icon="list">
    `GET /api/v2/billing/media-entities/attachments`
  </Card>

  <Card title="Create attachment" icon="link">
    `POST /api/v2/billing/media-entities/attachments` (admin)
  </Card>

  <Card title="Delete attachment" icon="link-slash">
    `DELETE /api/v2/billing/media-entities/attachments/{attachmentId}` (admin)
  </Card>

  <Card title="Resolve media billing entity" icon="magnifying-glass">
    `GET /api/v2/billing/media-entities/resolve?advertiserId=` or `?childCustomerId=`
  </Card>
</CardGroup>

The resolve endpoint previews which configured entity matches an advertiser or
account: it returns the resolved entity plus `resolvedVia`
(`advertiser` | `account` | `org`), or `resolvedVia: "none"` when your
organization has no entity at all yet. Admin-gated writes are enforced
server-side, so any future client shares the same rule as the REST API.

## Related

<CardGroup cols={2}>
  <Card title="Plan & Billing page" href="/v2/buyer/billing/plan-and-billing" icon="gauge">
    Where interchange fees and media billing both render
  </Card>

  <Card title="Billing overview" href="/v2/buyer/billing/overview" icon="file-invoice-dollar">
    How invoicing and remittance work
  </Card>
</CardGroup>