> ## 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.
# Billing
> Organization IU plan options, payout bank details, and how Apostra pays your Seller Account
Billing determines how money reaches you when Apostra clears payments for your
Seller Account. An administrator enters the payout bank details once — on the
**Payouts tab of the [Plan & Billing
page](/v2/buyer/billing/plan-and-billing)**, via `PUT
/api/v2/storefront/billing/payout-details`, or through the `set_payout_details`
agent operation — and Apostra pays you by bank transfer, net of the platform
fee and any additional fees on your billing config. A standalone Seller Account
administrator can enter these details directly. For a child Seller Account, an
administrator of its parent billing organization enters them; a child-only
administrator can see that billing is organization-managed but must ask a
parent-organization administrator to manage billing and payout details.
Setup is optional only for official Apostra sales-adapter Seller Accounts, where the downstream
platform relationship already has an external settlement agreement. A third-party sales
agent or a finished-product source with Listing is still a normal Seller Account and does not
change settlement. A normal Seller Account uses Apostra clearing, so payout details are
required — but only to get **paid**. The `billing_setup` readiness check is advisory, not a
go-live blocker: a Seller Account can activate and start transacting with payout details missing.
Funds still accrue against every booking; they simply cannot be disbursed until payout
details are on file. A parent-organization administrator can add them any time from the
Payouts tab, `PUT /api/v2/storefront/billing/payout-details`, or
`set_payout_details` — activation never waits on this step.
All examples use the legacy v2 `storefront` base URL for Seller Accounts:
```
https://api.apostra.com/api/v2/storefront
```
Authenticate every request with `Authorization: Bearer $SCOPE3_API_KEY`.
## Seller-specific billing mandates
A seller billing mandate records the commercial relationship that lets one
Seller Account bill for one exact advertiser or a finite advertiser set that a
Seller Account administrator reviewed. It is separate from advertiser access,
Organization membership, Campaign authority, seller admission, and execution
readiness. Those independent systems may still allow access or proposal setup
while a mandate is pending, failed, held, expired, or revoked; this API does not
decide either permission.
Each immutable mandate revision names the seller/payee, the canonical operator,
the liable payer, the payment-authority holder, the billing party and mode, a
typed provider-neutral internal invoice- or payment-authority evidence
reference, currency, terms, limits, effective dates, provenance, and the
complete canonical advertiser identity snapshot, including the conditional
buyer-selected timezone. The numeric advertiser ID is only a lookup pointer; it
does not replace the AdCP advertiser natural key or its identity revision.
Seller Account administrators can use these endpoints:
* `GET /api/v2/storefront/billing-mandates`
* `POST /api/v2/storefront/billing-mandates`
* `GET /api/v2/storefront/billing-mandates/{mandateUid}`
* `PUT /api/v2/storefront/billing-mandates/{mandateUid}`
* `PUT /api/v2/storefront/billing-mandates/{mandateUid}/readiness`
Creating or revising a mandate leaves readiness at `pending`. A readiness update
uses both the expected mandate revision and expected readiness revision so a
stale decision cannot win a race. `billingMandateReady` is true only when the
exact current mandate is active, effective, `ready`, scoped to the exact
advertiser, and still matches current canonical identity and seller-relationship
evidence. It is necessary mandate evidence for a later composing workflow; it
is never complete billing, proposal, Campaign, execution, or spend authority.
In particular, it does not prove that an actual funded or invoice rail exists.
Any future consumer must repeat the mandate check in the same transaction that
claims an external effect and independently prove every other gate. Revocation,
expiry, identity drift, sponsorship suspension, failure, or hold removes this
evidence without deleting delivery, invoice, Campaign, mandate, or audit
history. It cannot recall an external effect that was already claimed.
Every reference is a canonical lowercase typed internal ID:
`seller_payee:<uuid>`,
`liable_payer:<uuid>`, `payment_authority_holder:<uuid>`,
`commercial_terms:<uuid>`, a provenance ID matching its declared kind,
and exactly one of `seller_invoice_authority:<uuid>`,
`interchange_invoice_authority:<uuid>`, or
`interchange_payment_authority:<uuid>` for the matching billing route.
These are internal evidence IDs, never provider tokens. Caller-authored
reasons and readiness explanations also reject recognizable card,
bank-account, wallet, and provider-credential literals before they can enter
immutable history. There are no structured credential fields, and credentials
or bank-account details must never be placed in free text; semantically
unknowable bare identifiers are not treated as credentials. The API never
returns structured payment details or Organization payment methods. A card is
controlled by the liable payer or payment-authority holder, never by an
Advertiser. Advertiser access cannot view or change payment details, and
Apostra never borrows an Organization card for seller self-service.
`seller_direct_invoice` means the seller invoices its liable payer directly. It
does not mean Apostra has card custody, funds media, or carries the
receivable. `interchange_cleared` records a distinct commercial mandate, but
these endpoints still do not implement collection, invoice, wallet, payout, or
ledger execution. Those rails require their own supported workflow.
Mandates for two sellers remain independent even when their advertiser access
looks similar. The service does not infer seller, payer, operator, relationship,
or mandate authority from account ownership, Organization membership, email or
domain (including Gmail), a name, CRM record, signup source, CNAME, or stored
Organization card.
## Organization IU plan and Rate Card
**Plan & Billing → Plan & pricing** is the Seller Account view of your
organization's one [Effective IU Rate Card](/v2/buyer/billing/organization-iu-rate-card).
Buyer activity, Seller Account
work, Murph, and every other IU-rated workload use the same plan, corporate
pricing adjustment, rollover policy, and wallet. Your Seller Account does not have a separate
plan. If your organization contracts a platform license for governance,
integrations, support, or SLA, that license appears as an overlay on the same IU
plan rather than another wallet.
A Seller Account that uses another company's agent does not purchase that company's
`operate-agents-for-clients` entitlement. The agent operator purchases the right
for its own Partner organization, while each client billing organization keeps
its own IU plan and each Seller Account keeps its own media-settlement terms. See [Partner Program and agent
operations](/v2/storefront/inventory-sources/partner-account) for the operator,
client-authorization, and certification boundaries.
The standard Organization IU Rate Card is published in staging for a
controlled pilot and visible only to invited organizations. It remains
unpublished in production until the pricing and governing terms are approved.
Invited staging organizations can review and accept the exact Rate Card,
including its 100-IU setup-credit terms. Enrolled organizations may also see
the accepted included-IU allocation, observed usage, and a display-only
forecast. Transactional balance drawdown, entitlement enforcement, invoices,
payment collection, and renewal charging remain off. Existing accepted
media-pricing arrangements are unchanged.
Without a monthly distribution plan, a Seller Account keeps Listing connected
to its third-party sales agent. Listing has no monthly commitment. Saving,
enabling, and evaluating AI Business Rules is not an IU-rated activity today;
other qualifying activity remains governed by the organization's accepted IU
Rate Card. Listing + Distribution is available only when an approved Rate Card
publishes it, and the exact package price appears in Plan & billing before
acceptance.
The current staging-only IU pilot uses these planning values:
| Plan | Monthly commitment | Included IUs | Overage |
| ------------- | -----------------: | -----------: | ------: |
| Pay as you go | \$0 | 0 | \$5/IU |
| 250 | \$1,000 | 250 | \$5/IU |
| 1,000 | \$3,000 | 1,000 | \$5/IU |
These figures are the **standard USD list**, agreed on 2026-07-22 and not yet
published in production. Prices are set per currency rather than converted, so a
plan in EUR, GBP, or AUD is its own published number and not this figure at an
exchange rate — read your own Effective Rate Card if it is not in USD. A
corporate discount, a negotiated package, or a customized Offer replaces the
list entirely. The current Rate Card activity schedule has exactly three
published activities; see the [Organization IU Rate
Card](/v2/buyer/billing/organization-iu-rate-card#complete-activity-schedule).
After a separate production
billing launch, commitments will be billed at the start of each monthly period,
while pay-as-you-go usage and committed-plan overages will be billed after the
period. Staging publication and acceptance do not start those charges. Pay as
you go provides no included monthly IU allocation. On a committed plan, unused
included IUs carry into the next
month up to 50% of the plan's included quantity (125 on the 250 plan and 500 on the
1,000 plan), then expire; promotional credits never roll over. If your
organization has an authorized corporate discount, the plan-selection task
shows both list and effective prices before you confirm. That discount applies
once across the organization; it is not a Seller Account-only discount.
## Agentic Media Company plan catalog
This is the canonical customer-readable description of the current standard
Agentic Media Company defaults used to author new Rate Card offers. These
defaults are not available for production purchase until an approved Rate
Card publishes them. Plan & Billing shows the exact currency price, access,
payment terms, and effective dates before acceptance. An existing accepted
plan keeps its snapshotted terms until its documented successor flow takes
effect.
A seller first chooses who operates its sales agent. **Listing Only** and
**Listing + Distribution** keep a seller-owned or third-party Sales Agent in
control. **Merchandising** and **Merchandising + Distribution** use Apostra's
hosted Merchandising Agent. "Pay as you go" describes Merchandising's usage
price; it is not a separate plan name.
| Plan | Included access | USD | EUR | GBP | Initial term |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------: | ----------------------: | ----------------------: | -------------: |
| **Listing Only** | Apostra listing, seller-provided Sales Agent connection, shared Campaign and media-buy operations, no-spend sandbox workflows, and AI Business Rules | Free | Free | Free | 12 months |
| **Merchandising** | Listing plus Apostra's Merchandising Agent, Demand Inbox, product-marketing corpus, Pitch Composer, and Seller Account self-service | \$5/IU | €4.50/IU | £4/IU | 1 month |
| **Listing + Distribution** | Listing Only plus public listing distribution, one customer-owned CNAME, the external AdCP buyer campaign spine, unlimited self-serve Advertisers, and one customer-branded AdCP endpoint | $3,000/month + $4/IU | €2,750/month + €3.75/IU | £2,500/month + £3.50/IU | 12 months |
| **Merchandising + Distribution** | Merchandising plus public listing distribution, one customer-owned CNAME, the external AdCP buyer campaign spine, unlimited self-serve Advertisers, and one customer-branded AdCP endpoint | $3,000/month + $4/IU | €2,750/month + €3.75/IU | £2,500/month + £3.50/IU | 12 months |
| **Enterprise — Listing** | Listing + Distribution with only the negotiated integration, support, service, and optional customer-branded ChatGPT app terms stated in the accepted offer | Custom | Custom | Custom | Accepted offer |
| **Enterprise — Merchandising** | Merchandising + Distribution with negotiated terms; this is the only new-plan path that includes Custom modular sources | Custom | Custom | Custom | Accepted offer |
Standard Merchandising excludes public distribution, self-serve Advertiser
management, and Custom modular sources. The two standard Distribution plans
exclude Custom modular sources and the customer-branded ChatGPT app. Enterprise
includes only the Custom options written into the accepted offer.
All four standard plans use standard support. Distribution also includes
bounded activation help for one CNAME and endpoint. After the initial term,
each standard plan renews automatically one month at a time, requires 30 days'
notice of non-renewal, and has no termination for convenience. Recurring
commitments are billed at the start of the monthly period, IU usage is billed
at period end, payment terms are 30 days, and the current supported collection
methods are ACH, card, and invoice. Standard plans have no included IU
allocation or rollover. Prices are set independently per currency rather than
converted at an exchange rate.
A plan's public or private label controls only where the plan can be selected;
it does not determine whether the plan renews. The renewal cadence and notice
period shown in Plan & Billing and in your accepted offer are the terms that
apply. A private plan can renew automatically when those terms say it does, and
a public plan can be configured not to renew automatically.
Saving, enabling, and evaluating AI Business Rules is not an IU-rated activity.
The current Rate Card activity schedule has exactly three published activities;
see the [Organization IU Rate
Card](/v2/buyer/billing/organization-iu-rate-card#complete-activity-schedule).
Your accepted Rate Card, not these offer defaults, is the authority for charges.
The same wallet funds the three current Rate Card activities: a completed
Apostra merchandising cycle is 1 IU, Enhanced Reporting is 4 IUs per exact
connected account per billing period after its control is enabled and its
existing reporting subscription completes a successful sync, and a qualifying
non-social Interchange media buy is 1 IU per
billing period with positive impressions or spend. Your accepted Rate Card is
what prices each activity. No money is charged yet — charging is switched on per
organization, never silently. See the [Organization IU Rate
Card](/v2/buyer/billing/organization-iu-rate-card#complete-activity-schedule).
Media-buy qualification follows the latest authoritative delivery totals for the
original billing period. A correction that leaves both impressions and spend at zero
removes a provisional IU before invoicing; after invoicing, it goes through the normal
auditable one-IU credit or reversal process against that original period. Later positive
evidence may reinstate the same unit once, never add a second unit for the same buy and
period.
When an effective Rate Card makes the offer available, a billing organization
receives one automatic credit of 100 IUs on its first IU acceptance. Existing
customers qualify too. The credit is valid for exactly 60 elapsed days from the
acceptance commit, never a number of billing cycles, and any IU-priced activity
in the organization's shared wallet can use it. Seller Account provisioning may
finish asynchronously without moving that expiry window, and later acceptances
or Seller Accounts do not create additional credits. It never rolls over or stacks.
An optional promotion
or referral code can attribute that same credit and may carry an authorized
price or access adjustment, but it does not add another 100 IUs or change the
setup credit's value or expiration. The adjusted Effective Rate Card is shown
before acceptance. Apostra issues these codes; Seller Account operators
cannot create them, and a referral code records attribution only—it does not
promise a reward or payment.
When an organization IU plan is active, the page shows its snapshotted prices
and term. A later Rate Card or discount change does not rewrite those accepted
terms. **Contracts & orders → IU plan history** retains each accepted plan record,
including its Rate Card version, list and effective prices, discount,
acceptance source, and term. The same history appears from buyer and Seller Account
entry points.
## Accepting a private offer for the next term
If Apostra issues your organization a negotiated private offer while an IU plan
is active, an organization administrator can review and accept it for the next
term. Plan & Billing shows the current plan and the upcoming offer separately,
including the exact price, included IUs, overage, rollover, and effective date.
Accepting the offer does not reprice, shorten, refund, or prorate the current
term. The accepted offer starts when the current term ends and becomes the
organization's active IU plan at that boundary. No further action is required
after acceptance.
You can accept only one offer for an upcoming term at a time. After acceptance,
you cannot change renewal or select another plan until the new term starts. If
your organization has not been issued a private offer, nothing changes and no
action is required.
Standard public plans and private offers marked **pin exact** renew one month at a time on the exact accepted plan and
price snapshots. Each renewal creates a new immutable history entry linked to
the prior term. A newer Rate Card, a changed discount, or a private plan never
silently replaces those terms; it requires the applicable notice and successor
flow. A private offer marked **review required** does not auto-renew. While renewal processing is healthy, the new history entry normally
appears about one minute after the monthly boundary; its effective start remains
contiguous with the prior term.
An organization administrator can choose **End plan at term** before the change
cutoff shown in Plan & Billing. This does not shorten or refund the accepted
term: the plan remains active through its displayed end date, then the
organization returns to its no-paid-IU-plan posture because no automatic
successor is created. Plan & Billing shows the pending non-renewal and exact
effective timestamp, including timezone.
Ending the plan is organization-wide because every IU-rated workload shares
it. It does not terminate your platform agreement or change an existing
accepted media-pricing arrangement. If you want to stop only Seller Account merchandising or another
capability, disable that capability without ending the shared plan.
Before the same cutoff, an administrator can reinstate automatic renewal. That
reinstatement is recorded as a new audit event; it does not erase the earlier
cancellation. Once the cutoff has passed or a successor term already exists,
the prior term can no longer be changed. Apostra operators can inspect the same
history, but cannot bypass the governing agreement's cutoff or rewrite an
accepted term.
Apostra retains the complete renewal audit trail. The history beside the current
controls shows the 500 most recent decisions. Each entry is labeled **Renewal
target** or **Earlier term**, so an instruction from an earlier term cannot look
like a decision affecting the term being managed.
If the accepted plan cannot renew on its exact current terms—for example,
because the Rate Card was terminated or a different discount now requires an
explicit successor—Plan & Billing says automatic renewal is unavailable. It
does not promise a renewal the billing worker cannot create. You can still
record **End plan at term**; reinstatement becomes available only after the
exact renewal is eligible again.
The page also shows the next action supplied by the billing service. **Choose an
IU plan** opens the shared organization plan-selection task after an effective
Rate Card is published. If the governing Terms of Service have not been
accepted, the Terms of Service action comes first.
When Apostra has set your organization up on standard terms but nobody has
accepted them yet, Plan & Billing shows **Accept the platform terms** and
`get_billing_account` reports `plan.contractStatus: "awaiting_acceptance"`. The
contract and any rate card negotiated at setup are real and take effect the
moment an administrator of the organization accepts — Apostra does not accept on
your behalf. Until then the Seller Account cannot transact. Accounts that inherit
the organization's contract cannot accept for themselves; one administrator on
the organization accepts, and its accounts are unblocked.
Your confirmation applies only to the exact Rate Card version and prices shown.
If that offer changes before confirmation, the task reloads the latest version
and requires you to review and confirm it again. Only a verified organization
administrator can accept. Buyer and Seller Account IU activity use the resulting
same accepted plan; existing accepted media pricing stays separate and is not changed
by the IU plan.
For Free Seller Accounts included in the Rate Card pilot, a published offer can
prompt a review from any Apostra app page. The Terms of Service step comes
first. **Review plans** opens the existing plan review; an administrator must
still choose a plan and explicitly confirm acceptance. Other members see
**Ask your admin**, without the commercial terms. **Not now** returns to your
work and allows the prompt to appear in a later app session.
The task also offers **Continue without a paid plan** and **Decide later**.
Continuing without a plan suppresses the automatic next-login prompt only for
the exact Rate Card revision you reviewed; a successor revision may prompt
again. Deciding later permits the prompt in a later app session. Neither choice
removes the manual **Choose an IU plan** action from Plan & pricing while the
offer remains current, so you can return at any time.
## How you get paid
Apostra collects payment from the buyer, deducts the fees on your billing
config, and pays the remainder to your bank account by bank transfer in your
payout currency. Payout runs are executed by Apostra finance team — there is
no self-serve withdrawal step, and you do not need to hold a balance anywhere.
Each transfer carries a reference so you can reconcile it against your media
buys.
Today settlement is sequential: Apostra pays you after it receives the
buyer's corresponding payment, subject to the applicable payment terms.
Each payout account clears one currency: for Apostra-cleared Seller Accounts, your
payout `currency` must match your Seller Account's settlement currency
(`defaultCurrency`). The `settlement_currency_match`
[readiness check](/v2/storefront/tasks/get-readiness) blocks go-live on a
mismatch.
## Why Apostra needs your bank details
Bank details are how Apostra pays you — nothing else. A payout by bank transfer
needs:
* **Beneficiary name** (`beneficiaryName`) — the account holder exactly as your
bank knows it.
* **Beneficiary address** (`addressLine1`, `city`, `postalCode`, `countryCode`) —
required by banks for international transfers.
* **Account number or IBAN** (`accountNumber`) — where the money lands.
* **One bank identifier** (`bankIdentifierType` + `bankIdentifierValue`) — a
Fedwire/ABA routing number, CHIPS ABA, SWIFT-BIC, or local bank code, so the
transfer routes to the right bank.
* **Payout currency** (`currency`) — the currency your account accepts.
Apostra uses these details only to execute payouts. They are never shared with
buyers and never appear in discovery or media-buy responses.
## What happens to your bank details
* Your account number is **encrypted at the application layer** (AES-256-GCM)
before it is written to the database — the database never holds a usable
plaintext value — with disk-level encryption beneath it.
* The account number (or IBAN) is **write-only**: once saved, it is never
displayed again. Reads — `GET /billing`, the `get_billing_info` operation,
and Plan & Billing → Payouts — return only the last four characters, so you can confirm
which account is on file without exposing it.
* To change accounts, submit the full payout details again; the previous
details are replaced.
## Multiple payout entities
A child Seller Account uses its organization's payout destination until a parent
organization admin creates a Seller Account-specific destination. In **Plan &
Billing → Payouts**, select the direct child Seller Account; through REST,
pass `?targetCustomerId=`. Child-only admins cannot create or change
payout destinations.
If your organization is paid through more than one legal entity — say an India
entity and a Brazil entity — register a payout bank account for **each entity
and payout currency** via `PUT /api/v2/storefront/billing/payees` (the
`set_payout_payee` agent operation, or **Plan & Billing → Payouts**
in the UI). Each payee carries its own beneficiary name and address, account
number, and bank identifier:
* **One bank account per entity per currency.** A payout account clears exactly
one currency, so an entity paid in two currencies registers two payees. The
`entityName` + `currency` pair identifies the payee; submitting the same pair
again updates it.
* **The beneficiary name must match the account holder — the legal entity
itself.** Banks reject transfers where the beneficiary on the wire doesn't
match the name on the account.
* Every payout destination is a payout entity, and exactly one is your
**primary**. The details you set with `set_payout_details` are the primary
entity — and like any other entity, it can hold a bank account per
currency.
* Reads are masked the same way for every entity: list them with
`GET /api/v2/storefront/billing/payees` (`list_payout_payees`) and you get
the last 4 characters of each account number, never the full value.
* Removing a payee is a bank-detail change control and is handled by Apostra
finance — contact support.
## Apostra-cleared vs seller-cleared
A media buy is settled one of two ways:
| Settlement | Who invoices the buyer | Available today |
| ------------------------------- | --------------------------------------------------- | -------------------------------------------- |
| **Apostra-cleared** (`agent`) | Apostra invoices the buyer and pays you | All normal Seller Accounts |
| **Seller-cleared** (`operator`) | You invoice the buyer under your existing agreement | Existing official sales-adapter arrangements |
Apostra-cleared settlement requires payout details on file before Apostra can
**disburse** what it clears — it has no way to pass a payment on without them. This does
not block **activation**: a normal Seller Account can go live and start transacting first,
accruing funds against every Apostra-cleared booking, and add payout details
afterward. Missing payout details do not silently change a normal Seller Account booking to
seller-cleared.
Today, every normal Seller Account booking is Apostra-cleared. Seller Accounts will
be able to choose seller-cleared settlement in a future release, but that option
is not configurable yet and is not selected per booking. Existing
official sales-adapter buys may be seller-cleared because those parties already
settle under an external agreement.
With seller-cleared settlement, Apostra does not deduct a seller-side media fee from the
publisher's invoice or payment. Any separate platform charge to the buyer is
not a deduction from the seller's invoice.
The seller **Media Buys** page shows the resolved method on each booking as
**Apostra-cleared** or **Seller-cleared**. A booking with no buyer-side record at all —
for example one placed by a third-party AdCP buyer, which never has a local Apostra record —
resolves its settlement method from the Seller Account's own current routing configuration,
since that is what actually determines it (spec §12). Only a booking that predates the
settlement-method record itself, and where a local buyer-side record positively shows no
method was ever captured, shows **Settlement method not recorded for this buy** — the
platform never overwrites what an existing legacy record shows with a later inference.
Apostra no longer uses Stripe for Seller Account payouts. If you set up
billing through Stripe Connect before, an administrator of your billing
organization must enter the bank details once in Plan & Billing → Payouts (or
via `set_payout_details`) before Apostra can disburse accrued funds — bank
details held by Stripe cannot be migrated. Nothing else changes: fees,
currency, and net terms carry over.
## Organizations and accounts
A parent organization admin can manage a direct child Seller Account by passing
`?targetCustomerId=` on billing endpoints; every request validates
the organization/account relationship. Requests authenticated only for a child
account cannot create or change payout destinations. A child inherits its
organization's payout destination until a parent admin creates a child-specific
override.
## Billing activity
The **Payout activity** section at the top of the Payouts tab on the org
Billing page shows payout runs as they happen — status, period, entity,
currency, amount, and date — via
[Get payout activity](/v2/storefront/billing/tasks/get-payout-activity). It's
empty until your first payout run; nothing is fabricated in the meantime.
## Task reference
`PUT /billing/payout-details` — bank account for payouts
`GET /billing` — fees, currency, net days, masked payout details
`PUT /billing/payees` — bank account per legal entity per currency
`GET /billing/payees` — masked payees on file
`PUT /billing` — fees, currency, net days (admin)
`GET /billing/accounts` — billing status across your organization's accounts
`GET /billing/payout-activity` — payout activity as it happens