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.
No plan limits how many Buyer Accounts an organization holds. Archived accounts
keep their history. See
Accounts in an organization.
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
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.- 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.
- You connect the platform once. Apostra reads the ad accounts that sign-in can reach. See Platform accounts and advertiser mapping.
- 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.
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.
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.
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. 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 and Media billing entity configuration. Choose the route for a seller withsave_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.
Choose a credential
A user API key, an organization API key and an M2M application each reach one account. SendingX-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.
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 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.
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.
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. WithREAD, 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.
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.
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 withoperatorFees. 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.
Related
- Account access covers the accounts a call can reach.
- Name the account on every call covers
accountId. - Authentication covers every credential.
- Plan & Billing covers what you pay Apostra.