Economic agreements
Bind one subscription to a pricing family with negotiated terms — confirm-gated CLI operations, never repo code.
An economic agreement binds one subject (a subscription) to one pricing family
with a specific binding mode and optional contract terms. Agreements are how a
bespoke discount, floor, cap, or pinned catalog version reaches one customer
without touching the public catalog. They are platform operations run through
the CLI, not declarations in business/.
Binding modes
--binding | Meaning | Follows releases? |
|---|---|---|
current | The live catalog version in each served release. | yes |
current_with_contract_terms | The live catalog plus this agreement's terms (discount, floor, cap, scope). | yes |
fixed_version | Exactly --policy-version <pricingPolicyVersionId>; require_amendment by definition. | no |
Two-step, confirm-gated
Every write previews first and commits only with the preview's token:
farthershore agreements create acme-llm \
--subject sub_01J... \
--binding current_with_contract_terms \
--policy pricing_llm \
--terms-json '{"percentDiscount":{"num":"1","den":"10"},"floorNanos":"500000000000","selectorScope":[{"kind":"catalog_item","item":{"provider":"acme","model":"acme-4"}}]}' \
--new-meter-policy adopt_at_current_rate \
--format json
The preview prints the resolved effect — which pricing rules the terms
touch, the resulting rating-context change, bounds violations — plus a
server-minted confirmationToken (agc_<effectDigest>.<exp>.<hmac>). Nothing
is written. Re-run the same command with --confirm <token> to commit. If the
inputs or the policy changed in between, the effect digest no longer matches
and the CLI refuses with AGREEMENT_CONFIRMATION_STALE before any write; the
server enforces the same gate.
farthershore agreements create acme-llm \
--subject sub_01J... \
--binding current_with_contract_terms \
--policy pricing_llm \
--terms-json '{"percentDiscount":{"num":"1","den":"10"},"floorNanos":"500000000000","selectorScope":[{"kind":"catalog_item","item":{"provider":"acme","model":"acme-4"}}]}' \
--new-meter-policy adopt_at_current_rate \
--confirm agc_... \
--idempotency-key <persisted-agreements-create-attempt-key> \
--format json
Amendments append a new contract-pricing version; they never edit one in place:
farthershore agreements amend acme-llm agr_01J... \
--terms-json '{"percentDiscount":{"num":"3","den":"20"},"floorNanos":"500000000000","selectorScope":[{"kind":"catalog_item","item":{"provider":"acme","model":"acme-4"}}]}' \
--effective-at 2026-09-01T00:00:00Z
Read commands:
farthershore agreements list acme-llm --subject sub_01J...
farthershore agreements show acme-llm agr_01J...
farthershore agreements pins acme-llm sub_01J...
pins reads a subject's recurring-price pin and usage-pricing binding. It is
read-only; moving a subscriber to the latest plan is deferred post-launch.
Contract terms
--terms-json is a JSON object with:
| Field | Type | Meaning |
|---|---|---|
percentDiscount | exact rational {num,den} | Discount applied after catalog modifiers; at most 1. |
floorNanos | decimal nanodollar string | Per-window minimum (true-up base is post-modifier rated usage). |
capNanos | decimal nanodollar string | Per-window cap on rated usage; must not be below the floor. |
selectorScope | array, ≥1 | Which catalog items the terms apply to: { kind: "catalog_item", item } or { kind: "provider_model_glob", provider, modelGlob, modality? }. |
Selectors match only within the named provider's namespace — a glob can never
cross providers. A pricing policy may declare permitted bounds for negotiated
terms; terms outside them are rejected with
CONTRACT_TERMS_EXCEED_POLICY_BOUNDS. A percent discount paired with
adopt_at_current_rate requires a floor.
New meters and measures
When a release introduces pricing the agreement never negotiated,
--new-meter-policy (a meter the agreement has no rule for) and
--new-measure-policy (a new measure on an agreed meter) decide what happens:
| Policy | Effect |
|---|---|
adopt_at_current_rate | Rate the new basis at the live catalog; extend and audit the agreement's scope. |
exclude_until_renewal | Rate at the live catalog with agreement terms withheld until the next negotiated version. |
require_amendment | Rate at the live catalog with agreement terms withheld and record an amendment requirement (the default; mandatory for fixed_version). |
Auto-apply is limited to changes with the same measurement-rule key, the same measure set, and items inside an agreed namespace; anything else routes through these policies.
Where agreements show up
- The plan's
usagePricingbinding is the default for every subject; an agreement overrides it for one subject. - Rating contexts compiled into a release include agreement modifiers, so
farthershore commercial-release diffshows a new rating-context version when an agreement is created or amended. - The bill preview reflects agreement pricing automatically.