> ## 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.
# Playbook selling guidance and rate cards
> The Playbook shows the current read-only rate card while the Library owns rate-card editing and version history.
## Overview
**Rate cards live in the Library.** The Playbook shows the current rate card
read-only. Use **Edit in Library** to open its typed **Rate card** document and
make changes there.
**Playbook pricing** is the set of pricing facts your Seller Account gives the
[Merchandising Agent](/v2/concepts/storefront-agent) so it prices products the
way you would. Instead of a static rate card returned to every buyer, you hand
over the *anchors* — "rich media runs around a \$30 CPM", "never quote CTV below
\$22", "holiday inventory carries a premium" — and the agent applies them as it
composes a proposal for the buyer in front of it.
A pricing fact is deliberately **lightly structured**: a short label, a
natural-language condition describing when it applies, and a price anchor (target,
floor, and/or ceiling). It is reasoning context for the agent, not a rigid product
template. This is where the numbers from your rate card, media kit, or a setup-call
conversation live.
These are **your** product-pricing facts, separate from any Apostra contract rate
card. They price the inventory you sell through your Seller Account.
## What the Playbook needs from you
Give the Merchandising Agent the durable inputs it needs to pitch your
inventory consistently. Start with the required inputs, then add the
recommended evidence that makes its proposals more specific.
### Required
* **Business rules — what you accept.** Your acceptance policy tells the agent
which briefs and buyers are on policy, so it can decline demand that does not
fit your business.
* **Rate card / pricing anchors — how you price.** Floors, targets, ceilings,
and the conditions that apply to them give the agent a defensible price for
each discovery response.
### Recommended
* **Media kit — how you're represented.** Your listing and business profile
give the agent the seller facts it needs to represent your inventory clearly.
* **Selling guidance — how you package and select.** Versioned Playbook
guidance tells the agent how to name, package, and choose products for a
brief.
* **Past proposals and sales decks — what wins.** Product Marketing material
gives the agent examples of your proven positioning and proposal language.
Each input sharpens how the agent responds to a buyer brief; you can add or
update it over time as your inventory and sales strategy change.
The Playbook keeps selling guidance alongside a read-only rate-card summary.
The Library owns rate-card editing and its version history.
## What a rate card holds
The portable **Playbook** Page lets you review structured pricing alongside
versioned selling guidance in any MCP Apps host. Edit prices in the linked
Library **Rate card** document. The same configuration remains available through
the legacy v2 Seller Account API, in its
`compositionPricing` field —
a `StorefrontCompositionPricing` object:
| Field | Type | Description |
| - | - | - |
| `rateCard.currency` | ISO 4217 string | Default currency for the facts below (e.g. `USD`) |
| `rateCard.facts` | array | Up to 500 pricing facts (below) |
| `targetPercentile` | `p50` \| `p75` \| `p90` | **Deprecated.** Historical clearing percentile, retained for explainability only — it no longer sets prices. Pricing is value-led, bounded by your floors and ceilings |
Each **pricing fact** (`StorefrontPricingFact`):
| Field | Type | Description |
| - | - | - |
| `id` | string | Stable operator-facing id. Preserved across rewrites when the fact means the same thing |
| `label` | string | Short display label (e.g. "Rich media packages") |
| `appliesWhen` | string | Natural-language condition. Intentionally not a rigid template — the agent uses it as reasoning context |
| `pricing.targetPrice` | number | The price you'd like to land at |
| `pricing.floorPrice` | number | The lowest you'll quote. A quote is never composed below it |
| `pricing.ceilingPrice` | number | The most you'd quote (must be ≥ `floorPrice`) |
| `strength` | `hard_floor` \| `default` \| `guidance` | `hard_floor` is a must-not-go-below constraint; `default` is the preferred pricing anchor; `guidance` is advisory context only |
| `hints` | object | Optional structured hints for deterministic matching. Missing hints are fine |
| `hints.formatDimensions` | `{ width, height }[]` | Creative sizes this fact applies to. A pair matches when a selected canonical option equals it, lists it in `sizes[]`, or includes it within min/max bounds |
| `provenance` | string | Where the fact came from (e.g. "Uploaded 2026 rate card, page 3") |
| `notes` | string | Rationale or caveats for operators and Murph |
Every fact must carry at least one of `targetPrice` or `floorPrice`.
For a size-specific rate-card line, set `hints.formatDimensions` rather than
relying on words in the label. For example, a 300×250 fact uses
`"formatDimensions": [{ "width": 300, "height": 250 }]`. When one composed
product selects several sizes, every fact whose dimensions are selected can
apply; the highest applicable floor and target govern the product's single
price. A fact scoped to an unselected size does not affect the price or its
provenance.
For compatibility, an unhinted fact can still match when its full normalized
label appears in a bundle name. Individual bundle-name words are not used for
fallback matching, which prevents seller identity from activating an unrelated
fact.
## Where you set it
* **In the Library** — open your **Rate card** document to edit, preview, and
commit price rows. The Playbook's **Edit in Library** action opens this
document directly.
* **API integrations** — existing `save_playbook` and v2 settings writes still
accept pricing facts. Each write saves a new Library Rate card version.
* **REST** — `PUT /api/v2/storefront` with a `compositionPricing` object. The full
nested structure is returned on `GET /api/v2/storefront`.
* **On `/mcp/v3`** (preview) — `save_playbook` writes pricing, the
versioned selling guidance, and the brand/operator
[house discounts](/v2/storefront/house-discounts/overview) that come off
those prices, because the Playbook is the one noun that owns how you sell.
There, each fact's `pricing` object uses snake\_case names on both
`save_playbook` and `get`: AdCP's `pricing_model`, `currency` and
`floor_price`, plus `target_price` and `ceiling_price` in place of
`targetPrice` and `ceilingPrice`.
See [Seller pages](/v2/setup/seller-pages).
## How pricing reaches discovery
When a buyer discovers products, the Merchandising Agent reads your pricing facts,
matches them against the brief, and anchors each composed product's price
accordingly. The price surfaces on the discovered product as:
* `cpm` — the quoted price, in the pricing scope's currency.
* `currency` — ISO 4217, inherited from your `rateCard.currency` unless the buyer's
currency requires conversion.
* `pricingScope` — `public` (your open rate-card price) or `account` (a
buyer-specific price, e.g. after a [house discount](/v2/storefront/house-discounts/overview)).
Two guardrails always hold:
* **The wholesale floor wins.** Every quote is floored at the Seller Account's
wholesale cost. A pricing fact can raise or shape a price, but the agent never
composes a quote below cost.
* **Buyer currency must be accepted.** Discovery only returns priced products in a
currency on the Seller Account's accepted list; otherwise no products are returned
(see [cross-currency](/v2/concepts/cross-currency)).
## Playbook pricing vs. discounts
Playbook pricing sets your **base** pricing — what any buyer sees. To give a
*specific* buyer a better price, layer a discount on top:
Structured rate-card discounts keyed to a buyer's brand or operator.
Freeform per-buyer terms, notes, and operator-and-brand intersections.
## Related
Collect rate-card provenance alongside the rest of the publisher evidence pack.
How the agent turns what you have into a priced proposal.
The rules the agent follows when composing products.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.