Skip to main content
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 calls open_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

Add include: ["usageDetail"] to read the IU cycle in detail. A bare read carries only usage.usedIus and usage.activityIus.
The result carries 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

Add include: ["pricing"] to read the platform fee rates in force for the organization.

Contracts

Add include: ["contracts"] to read the agreements the organization has accepted, their documents and its plan history.

Accounts

Add include: ["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

Add include: ["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

Add include: ["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 adding include: ["payouts"] to the billing read. A bare billing read does not carry them and is unchanged.
The result carries 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; terms in 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.
A Seller account reads its own payouts, and an account whose organization manages billing reads the organization’s, with 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 adding include: ["mediaBilling"] to the billing read. A bare billing read does not carry them.
The result carries 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. Call save_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.
The call returns 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: true to make another one primary, and the old primary stops being primary. You cannot demote the primary by sending isPrimary: 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.
Who may write follows who may change media billing in Plan & Billing. From the organization’s own account, the caller’s role must be administrator. From one of its child accounts, the caller must be a direct administrator member of the organization. Service tokens and advertiser-scoped principals are refused from a child account. Apostra staff acting as a SuperAdmin may write. A caller who may not write gets 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. Call save_billing with payer, sent alone (not beside terms, paymentTerms, plan, offerResponse, renewal or mediaBilling):
The call checks the fields, writes the ones you named to the billing organization and returns 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. Call save_billing with paymentTerms and an idempotencyKey, sent alone (not beside terms, plan, offerResponse, renewal or payer):
The call writes 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 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. Call save_billing with paymentMethod and an idempotencyKey, sent alone (not beside terms, paymentTerms, plan, offerResponse, renewal, payer, mediaBilling or payNow):
The call removes 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 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 link payout.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. Call save_billing with payNow: true and an idempotencyKey, sent alone (not beside any other declaration):
The call charges 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 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. Call save_billing with renewal, sent alone (not beside terms, paymentTerms, plan, offerResponse or payer):
The call checks the version and the action first. A 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.
What stays with the account: media billing entities and their advertiser attachments. They keep resolving for the account’s advertisers. Where the organization already holds a plan record, standing, payment terms, currency override, free credit or the same rollover cycle, the organization’s own record stays as it is and the account’s stays on the account as history; nothing is merged. An organization that already has its own Stripe customer stops the conversion, because two cards cannot be reconciled by a rule. An account with a charge, a closed cycle or an invoice in progress, a payment collection in progress, an open standing hold, a plan with a monthly commitment, a credit application, a referral or funds on its Apostra balance is refused, and the refusal names which one. Afterwards only organization administrators see and manage the card, invoices and standing, because they belong to the organization. A member of the account who is not an organization administrator no longer sees them, and a billing read from that account returns the organization that manages billing or a refusal, as in A caller without billing access.

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 its offerVersion. 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 with include: ["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. The billing_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.