get with { "kind": "billing" } returns one organization’s billing in a
single read: its Terms, payment status, payment terms, standing, balance, IU usage, payout
setup, plan, the offer it can accept, its renewal, its recent invoices and the
next thing to do. It takes no ID or filter. It takes an include for the
detail a bare read leaves out: mediaBilling, usageDetail, pricing,
contracts, accounts, paymentMethods, invoiceHistory and payouts. It
always reads the organization of the selected account, so check
object.organization.customerId before you act on it.
The read changes nothing. It is available to Buyer, Seller and Organization
accounts. When an account’s organization manages billing for it, a member who
is not an administrator of that organization gets the billing_managed answer
described in Response variants, and so does the
account’s own service token, organization API key or machine-to-machine
application when it is not scoped to an advertiser. Only the organization’s
administrators read its billing.
Open Plan & Billing in Claude, ChatGPT or Murph
To see or change billing in a person’s own host, ask the agent to open Plan & Billing. The agent callsopen_plan_and_billing, which shows the
Plan & Billing Page: the plan, Terms, payment terms,
payment method, payer and payout details, invoices, and the requests waiting for
an administrator. The call takes no input and changes nothing.
It is available to Seller, Buyer and Organization accounts. A Developer account
has no plan of its own, so it reviews plans in its organization account. Claude
and Murph show the Page straight away. ChatGPT shows it once OpenAI’s scan
approves the tool. To answer one question without the Page, read get with
kind: "billing".
What the read returns
Both response channels carry the same facts. The structured result is the complete object. The text result starts with a short summary of the next action, the plan, the offer version, the renewal and the invoices, followed by the rest of the object, so a host that shows only text can still choose its next call.Payment terms a seller refused
When a seller’s agent refuses an account request because it does not accept your payment terms (PAYMENT_TERMS_NOT_SUPPORTED), nothing is sent to it
again until something changes. Once an administrator approves different
paymentTerms for save_billing, every request a seller refused over the terms
you replaced is sent once more, with the new terms. Choosing the terms you already have sends
nothing, and a request refused under the new terms waits for your next change
or for the seller to accept them. We never send terms other than the ones you
chose. A refusal over anything other than your payment terms, such as a seller
that has not enabled agent billing, is for the seller to fix, and changing your
terms does not resend it.
nextAction
nextAction.type names the next step in a fixed order: accept Terms, accept the
governing agreement, choose a plan, add billing details, then set up payment.
SELECT_IU_PLAN means the organization has no plan and an offer is waiting.
ADD_BILLING_INFO means the payer name and address are missing; see
Add billing details for where to enter them.
ACCEPT_GOVERNING_AGREEMENT means the agreement behind the offer must be
accepted first. ADD_PAYMENT_METHOD, FUND_PREPAY and CONTACT_SCOPE3 name
how the chosen plan gets paid for. NONE means nothing is owed.
nextAction.severity is success when the type is NONE and warning for
every other type. Read it instead of deciding urgency yourself.
nextAction.canCompleteInChat is true only when the next action is accepting
Terms and the signed-in person can do it from this session.
standing, balance and usage
setupProgress
setupProgress says how far the organization has got through the four setup
steps, decided on the server from the same facts as nextAction, so the two
never disagree. It is null once nextAction is not a setup action.
payout and permissions
payout says whether setup is owed, and carries the link to the web Payouts
page when you ask for payouts and may change them. Ask for
payouts to read the payees and their
masked bank details. Payout details are typed on that web page, never in chat or
in the Plan & Billing Page; see
Change where a Seller is paid.
Whether the signed-in person may accept Terms stays in terms.canAccept.
payer
payer holds the name, invoice emails, address and tax ID we print on the
organization’s invoices. It uses the names and meaning of the billing profile in
the v2 API. Nothing here is a card or bank detail.
A failure to read the payer details fails the whole read. The text result
starts its summary with whether the details are complete and, when they are not,
how to add them.
pendingApprovals
A payment terms choice, a renewal change, a card setup, a card removal, a pay
now or a payout details change is recorded for an administrator to approve on Apostra,
and nothing changes until they do. If you lose track of one
(a Page was rebuilt, a conversation moved on), the billing read lists it. Each
entry is a request you made yourself and that can still be decided: waiting
before its deadline, or approved and being completed. Another person’s request is
never listed, a request that was approved, declined or expired is not listed,
and a service token, which has no person behind it, sees an empty list.
A
billing.payment_method_setup entry carries only kind, url, idempotencyKey and expiresAt. A card setup asks for no choice, so there is nothing to repeat with the key. A billing.pay_now entry carries the same four fields: it names no choice beyond the organization. Call save_billing with paymentMethod or payNow and the entry’s idempotencyKey to read a card removal or a pay now.
A billing.payout_details entry carries only kind, url, idempotencyKey and expiresAt too, for a different reason: payout details are bank data, so the read never repeats a name, an account number or an identifier. A caller that still holds the details it sent can repeat that same write with this key to read the approval.
plan
plan.current and plan.upcoming carry the same fields:
plan.offer carries:
paymentOptions lists the options a private proposal lets the organization
choose from: optionKey, kind (MONTHLY or TERM_PREPAY), displayName,
currency, amountMinor, termMonths, paymentTermsDays and
collectionMethods. For MONTHLY, amountMinor is the monthly amount; for
TERM_PREPAY, it is the whole prepaid amount. A public plan has no options to
choose from, so the list is empty. acceptanceConvertsStandaloneAccount is
true when accepting that plan first turns a standalone account into an
organization.
plan.renewal carries:
invoices
invoices lists at most 10 invoices, newest first. invoicesTruncated is
true when the organization has older ones.
Usage detail
Addinclude: ["usageDetail"] to read the IU cycle in detail. A bare read
carries only usage.usedIus and usage.activityIus.
usageDetail beside object. It comes from the same IU
account that Plan & Billing shows, so the two agree. The plan key, the monthly
commitment and the IU price are not repeated here: they stay on plan.current.
Platform fee rates
Addinclude: ["pricing"] to read the platform fee rates in force for the
organization.
Contracts
Addinclude: ["contracts"] to read the agreements the organization has
accepted, their documents and its plan history.
Accounts
Addinclude: ["accounts"] to read the organization’s child accounts. Only a
direct administrator of the organization can read it; any other caller gets it
in unavailableIncludes with the reason.
Saved cards
Addinclude: ["paymentMethods"] to read the organization’s saved cards. Only
a direct administrator of the organization can read it; any other caller gets it
in unavailableIncludes with the reason.
This is a summary, the kind a payment provider shows anyone who can see the
account. It never carries a card number, a security code, a processor ID or a
setup token.
Invoice history
Addinclude: ["invoiceHistory"] to read every fee invoice. The bare invoices
list is unchanged: it holds the 10 newest.
Naming an include more than once reads it once. If the saved cards or the
invoice history cannot be read right now, the read still answers. It leaves the include out and lists it in
unavailableIncludes.
Payouts
Payouts say how a Seller is paid: the bank account for each legal entity and currency, and whether the account’s payout details are its own or its organization’s. Read them by addinginclude: ["payouts"] to the billing read.
A bare billing read does not carry them and is unchanged.
payouts beside object:
Two values are cut to their last four characters: the account number or IBAN,
and the bank identifier (a routing number, a CHIPS number, a SWIFT-BIC or a local
bank code). The full values are never returned, by this read or by any other.
bankIdentifierLast4 is an empty string when the identifier has four
characters or fewer, because its last four would be the whole value. Nothing
else is masked: the beneficiary name, the address and the bank identifier type
come back as stored.
The billing read still answers when payouts cannot be read. It leaves
payouts out and lists it in unavailableIncludes with the reason when:
- the organization has not accepted the Terms. Payouts are read only after
Terms;
termsin the same read says what is owed. - the account is a Buyer account, or an organization with no Seller account. Payouts exist only for Sellers.
- the payouts could not be read right now.
inherited set to true. An
agent cannot change a payee or payout details. Bank details are typed on the web
Payouts page, because a bank account number is a secret that does not pass
through chat. Give the person payout.manageUrl to open it; see
Change where a Seller is paid.
permissions.canSetPayout says whether the signed-in person may do it.
The Payouts tab on the web
The Payouts tab of Plan & Billing on the web shows these same facts: the payees, whether the account’s details are its own or its organization’s, and, for an organization, each Seller account’s payout status. It reads them with this read, so it shows a bank account number and a bank identifier cut to their last four characters, the same as an agent sees. Adding or editing a payee is a step on that tab, in your own browser session. It is not an API operation: an API key, a service token or an MCP bearer cannot do it, and no tool does. A signed-in administrator of the billing organization saves the payee on the call, for the organization itself or for a Seller account under it. An account that its organization manages cannot change its own payouts; the organization does. Because a read returns only the last four characters of the bank identifier, editing a payee asks for the full bank identifier again. The account number is asked again only if you replace it; otherwise the stored number stays.Media billing entities
Media billing says who is invoiced for the organization’s media. A media billing entity is a legal name, a country, the currency it is invoiced in, invoice emails, an address and a tax ID. An entity attaches to one advertiser or one account. The organization’s primary entity catches every advertiser and account with no entity of its own. Today the entities record that choice: the invoice we issue does not use them yet. Read them by addinginclude: ["mediaBilling"] to the billing read. A bare
billing read does not carry them.
mediaBilling beside object:
The read returns what is stored. It does not check an entity against AdCP’s
field limits, which are tighter than ours for some fields (for example, a legal
name of at most 200 characters). The read follows who can read media billing in
Plan & Billing: from the organization’s own account, its members; from one of its
accounts, only a direct administrator of the organization. When the caller may
not read it, the billing read still answers. It leaves
mediaBilling out and
lists it in unavailableIncludes with the reason.
Create, change and attach entities with save_billing, as
Change media billing entities
describes, or in the Media billing tab of Plan & Billing on the web.
Who is invoiced for an advertiser
get with kind: "advertiser" carries mediaBilling, the entity that
resolves for that advertiser, so you do not have to match attachments yourself.
mediaBilling is null when no entity resolves for the advertiser. When the
caller may not read media billing, the field is left out, so absent means “not
allowed” and null means “no entity”. If the read itself fails, the field is
also left out and unavailableIncludes says so; the advertiser is still
returned.
Who is invoiced for an account
get with kind: "account" carries mediaBilling for the child account in
the same shape, so you do not have to match attachments yourself. source is
account when the account has an entity attached to it, and organization
when the organization’s primary entity catches it. It is never advertiser.
mediaBilling is null when no entity resolves for the account. When the
caller may not read media billing, the field is left out, so absent means “not
allowed” and null means “no entity”. If the read itself fails, the field is
also left out and unavailableIncludes says so; the account is still returned.
Change media billing entities
Media billing entities are the names and addresses we print on a media invoice. Like the payer details, they move no money and commit the organization to nothing, so a change saves on the call, with no approval step. Callsave_billing with mediaBilling, sent alone (not beside terms,
paymentTerms, plan, offerResponse, renewal or payer). Each call makes
one change: send exactly one of entity, removeEntityId, attach or
detach.
action: "media_billing_saved" with saved (the entityId
or attachmentId the change was made to) and mediaBilling, the updated
entities and attachments in the shape the read returns. If the change is saved
but the read after it fails, the answer is still a success: it leaves out
mediaBilling and names it in unavailableIncludes with the reason, so you do
not repeat a change that already happened. Read it with get. idempotencyKey
is accepted only with paymentTerms, so mediaBilling takes none. A repeated
create is refused when an entity with the same name and currency already exists.
AdCP’s limits apply to every write, and they are tighter than the web app’s form
and the v2 routes: legal_name is at most 200 characters, tax_id 30,
address.street 200, address.city 100, address.postal_code 20 and
address.region 100, with at most 10 contacts. address.country is an ISO
3166-1 alpha-2 code, never a country name. legal_name, street, city and
postal_code must not be empty, and each email must be a valid address. A call
that breaks a limit is refused with the field named, and nothing changes. An
entity saved earlier through the web app over one of these limits still reads as
stored. To change it through save_billing, it has to fit. The
address is saved as one street line: street is stored as line 1, and line 2 is
cleared. An entity carries no bank, vat_id, registration_number or ext,
and a contact carries only role and email.
These rules hold on every call:
- There is exactly one primary entity while any entity exists. The first entity
you create is primary. Send
isPrimary: trueto make another one primary, and the old primary stops being primary. You cannot demote the primary by sendingisPrimary: false. Make another entity primary instead. Removing the primary makes the oldest remaining entity primary. - An entity with attachments cannot be removed. Detach them first.
- An advertiser or account takes one attachment. Detach it before you attach it to another entity.
ACCESS_DENIED, and nothing changes. Each change is recorded in
the audit log with the entity as it was and as it is now.
The Media billing tab in the Apostra web app changes the same entities.
Change the payer details
Payer details are what we print on the organization’s invoices. They move no money and commit the organization to nothing, so a direct administrator of the billing organization saves them on the call, from an agent or from the Plan & Billing Page, with no approval step. Callsave_billing with payer, sent alone (not beside terms, paymentTerms,
plan, offerResponse, renewal or mediaBilling):
action: "payer_saved" with payer, the details as
they stand now, in the shape the read returns. payer.complete says whether we
now have what an invoice needs, and payer.missing names what is still needed. Confirm the details with the person before you
send them.
Only a direct administrator of the billing organization signed in as
themselves may save payer details. An administrator of a parent organization who
is not a direct member, Apostra staff without a direct administrator
membership, service tokens and impersonated or support sessions are
refused with ACCESS_DENIED, and nothing changes. A direct administrator of the
organization may work from the organization account or any child account they
administer. Each change is recorded in the audit log with the values before and
after.
The Plan & Billing Page and the Payment & invoices form in the Apostra web app
save payer details the same way.
Choose the payment terms
The payment terms are what every seller connection of the organization is asked for. Choosing them binds the organization, so a call from an agent or a Page does not change them. A direct administrator of the billing organization approves the choice on Apostra first. Callsave_billing with paymentTerms
and an idempotencyKey, sent alone (not beside terms, plan,
offerResponse, renewal or payer):
action: "approval_required" with an
approval url, its state and when it expires. Show the person the link and
say that nothing changes until an administrator approves. The approval page
shows the terms in force now beside the ones you asked for, and says when none
were ever chosen and the net_60 default applies. Asking for the terms the
organization has already chosen records nothing and answers
payment_terms_saved. Approving sets the terms once
and records the change in the audit log under the administrator who approved it.
Call again with the same idempotencyKey to check. If you sent none, use the idempotencyKey in the answer: a call with that key reads the approval and never records a new one, while a call with no key can start a new request once the earlier one has ended. While the approval waits, or
when it ended without approval (rejected, expired or failed), the answer is
approval_required and its state says which. Once it is approved, the answer
is action: "payment_terms_saved" with paymentTerms and
paymentTermsChosen: true. get with kind: "billing" returns the same terms.
Only a direct administrator of the billing organization signed in as themselves
may ask for the terms, and only a direct administrator signed in to Apostra in
their own browser may approve them. An administrator of a parent organization who
is not a direct member, Apostra staff without a direct administrator membership,
service tokens and impersonated or support sessions are refused with
ACCESS_DENIED, and nothing is recorded.
Apostra’s own screens ask for the choice the same way: the Buyer Setup Page and
the Media Partners prompt call save_billing, open the approval page, and show
the terms once they are in force.
Remove a saved card
Removing a card changes how the organization pays, so a call from an agent or a Page does not remove it. A direct administrator of the billing organization approves the removal on Apostra first. Callsave_billing with paymentMethod
and an idempotencyKey, sent alone (not beside terms, paymentTerms, plan,
offerResponse, renewal, payer, mediaBilling or payNow):
action: "approval_required" with an
approval url, its state and when it expires. Show the person the link and
say that nothing changes until an administrator approves. The approval page
shows the card, its brand, last four digits and expiry, as it is on file now.
A request is refused, and nothing is recorded, when the card is not on file for
the organization (NOT_FOUND), or when it is the organization’s only way to
pay: with no credit line and no balance to spend, removing it would leave no way
to pay, so add a replacement card first. Approving removes the card once. It can
no longer be charged, and adding a card again goes through a new card setup. If
the card became the only way to pay between the request and the decision, the
approval fails and the card stays.
Call again with the same idempotencyKey to check. While the approval waits,
or when it ended without approval (rejected, expired or failed), the
answer is approval_required and its state says which. Once it is approved,
the answer is action: "payment_method_removed" with
paymentMethod: { id, removed: true }. Read billing again with get and
kind: "billing" to see the organization’s payment status without the card.
Only a direct administrator of the billing organization may ask, and only a
direct administrator signed in to Apostra in their own browser may approve. A
user’s own API key, which acts for that user, can ask. An administrator of a
parent organization who is not a direct member, Apostra staff without a direct
administrator membership, credentials that act for no user (service tokens and
organization API keys) and impersonated or support sessions are refused with
ACCESS_DENIED, and nothing is recorded.
Change where a Seller is paid
Payout details are the bank account and beneficiary Apostra wires a Seller’s revenue to, so changing them binds the organization. A bank account number is a secret, so it is typed only on Apostra’s own web Payouts page, never in chat and never in the Plan & Billing Page. An administrator signed in on Apostra saves them there directly. The Plan & Billing Page shows where payouts stand and, for a person who may change them, a button that opens the Payouts page. It opens the linkpayout.manageUrl that the billing read carries when you ask for
payouts. A person who may not change
payouts gets no link and no button, and the Page says that only an account
administrator can. An agent does the same: it reads payout.manageUrl, shows
the person the link and asks them to open it. The Page no longer takes bank
details or calls set_plan_billing_payout_payee, the action earlier versions of
the Page used.
A request that does not come from that page, such as one sent with an API key,
does not change the details. It records a request, returns
action: "approval_required" with an approval url, its state and when it
expires, and takes effect only after a direct administrator of the billing
organization approves it on Apostra.
payout.onboardingStatus becomes complete once the first payee is saved. Your own waiting request appears in
pendingApprovals as
billing.payout_details, with no bank data.
Pay a failed payment now
When a card payment fails, Apostra retries it on a schedule. Paying now charges the saved card straight away for the organization’s open failed payment. It moves money, so a call from an agent or a Page does not charge. A direct administrator of the billing organization approves it on Apostra first. Callsave_billing with payNow: true and an idempotencyKey, sent alone (not
beside any other declaration):
action: "approval_required" with an
approval url, its state and when it expires. Show the person the link and
say that nothing is charged until an administrator approves. The approval page
shows the failed payment’s amount and date and the card that would be charged,
as they are now. A request is refused, and nothing is recorded, when there is no
failed payment to pay (NOT_FOUND), when a payment attempt is already
processing (VALIDATION_ERROR), or when there is no card to charge
(VALIDATION_ERROR).
Approving starts one charge on the saved card. The payment provider reports how
it ends afterwards, so a started charge is not a paid one. Call again with the
same idempotencyKey to check. While the approval waits, or when it ended
without approval (rejected, expired or failed), the answer is
approval_required and its state says which. Once it is approved, the answer
is action: "pay_now_started" with payNow: { status: "processing" }. It never
says the payment was made. Read billing again with get and kind: "billing"
to see the result in standing and balance once the provider confirms it. If
the charge is declined, the failed payment stays open and its retry schedule
continues. An approval fails, and nothing is charged, when the failed payment is
gone by the time it runs (for example because it was paid in the meantime) or
the card was removed.
Repeating an approved request never charges twice: the charge carries a key that
Apostra stores on the failed payment before it is sent, so a charge whose answer
was lost is found again instead of repeated.
The same people may ask and approve as for a card removal.
Change the renewal
Ending the plan at the end of its term, or keeping it renewing, changes the contract the organization has accepted, so a call from an agent or a Page does not change the renewal. A direct administrator of the billing organization approves the change on Apostra first. Callsave_billing with renewal, sent
alone (not beside terms, paymentTerms, plan, offerResponse or payer):
renewalVersion that is no
longer current is refused with CONFLICT, field: "renewalVersion" and
details.currentVersion, and an action outside allowedActions is refused with
CONFLICT. Nothing is recorded in either case: read the renewal again and ask
the person to confirm again.
Otherwise the call changes nothing. It returns action: "approval_required"
with an approval url, its state and when it expires. Show the person the link
and say that nothing changes until an administrator approves. The approval page
shows the action, the plan term it applies to and the date it takes effect (the
end of the current term), the reason, and the renewal as it stands now.
When an administrator approves, Apostra applies the change once, as that
administrator, and records it in the audit log under their name. It checks the
renewal version again at that moment. If the renewal has changed since you asked
(another change landed, the window for changing it closed, or the plan is no
longer eligible), the approval ends as failed and nothing changes: read the
renewal again and ask again, under a new key if you send one.
Call again with the same renewal, including its idempotencyKey if you sent
one, to check. A repeat with a key does not compare the version again, because
approving the first call moves the renewal on. While the approval waits, or when
it ended without approval (rejected, expired or failed), a keyed call
answers approval_required and its state says which. Once it is approved, it
answers action: "renewal_changed" with renewal.instructionId, instruction,
effectiveAt and changeCutoffAt. A call with no key reads the approval you
have open, and so answers approval_required while it waits; to check without
any chance of asking again, repeat the call with the idempotencyKey the answer
named. Once the approval
has succeeded the renewal has a new version, so a call with no key for the old
version is refused as stale: read get with kind: "billing", which returns the
new plan.renewal, to see the change.
Only a direct administrator of the billing organization signed in as themselves
may ask for the change, and only a direct administrator signed in to Apostra in
their own browser may approve it. An administrator of a parent organization who
is not a direct member, Apostra staff without a direct administrator membership,
service tokens and impersonated or support sessions are refused with
ACCESS_DENIED, and nothing is recorded.
The Plan & Billing Page asks for the change the same
way: it calls save_billing, opens the approval page, says that nothing changes
until an administrator approves, and asks again while it waits. It shows the
result once the change is approved, and says plainly that nothing was changed if
the approval was declined, expired or failed. The Page and its controls send no
key on a click, so a Page that is rebuilt while an approval waits returns the
same approval on the next ask instead of recording a second. While it waits, the
Page checks with the key the answer named, which reads the approval and never
records a new one, so a declined change stays declined until the person asks
again.
When an account becomes an organization
A standalone account is its own billing boundary. When it is converted into an organization (see Turn a standalone account into an organization), the billing read above starts reading the new organization, so the billing records move with the conversion, in the same step as the contract. Nothing is charged again and Stripe is not called. What moves to the organization:- the card, its Stripe customer, its payment methods (a detached one too), and any card setup or capture link that has not finished. The Stripe customer id and payment method id do not change, so a card entered before the conversion keeps being charged after it;
- a metered plan record (a plan with no monthly commitment), and the free, rollover and referral credit;
- credit standing, buyer payment terms and the billing currency override;
- the billing contact fields. They are copied: the organization gets them and the account keeps its own values as history.
Billing documents
The rate card of a plan and the organization’s contract documents are files, and they download from Plan & Billing on the web, not from the API. A direct administrator of the billing organization opens them from the page. The file is served only to a signed-in browser session, so an API key, a service token or an agent credential cannot fetch one, and the read carries no download link for them. The proposal document of a plan, in force or upcoming, or of a pending offer is the one of itsofferVersion. If you need a copy of a document, open
Plan & Billing in the web app and download it there.
What the read leaves out
The read never carries card numbers, security codes, processor IDs, processor secrets, setup tokens, hosted invoice or payment links, browser hand-off links, or a full bank account number or bank identifier. A card summary (brand, last four digits, expiry and status) is available withinclude: ["paymentMethods"]. It also leaves out
internal row IDs, the actor behind a renewal change and any free-text reason
given for one. terms.url and nextAction.docsUrl are public documentation
links.
A caller without billing access
The read follows the same access rules as Plan & Billing. A member who cannot read the organization’s billing gets the organization that manages it, or a refusal, never part of the plan section. Thebilling_managed answer carries nothing from the organization’s billing, so
usageDetail, pricing, contracts, accounts, paymentMethods and
invoiceHistory are left out of it when you ask for them. Each is listed in
unavailableIncludes with the reason.