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

# How IU billing works

> The whole path from a published price to an invoice you can check — with worked examples and a plan calculator

export const IuCalculator = () => {
  const [used, setUsed] = useState(300);
  const plans = [{
    name: 'Pay as you go',
    commitment: 0,
    included: 0
  }, {
    name: '250 plan',
    commitment: 1000,
    included: 250
  }, {
    name: '1,000 plan',
    commitment: 3000,
    included: 1000
  }];
  const overageRate = 5;
  const n = Number.isFinite(used) && used > 0 ? used : 0;
  const rows = plans.map(p => {
    const overageIus = Math.max(0, n - p.included);
    const cost = p.commitment + overageIus * overageRate;
    return {
      ...p,
      overageIus,
      cost,
      perIu: n > 0 ? cost / n : 0
    };
  });
  const cheapest = Math.min(...rows.map(r => r.cost));
  const money = v => v.toLocaleString('en-US', {
    style: 'currency',
    currency: 'USD',
    maximumFractionDigits: 0
  });
  const money2 = v => v.toLocaleString('en-US', {
    style: 'currency',
    currency: 'USD',
    minimumFractionDigits: 2
  });
  return <div className="not-prose rounded-xl border border-gray-200 bg-gray-50 p-5 dark:border-white/10 dark:bg-white/5">
      <label htmlFor="iu-calc-range" className="block text-sm font-semibold text-gray-900 dark:text-gray-100">
        Intelligence Units used in a month
      </label>

      <div className="mt-3 flex items-center gap-4">
        <input id="iu-calc-range" type="range" min="0" max="2000" step="10" value={n} onChange={e => setUsed(Number(e.target.value))} className="h-2 w-full cursor-pointer appearance-none rounded-full bg-gray-200 accent-emerald-700 dark:bg-white/10" />
        <input type="number" min="0" step="10" value={n} onChange={e => setUsed(Number(e.target.value))} aria-label="Intelligence Units used in a month" className="w-24 shrink-0 rounded-md border border-gray-300 bg-white px-2 py-1 text-right text-sm tabular-nums text-gray-900 dark:border-white/15 dark:bg-white/10 dark:text-gray-100" />
      </div>

      <div className="mt-5 grid gap-3 sm:grid-cols-3">
        {rows.map(r => {
    const best = r.cost === cheapest && n > 0;
    return <div key={r.name} className={'rounded-lg border p-4 ' + (best ? 'border-emerald-700 bg-white dark:border-emerald-500 dark:bg-white/10' : 'border-gray-200 bg-white dark:border-white/10 dark:bg-white/5')}>
              <div className="flex items-baseline justify-between gap-2">
                <span className="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">
                  {r.name}
                </span>
                {best && <span className="rounded-full bg-emerald-700 px-2 py-0.5 text-[10px] font-bold uppercase tracking-wide text-white">
                    Cheapest
                  </span>}
              </div>

              <div className="mt-2 text-2xl font-bold tabular-nums text-gray-900 dark:text-gray-100">
                {money(r.cost)}
                <span className="text-sm font-normal text-gray-500 dark:text-gray-400"> / mo</span>
              </div>

              <dl className="mt-3 space-y-1 text-xs text-gray-600 dark:text-gray-400">
                <div className="flex justify-between gap-2">
                  <dt>Commitment</dt>
                  <dd className="tabular-nums">{money(r.commitment)}</dd>
                </div>
                <div className="flex justify-between gap-2">
                  <dt>Included</dt>
                  <dd className="tabular-nums">{r.included.toLocaleString('en-US')} IUs</dd>
                </div>
                <div className="flex justify-between gap-2">
                  <dt>Overage</dt>
                  <dd className="tabular-nums">
                    {r.overageIus.toLocaleString('en-US')} IUs · {money(r.overageIus * overageRate)}
                  </dd>
                </div>
                <div className="flex justify-between gap-2 border-t border-gray-200 pt-1 dark:border-white/10">
                  <dt>Effective per IU</dt>
                  <dd className="tabular-nums">{n > 0 ? money2(r.perIu) : '—'}</dd>
                </div>
              </dl>
            </div>;
  })}
      </div>

      <p className="mt-4 text-xs text-gray-500 dark:text-gray-400">
        Overage bills at $5.00/IU on every plan. This estimate assumes nothing carried in from the
        previous period — rollover only reduces the total. It does not include any corporate
        discount, promotion, private package, or platform-license fee on your Effective Rate Card,
        or any media spend.
      </p>
    </div>;
};

