> ## 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.

# Run Apostra for several client accounts

> Choose an account shape, a billing route and a credential when one platform buys media for several clients, and limit what each client's work can do.

This page is for a platform or agency that buys media for several clients and
runs a server-side buyer agent to do it. It makes a recommendation for each
choice, and says plainly where Apostra does not do something yet.

| Choice | Recommendation |
| - | - |
| Account shape | One Buyer Account with an advertiser for each client. Give a client its own account when it needs its own sign-in or its own billing choice with a seller. |
| Billing route | Direct billing by the seller where the seller offers it, with each client's legal entity on its advertiser. Otherwise your organization is invoiced. |
| Credential | A user API key made by a dedicated service user. When clients need different limits, a buyer agent with one grant for each client's advertiser. |
| Limits per client | Read or read-and-write grants, a separate launch step your application controls, and the campaign budget. |

## Choose an account shape

An advertiser is one of your clients' brands. A Buyer Account holds advertisers,
and an organization holds Buyer Accounts. You can run several clients in one
Buyer Account, or give each client a child Buyer Account under your
organization.

| | One Buyer Account, many advertisers | A child Buyer Account for each client |
| - | - | - |
| Billing | One account, one billing policy for each seller. A media billing entity can still be attached to each advertiser. | Each account makes its own billing policy choice for each seller. IU plan and billing details stay with your organization. |
| Access | Your people and your credential see every advertiser in the account. You limit a buyer agent advertiser by advertiser. | Your organization's administrators reach every child account. A client's own members see only their account. |
| Isolation | Clients share one account, one operating unit and one set of seller connections. | Sellers see each account as its own operating unit of your organization. |
| Credentials | One credential can serve every client. | An API key reaches one account, so each client account needs its own. A buyer agent can be granted advertisers in every client account. |
| Setup | `save_advertiser` for each client. | Each child needs `save_account`, which an organization administrator approves on the website. An organization can create 25 accounts in any 24 hours. |