This page is the walkthrough: what happens between a published price and a charge on
your account, what you do at each step, and **what you can check afterwards**. If you
only want the price list, the
[Organization IU Rate Card](/v2/buyer/billing/organization-iu-rate-card) has it.

<Note title="Availability">
  The IU plans and prices below are agreed and published for a controlled
  staging pilot. They are **not published in production**, so no organization
  needs to accept them in production today and no IU charges are being made.
  Existing accepted media-pricing arrangements are unchanged. When your
  organization is invited, your confirmation shows the exact version, term, list
  price, and effective price that would apply to you.
</Note>

## The short version

* **Connecting costs nothing.** Connecting an account, discovering it, and mapping it
  to an advertiser never consume IUs.
* **You pay for successful work**, priced by an activity term on the Rate Card you
  accepted. Attempts, retries, and our own failures are free.
* **One plan for the whole organization.** Buyer activity, Seller Account work, and Murph
  draw from the same plan and the same wallet.
* **A commitment lowers the per-IU price.** Usage beyond your included IUs bills at
  the metered rate.
* **Every charge traces back to a term you accepted**, and you can read that trail
  yourself — see [checking our numbers](#checking-our-numbers).

## The seven steps

<Steps>
  <Step title="A price is published">
    Apostra publishes an immutable Rate Card revision: plan sizes, monthly
    commitments, included IUs, activity prices, currencies, and an effective date.
    Publishing a revision does not commit anyone to anything.

    **You do:** nothing.
  </Step>

  <Step title="Your Effective Rate Card is resolved">
    Your organization gets one **Effective Rate Card** — the complete commercial
    result for you. It starts from a published plan and can include one authorized
    adjustment: a corporate discount, a promotion or referral code, a negotiated
    private package, or a customized Offer based on an exact Rate Card plan.

    **You can check:** the list price, the adjustment, and the effective price appear
    side by side before you confirm. Discounts do not stack, and only one complete
    offer is effective at a time.
  </Step>

  <Step title="An administrator accepts it">
    Only a verified organization administrator can accept a plan. An agent, API key,
    service account, or support session cannot make that commitment on your behalf.

    Acceptance snapshots the exact agreement, revision, plan, adjustments, prices,
    actor, and time into an immutable **acceptance record**. A later price change never rewrites
    it — changes arrive as a new offer you can review.

    **You do:** review and accept, decline for that revision, or decide later. All
    three are recorded; none of them is assumed.
  </Step>

  <Step title="You give us a way to collect">
    Either save a card, or be set up for invoicing on your existing terms. This is
    separate from accepting a plan: accepting a plan does not by itself start
    charging, and charging is switched on per organization, never silently.

    **You do:** add payment details in **Settings → Plan & Billing**.
  </Step>

  <Step title="You use IU-rated capabilities">
    When a capability has a published IU price, successful use draws from your plan.
    Your wallet shows the balance, what consumed it, and a projection for the rest of
    the period.

    Usage draws from expiring credit lots first, then rolled-over IUs, then the
    period's included allowance, then overage.

    **You can check:** usage appears on **Usage & credits** as it happens, attributed
    to the activity that caused it.

    The activity list and daily trend are measured in IUs and reconcile to the
    wallet's **IUs used** total. They do not come from Apostra's cost to run an AI
    provider. A capability can incur an internal provider cost without consuming
    a priced IU activity; in that case it does not appear as customer IU usage.
  </Step>

  <Step title="The cycle closes into an invoice">
    Each charged month produces one numbered fee invoice: plan commitment, overage as
    IUs × your rate, and payments applied. Commitment and overage are switched on
    separately, so an invoice can carry the commitment while overage is still only
    accruing — see [billing cycle and fee
    invoices](/v2/buyer/billing/organization-iu-rate-card#billing-cycle-and-fee-invoices).

    **You can check:** invoice numbers are sequential with no gaps, and an issued
    invoice's charges never change. Payments are appended as they settle.
  </Step>

  <Step title="You reconcile it — and so do we">
    The invoice, the usage that produced it, and the term that priced it are the same
    three records we reconcile internally. Nothing on your invoice should be
    unexplainable from your own reads.

    **You can check:** see [checking our numbers](#checking-our-numbers).
  </Step>
</Steps>

## What consumes IUs, and what never does

**One thing consumes IUs:** successful activity that has a published price on the Rate
Card your organization accepted.

New Rate Cards use the three published v4 activities on the
[Organization IU Rate Card](/v2/buyer/billing/organization-iu-rate-card#complete-activity-schedule):
Brief response, Enhanced Reporting, and Interchange media buy. Older
accepted Rate Cards retain their own immutable activity terms.

Everything below is always free, and stays free whether or not you have a paid plan:

* connecting an account or an ad server;
* discovering accounts and mapping them to advertisers;
* reading, reporting, and exporting your own data, unless you enable Enhanced
  Reporting for a connected account;
* approving something we proposed;
* retries, routing, cache hits, and no-op work;
* anything that failed; and
* work caused by an Apostra defect.

The order of operations is fixed: **zero-rate first, then credits, then bill.** If it
is ambiguous whether something should be charged, it resolves free.

### The v4 activity schedule

New integrations can read the current three-activity catalog from
`GET /api/v2/billing/iu-rate-card/v4`. The response carries both the accepted
`activityTerms` and the resolved `activitySchedule` so a client can show the exact
price and boundary that govern the organization:

| Activity code                                | Customer-facing activity | Starting rate and boundary                                                                                                                                                              |
| -------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMPLETED_INTERCHANGE_MERCHANDISING_CYCLE`  | Brief response           | 1 IU for one completed Apostra merchandising cycle                                                                                                                                      |
| `SOCIAL_ACCOUNT_INTELLIGENCE_BILLING_PERIOD` | Enhanced Reporting       | 4 IUs for one connected account in a billing period after its account-level Enhanced Reporting control is enabled and that account's existing reporting subscription successfully syncs |
| `INTERCHANGE_MEDIA_BUY_BILLING_PERIOD`       | Interchange media buy    | 1 IU for one qualifying non-social media buy in a billing period with positive impressions or spend                                                                                     |

The unversioned, `/v2`, and `/v3` reads remain compatibility boundaries for clients
that use the older activity vocabulary; they do not add the v4 rows. Opt in to
`/v4` before depending on these codes. An accepted Rate Card still freezes its
catalog version and resolved prices, so reading the newer endpoint never rewrites
an earlier agreement.

For Interchange media buys, the latest authoritative delivery totals control the
result. If both impressions and spend become zero before invoicing, the provisional
IU is removed. After invoicing, the same correction produces an auditable one-IU
credit or reversal against the original period. A later positive correction can
reinstate that same unit once, but cannot create a second unit for the buy and
period. See the [complete activity schedule](/v2/buyer/billing/organization-iu-rate-card#complete-activity-schedule)
for all qualification details.

## Plan shapes

| Plan          | Monthly commitment | Included IUs | Price per included IU |     Overage |
| ------------- | -----------------: | -----------: | --------------------: | ----------: |
| Pay as you go |                \$0 |            0 |                     — | \$5.00 / IU |
| 250           |            \$1,000 |          250 |                \$4.00 | \$5.00 / IU |
| 1,000         |            \$3,000 |        1,000 |                \$3.00 | \$5.00 / IU |

Two break-even points fall out of those numbers, and they are worth knowing before
you choose:

* Above **200 IUs a month**, the 250 plan costs less than pay as you go.
* Above **650 IUs a month**, the 1,000 plan costs less than the 250 plan.

On a committed plan, unused included IUs carry into the next monthly period only, up
to **50% of that next period's included quantity** — at most 125 IUs on the 250 plan,
500 on the 1,000 plan. Carried IUs expire after that one period and never accumulate
again. Pay as you go has no allocation to carry.

**This is the standard list, not everyone's price.** Your Effective Rate Card is the
authority. An authorized corporate discount, a promotion or referral code, a
negotiated private package, or a customized Offer replaces these figures, and Plan &
Billing shows the list price and the effective price side by side before you confirm.
If your organization has been quoted something else, that quote — once it is an
Effective Rate Card you accept — governs your charges, not this table.

**Prices are set per currency, never converted.** The figures above are the USD list.
A Rate Card revision carries a separately published price for each supported
currency, so a plan in EUR, GBP, or AUD is **not** the USD figure at an exchange rate
— it is its own published number. Your organization's currency is fixed on the
revision you accept, and your invoice, charge, and wallet all use it. Read the
numbers on your own card, not these, if your card is not in USD.

**And these are today's standard figures.** This table describes the standard model as
agreed on 2026-07-22. Standard prices can change, and when they do they arrive as a
**new published revision** — never as an edit to a revision anyone accepted. Your
acceptance record snapshots the exact version, term, and prices you agreed to, so a change to
this table does not change what you are paying: you would see a successor offer and
decide whether to accept it.

## Calculator

Enter the IUs you expect to use in a month. The cost of each plan is shown, with the
cheapest one marked.

<IuCalculator />

This computes the **standard USD list** and is not a quote. If your organization has a
corporate discount, a negotiated package, a customized Offer, or a card in another
currency, put the numbers from your own Effective Rate Card into the formula below —
prices are published per currency rather than converted from USD.

The formula, if you would rather compute it yourself or have an agent do it:

```
cost = commitment + max(0, used − (included + carried_in)) × 5.00
```

`carried_in` is the smaller of last period's unused included IUs and half of this
period's included quantity.

## Worked examples

<AccordionGroup>
  <Accordion title="A seller trying things out — pay as you go">
    Uses 12 IUs in the month.

    ```
    commitment          $0
    metered  12 × $5.00 $60.00
    ──────────────────────────
    invoice             $60.00
    ```

    No commitment, no included allocation, nothing to roll over. Every IU is \$5.00.
  </Accordion>

  <Accordion title="A buyer who went over — the 250 plan">
    Committed to 250 IUs for \$1,000. Uses 310 IUs, with nothing carried in.

    ```
    commitment              $1,000.00
    included                250 IUs — covered
    overage   60 × $5.00      $300.00
    ────────────────────────────────
    invoice                 $1,300.00
    effective per IU            $4.19
    ```

    Because they are on a card, the \$300 of overage is charged when it crosses the
    account's threshold during the month rather than arriving as a surprise at close.
    The remainder settles when the cycle closes.
  </Accordion>

  <Accordion title="A quiet month, then a busy one — rollover">
    On the 250 plan. Period 1 uses 180 of 250 IUs.

    ```
    period 1   used 180 of 250      unused 70
    carry      min(70, 125) = 70 IUs into period 2
    ```

    Period 2 has 250 included + 70 carried = 320 IUs before any overage. If they use
    300, the invoice is the \$1,000 commitment and no overage. The 20 IUs left over
    from the carried lot expire — carried IUs do not carry again.
  </Accordion>

  <Accordion title="Your first plan — the 100-IU credit">
    A seller billing organization receives one **100-IU credit, valid for 60 days**,
    on its first IU plan acceptance. You do not have to be a new customer — if you
    have been with us a while and are accepting an IU plan for the first time, the
    credit is yours too.

    It can be spent on **any IU-priced activity**. The window is a fixed 60 days from
    your signup commit, not a number of billing periods, so it does not shift with
    your billing cycle and you never need to know where your cycle boundary falls.
    **Usage & credits shows the exact expiry date.**

    One credit per billing organization: later Seller Accounts do not create another. It
    does not roll over, has no cash value, and does not stack.
  </Accordion>
</AccordionGroup>

## Reading your invoice

Every charged month produces one numbered fee invoice on **Settings → Plan & Billing
→ Payment & invoices**, showing:

* the plan commitment, at the price fixed in your accepted terms;
* overage as a quantity of IUs multiplied by your plan's rate;
* payments applied, as they settle.

Two properties are worth relying on. **Invoice numbers are sequential with no gaps**,
so you can tell whether you have seen every invoice. And **an issued invoice's charges
never change** — a correction arrives as its own document, never as an edit to one you
have already received.

Organizations paying by card are charged automatically. Invoiced organizations receive
the fee invoice only and pay on their existing terms; no card charge is made.

### When a card payment settles before the cycle closes

A card payment can succeed during the month before its fee invoice is issued. The
payment stays attached to that exact billing cycle and is recorded as deferred until
the cycle closes. A retry or **pay now** recovery replaces the failed attempt with the
successful payment on the same cycle; it does not create a second cycle or detach the
payment from its usage.

When the cycle closes, Apostra issues its invoice from the frozen usage drawdown and
accepted plan terms, including payment applications for successful charges. Collected
payments are then recognized as revenue. Separately, Apostra's billing checks compare
those records with successful charges and invoice arithmetic for differences. If
charging is turned off after a payment was collected, no new charge is made, but that
paid cycle still closes and the accounting checks continue so the payment is not left
without an invoice.

For day-to-day billing, nothing changes: finance teams can use the numbered invoice and
its applied payments as their audit trail, while smaller teams can continue using Plan
& Billing without a new setup step.

## If a payment fails

A published recovery ladder applies: automatic retries on a schedule, email notices,
and a self-serve **pay now** action that clears the failed-payment status as soon as it
succeeds.

Plan & Billing reports an unresolved dunning-backed hold; reaching the account's cap
records a separate internal hold. In the current alpha, neither hold is consulted by a
production authorization path, so it does not automatically block new paid platform
activity. **Viewing your data, reporting, exporting, and fixing your payment method
remain available.**

## Checking our numbers

You should not have to take an invoice on trust. These reads are the same records the
charge was built from:

| To check                                 | Read                                                                   |
| ---------------------------------------- | ---------------------------------------------------------------------- |
| The exact v4 terms you accepted          | `GET /api/v2/billing/iu-rate-card/v4`                                  |
| Your plan, standing, and payment methods | `GET /api/v2/billing/account`                                          |
| Your invoices and their line items       | `GET /api/v2/billing/fee-invoices` and `/fee-invoices/{invoiceNumber}` |
| Invoice activity as it happens           | `GET /api/v2/billing/invoice-activity`                                 |

Authenticate with `Authorization: Bearer $SCOPE3_API_KEY`. Agents should use the typed
`open_iu_plan_task` and `get_billing_account` tools rather than reconstructing
this from generic calls.

The reconciliation you can do yourself: **the IU quantity on an invoice line should
equal the usage attributed to that activity for the period, priced at the rate on your
accepted terms.** If those three do not agree, that is a defect on our side — tell us and we
will explain the difference rather than adjust the invoice quietly.

## Two bills, kept separate

IUs price platform activity. Media spend and its accepted contract fee terms are a
separate commercial stream on a separate bill. Plan & Billing can show both, because
an organization may owe both, but neither replaces or silently amends the other.

## Related

<CardGroup cols={2}>
  <Card title="Organization IU Rate Card" href="/v2/buyer/billing/organization-iu-rate-card" icon="coins">
    The price list, adjustments, rollover, and acceptance in detail
  </Card>

  <Card title="Plan & Billing" href="/v2/buyer/billing/plan-and-billing" icon="gauge">
    The surface where you review terms, usage, and invoices
  </Card>

  <Card title="Pay by card" href="/v2/buyer/billing/concepts/pay-by-card" icon="credit-card">
    Saving a card, thresholds, and the recovery ladder
  </Card>

  <Card title="Media billing" href="/v2/buyer/billing/overview" icon="file-invoice-dollar">
    How media spend is invoiced, and where remittance details come from
  </Card>
</CardGroup>