No plan limits how many Buyer Accounts an organization holds. Archived accounts
keep their history. See
[Accounts in an organization](https://docs.apostra.com/v2/account-capacity).

**Recommendation.** If clients never sign in to Apostra and one agent does the
buying, start with one Buyer Account and an advertiser for each client. It is the
simplest shape: one API key reaches every client. Give a client
its own child account when its own people need to sign in, or when it needs a
different billing choice with a seller than your other clients.

An operator fee is set on a campaign. [Operator fees](https://docs.apostra.com/v3/operator-fees.md)
describes it for client accounts under your organization and lists the
conditions to meet before you use one.

### When each client connects its own ad account

A common builder case: each client already has its own ad account on a platform
such as Meta, TikTok or Snap, with its own payment method, and pays the platform
directly. Use one Buyer Account with an advertiser for each client. Choose a
child Buyer Account for a client only for the reasons in the table above.

1. The client lets you reach its ad account on the platform. Either the client
   authorizes the sign-in you connect with, or it adds your manager account
   (a Meta Business Manager, a Google Ads manager account) as a partner. See
   [Agencies link the manager account](https://docs.apostra.com/v2/guides/connecting-ad-platforms.md#agencies-link-the-manager-account).
2. You connect the platform once. Apostra reads the ad accounts that sign-in
   can reach. See [Platform accounts and advertiser mapping](https://docs.apostra.com/v2/concepts/ad-platform-accounts.md).
3. You map each client's ad account to that client's advertiser. A buy for an
   advertiser with no mapped account is refused. It never runs on another
   client's account.

The platform bills the payment method on the connected ad account, which is the
client's own, so the client pays the platform for media. Apostra is not in the
media payment. Apostra's own charges stay on your organization's plan. If
several clients sit behind one manager account, they still share one Buyer
Account, and each has its own advertiser and its own mapped ad account.

## Add your people to the account

Your organization is a container for people, the plan and billing. It is not a
place to work. Campaigns, advertisers and connections live in a Buyer Account
inside it, and a person can work there only when one of these is true:

* They hold a permission on that account: Viewer (read only), Editor (read and
  write) or Admin.
* They are an administrator of the organization that holds the account. An
  organization administrator reaches every account in it.

Belonging to the organization as an Editor or a Viewer is not enough. Such a
person can open the organization, and no account in it. The web app cannot open
a Buyer Account for them, and in Claude Code or the SDK `get_status` shows them
only the organization. Naming an account in `accountId` is refused with
`ACCOUNT_NOT_REACHABLE`, because [naming an account never grants access you do not
already have](https://docs.apostra.com/v3/name-the-account.md).

To give a teammate working access, an administrator of the account adds them to
the Buyer Account itself, with the Editor permission when they need to create
advertisers or campaigns, and gives them an Admin permission only when they also
manage the account's people. To work in every account of the organization, make
them an organization administrator instead. That also lets them accept the Terms
and change the plan, so use it for the few people who should have it.

A person who already holds Viewer on the account reads it and cannot change it.
Raise their permission on the account. A permission on the organization does not
raise it. An API key or an agent does not need any of this: it is bound to one
account when it is made and acts there.

## Choose a billing route

Media is billed by transaction, and the billing party decides who invoices it.
For each seller you choose between two routes.

**Your organization is invoiced.** A client account under your organization is
invoiced to your organization by default. You invoice your client yourself.
Apostra invoicing your client directly is not available yet. See
[Who pays whom](https://docs.apostra.com/v3/operator-fees.md#who-pays-whom).

**The seller invoices the business you name.** An administrator approves direct
billing for a seller. The seller then invoices the media billing entity
resolved for the advertiser, not you. Apostra looks for an entity attached to
the advertiser first, then to its account, then your organization's primary
entity. An advertiser with no resolved entity cannot open a directly billed
account with the seller, so attach each client's legal entity to its
advertiser first. The approval covers your Buyer Account and that seller, and
applies to every current and future advertiser in the account. See
[Approve direct billing](https://docs.apostra.com/v2/buyer/storefronts/tasks/accept-direct-billing.md) and
[Media billing entity configuration](https://docs.apostra.com/v2/buyer/billing/media-billing.md).
Choose the route for a seller with `save_connection` and its `billing` field.
Direct billing is not offered by every seller, and some platforms bill your
connected account directly with no choice.

**Consolidated media invoicing through Apostra is not fully live.** In
consolidated billing the seller sends its invoice to Apostra, not to you. The
setup that names the legal entity on that invoice is configuration and preview
only today. It does not yet change who an invoice is addressed to. Ask your
Apostra contact before you plan client media around it.

**Recommendation.** Use direct billing where the seller offers it and attach
each client's entity to its advertiser. That puts the media invoice with the
client's own business. Where it is not offered, your organization is invoiced
and you invoice the client.

Apostra's own charges are separate. They are billed to your organization on one
plan, whatever the number of accounts. See
[What you pay as a buyer](https://docs.apostra.com/v3/plan-and-billing.md#what-you-pay-as-a-buyer).

## Choose a credential

A user API key, an organization API key and an M2M application each reach one
account. Sending `X-SCOPE3-CUSTOMER-ID` with another account does not widen
it: on the V3 HTTP API the request is refused with `403`. A buyer agent is the
exception: it reaches the advertisers an administrator grants it, in its own
account or in other accounts of your organization.

| Credential | What it reaches | Use it for |
| - | - | - |
| A user API key made by a dedicated service user | The account it was created in, with the owner's role. A read-only member's key cannot write. | A server-side agent for one account that needs no per-client limits. Create it in **Settings → API Access** while signed in as the service user. |
| An M2M application | One account, on the HTTP API only. MCP refuses it. | A deployed backend that needs OAuth client credentials. An organization administrator creates it. |
| A buyer agent | The advertisers an administrator grants it, each read or read and write, in its own account or in other accounts of your organization. | A server-side agent that needs a different limit for each client. |
| A person's OAuth connection | Every account that person can reach, named with `accountId` on each call. It acts as that person. | A person working with a coding agent. Not a server credential: a person approves it in a browser. |
| Agent Registration | A 30-day sandbox that cannot spend until claimed. | Trying Apostra. Not for running clients. |
| An identity-only credential issued from **Manage buyer agents** | Nothing. Every business API answers `403`. | Proving who an agent is. Register a credential that can call APIs instead. |

**Recommendation.** Start with a user API key made by a dedicated service user,
so the key does not depend on one person's job. It reaches every advertiser in
the account. When your clients need different limits, for example one client
read-only, use a buyer agent: an administrator grants it each client's
advertiser, and it reaches only the advertisers it is granted. Registering a
credential to a buyer agent does not widen what that credential can reach. See
[Manage buyer agents](https://docs.apostra.com/v3/buyer-agents.md) for the credentials a
buyer agent can use and how to grant access.

A buyer agent granted advertisers in other accounts of your organization works
in each client's own account: a call that names one of those advertisers in
`advertiserId` runs in the account that owns it. `get_status` lists those
accounts in `reachableAccounts` with `nameWith: "advertiserId"`. See
[Account access](https://docs.apostra.com/v3/account-access.md).

An advertiser grant between organizations is not the way to do this. A grant
gives the grantee's buyer agents nothing. See
[Manage organization advertiser grants](https://docs.apostra.com/v3/advertiser-grants.md).

## Limit what each client's work can do

**Read or read and write for each advertiser.** An administrator signed in
directly sets a buyer agent's grant on each advertiser. With `READ`, the agent
reads that advertiser's campaigns, creatives, media buys and reporting, and any
write is refused with `agent_read_only`. With `READ_WRITE` it can write too.
The agent cannot change its own grants. Set them in **Settings → API keys →
Manage buyer agents**, or with `save_buyer_agent`. See
[Set advertiser access](https://docs.apostra.com/v3/buyer-agents.md#set-advertiser-access).

**Launch is a separate confirmation.** A call to `save_campaign` with
`desiredPhase: "active"` previews the launch and changes nothing. A second call
with `confirmLaunch: true` and the `expectedRevision` from the preview launches
it. If the campaign changed in between, the second call is refused. Your
application can hold that second call behind its own approval. A buyer agent
with only a `READ` grant cannot make it. See
[Build an agent](https://docs.apostra.com/v3/build-an-agent.md#add-buying-steps).

**There is no spend cap per advertiser or account.** You cannot set one today.
The control is the campaign budget: `budget.total`, and an optional
`budget.dailyCap`, set with `save_campaign`. Media buy budgets are allocated
from the campaign's total.

## Client funds

Apostra does not hold a separate prepaid balance for each client, and a launch
does not check one. Before it launches, Apostra checks the account's setup: the
account type, a verified organization identity, a plan, accepted Terms, no
unresolved hold, and, for consolidated billing,
billing details and payment terms. It does not check whether your client has
funds.

Check your client's funds in your own application before your agent confirms a
launch.

## Add your own fee

You can add your own percentage fee to a campaign with `operatorFees`. You
invoice your client and keep the fee. Apostra does not collect it. It is shown
to your organization and hidden from the client unless you choose otherwise.
Operator fees must be switched on for your organization, and a buyer agent
cannot set one. See [Operator fees](https://docs.apostra.com/v3/operator-fees.md).

## Related

* [Account access](https://docs.apostra.com/v3/account-access.md) covers the accounts a call can reach.
* [Name the account on every call](https://docs.apostra.com/v3/name-the-account.md) covers `accountId`.
* [Authentication](https://docs.apostra.com/v3/authentication.md) covers every credential.
* [Plan & Billing](https://docs.apostra.com/v3/plan-and-billing.md) covers what you pay Apostra.


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