Plans, features & quotas

Your manifest declares what a plan can sell

An app does not decide, in code, what each customer's plan includes. It declares the vocabulary — the features a plan may switch on, the metered quotas it may cap, and the one-off products a customer may buy — in app.manifest.yaml. The Control Plane binds concrete values to that vocabulary per plan and per org: which features are on, what each quota's limit is, how the limit is enforced. Your manifest never carries a per-plan number; it carries the definition the number attaches to.

The shape is the products-and-prices split behind Stripe Billing: you declare the catalogue, the platform binds prices, meters usage and enforces limits.

spec.features is the only required section of the whole spec. Everything else — routes, events, config, products — is optional; a valid manifest must at least declare its plan features (even an empty capability set is a deliberate statement).

Three concepts, three shapes:

Features are definitions, not values

Every feature is a definition CP renders into the plan-builder and the public /pricing table. The manifest fixes the feature's shape and a platform default; the plan that a customer subscribes to overrides that default in CP.

features:
- code: myservice.example.enabled       # boolean toggle
  name: Example feature
  description: Enable the example module.
  ui_hint: Toggle ON to enable the example module.
  type: boolean
  default: true
  marketing_label: Example feature
  marketing_description: Enable the example module.
- code: myservice.example.mode          # string choice
  name: Example mode
  description: A string-typed feature offering a fixed set of modes.
  ui_hint: Select the operating mode.
  type: string
  default: standard
- code: myservice.example.count         # integer limit + quota
  name: Example record limit
  description: Maximum number of example records per tenant (metered quota).
  ui_hint: Cap on example records.
  type: integer
  unit: records
  default: 100
  quota:
    source: cumulative

A boolean or string feature is a pure entitlement — it gates behaviour but is never metered. Only an integer feature can carry a quota.

Quotas meter an integer feature

Add a quota block to an integer feature and CP starts tracking reported usage against the feature's default limit. The block does not restate the limit — the feature's default is the number — it tells CP how to aggregate usage and, optionally, what to do when usage reaches the limit.

Most services declare only source — that is a full, valid quota. When the producer reports in a different unit than the customer-facing limit, add metric_code and multiplier:

features:
- code: comments.attachments.storage_gb
  name: Comment attachment storage (GB)
  description: Cumulative size of all uploaded comment attachments.
  ui_hint: Cap on comment attachment storage.
  type: integer
  unit: GB
  default: 0
  quota:
    # Limit is expressed in GB; the producer reports bytes.
    metric_code: comments.attachments.bytes
    source: cumulative
    multiplier: 1073741824

Enforcement, grace, and overage

policy is the platform default for what happens when a tenant reaches the limit. It is a default — CP lets an operator override it per plan and per org/instance. Omitting policy preserves the legacy observe-and-warn behaviour.

grace widens the point at which block / overage bite, and sets the dunning window for suspend:

overage is mandatory when policy: overage. The first included units are free; only the excess is metered and billed:

self_service chooses which recovery actions the portal offers the customer at the limit; notify controls the warnings:

features:
- code: myservice.api.calls_per_day
  name: API calls per day
  description: Daily API call allowance for this tenant.
  ui_hint: Cap on API calls per day.
  type: integer
  unit: requests
  default: 100000
  quota:
    source: daily
    policy: overage
    grace:
      pct: 10
      period: P3D
    overage:
      price_ref: api_calls_overage
      hard_ceiling: 500000
    self_service:
      upgrade: true
      enable_overage: true
      request_increase: false
    notify:
      thresholds_pct: [75, 90, 100]
      audiences: [client_admin, client_billing, operator]
      channels: [email]

Features and quotas are declared here but enforced at request time by the require_feature and require_quota gates. See Auth & the five gates for how a route composes them (feature not in plan → 403; over quota → 429).

Products are one-off purchases

Where a feature is recurring plan entitlement, a product is a single purchase — a credit pack, a storage top-up, a one-time add-on. You declare the SKU and a fulfilment endpoint; CP owns the money. On a customer purchase, CP runs a one-time Stripe checkout and, on successful payment, POSTs to your fulfillment.handler_endpoint. The declaring app never touches Stripe, never sees a card, and never verifies a payment — it only grants what was bought.

The fulfillment block names the internal endpoint CP calls on settled payment:

products:
- code: ai_credits_1000
  name: 1,000 AI Credits
  description: Starter top-up — 1,000 AI credits added to your org pool.
  kind: one_time
  price_cents: 1000
  currency: usd
  fulfillment:
    handler_endpoint: /v1/egav-ai/internal/credits/grant
    params:
      credits: 1000
      source: purchase
- code: ai_credits_5000
  name: 5,000 AI Credits
  description: 5,000 AI credits — best value for active teams (10% off).
  kind: one_time
  price_cents: 4500
  currency: usd
  recommended: true               # badged "Best value" in the catalog
  fulfillment:
    handler_endpoint: /v1/egav-ai/internal/credits/grant
    params:
      credits: 5000
      source: purchase

Make the fulfilment handler idempotent. CP injects a payment_ref on every call; dedupe on it so a retried delivery returns the existing ledger result instead of creating another grant. The reserved keys (org_guid, payment_ref, reason) arrive from CP, not from your params.

Products backed by provisioned resources

Set resource.component_type when fulfillment depends on a platform resource, not only an app-local ledger entry:

products:
- code: reporting_database
  name: Reporting database
  kind: recurring_add_on
  price_cents: 2500
  currency: usd
  resource:
    component_type: db
  fulfillment:
    handler_endpoint: /v1/example/internal/resource-claims

CP provisions and records the tenant binding first. A tenant binding is CP's durable record that links an organization, app instance, component type, and provisioned resource. CP then adds a resource claim — the generation-specific grant or revoke request that the provider app must acknowledge — to the existing fulfillment request. The resource_claim object carries operation (grant or revoke), monotonic generation, stable claim_ref, binding_guid, component_type, resource_code, and an optional opaque handle_ref. It does not include credentials, DSNs, or an app-specific database-row shape.

Use the SDK's ResourceClaimRequest / ResourceClaimResponse models. Persist the app-local result idempotently and acknowledge the exact claim_ref only after that commit. When CP retries the same claim_ref, return the same acknowledgement rather than creating another entitlement. Non-2xx or malformed acknowledgements leave claim_status, claim_reason, and claim_attempts available for inspection and cause the fulfillment worker to retry the durable claim. Test both sides with check_resource_claim_conformance(manifest, implemented_claim_handlers=...); the gate rejects both a declared-but-missing handler and a mounted-but-undeclared resource-claim handler.

A binding represents one resource-ownership lifecycle, not a purchase ledger. CP refuses a second payment or grant while its current grant is pending, failed, or active; retry uses the same generation and payment reference. A later grant is allowed only after the app has acknowledged the binding's revoke. Ordinary repeat-purchase credit packs therefore remain non-resource products.

The one-time checkout path durably reserves the selected binding generation before redirecting the customer. The reservation is the provider idempotency key and must be echoed in signed provider metadata before CP records the invoice or sends the grant. An ambiguous provider error leaves the reservation open so retry reuses the same key; only a definitive rejection or signed failed/expired event cancels it. A signed asynchronous-payment state disables the local opening deadline until the provider reports success or failure. Deletion is blocked while the reservation is genuinely open.

Do not use lifecycle_hooks for this contract. They are instance lifecycle notifications; paid resource ownership belongs to the durable product fulfillment path.

Typed handler integration boundary

The existing Data app shows what accepting a database grant actually does. Source reference: egav/backend/app/api/v1/egav/routes/internal_storages.py at commit 0a6360eb19432a3c1d3ac600794c09b68f3bbfd5, apply_resource_claim. Its app-owned EGAVResourceClaimRequest uses the SDK's ResourceClaim type and forbids unexpected envelope fields.

The following is an abridged source excerpt, not a deployable handler. Comments mark omitted validation and replay/conflict branches; retain those branches when studying the complete implementation.

@router.post("/resource-claims", response_model=ResourceClaimResponse)
async def apply_resource_claim(
    body: EGAVResourceClaimRequest,
    request: Request,
    db: AsyncSession = Depends(get_db),
) -> ResourceClaimResponse:
    claim = body.resource_claim
    payload_hash = _claim_payload_hash(body)
    binding_guid = str(claim.binding_guid)
    # Omitted: reject non-db claims, primary storage, and invalid handle GUIDs;
    # derive tenant_database_guid only after those checks.

    await assert_org_owns_instance(
        org_guid=str(body.org_guid),
        instance_guid=request.headers.get("x-app-instance-guid"),
        app_code="egav",
        authoritative=True,
    )

    async with async_transaction_context(db):
        await _acquire_resource_claim_locks(
            db,
            binding_guid=binding_guid,
            resource_code=claim.resource_code,
        )
        row = await db.scalar(
            select(EGAVDataStorage)
            .where(EGAVDataStorage.resource_binding_guid == binding_guid)
            .with_for_update()
        )
        # Omitted: stored identity/generation/payload conflict checks,
        # stale and identical replay handling, and active-code ownership checks.
        if row is None:
            row = EGAVDataStorage(
                code=claim.resource_code,
                name=f"Extra ({claim.resource_code})",
                tenant_database_guid=tenant_database_guid,
                resource_binding_guid=binding_guid,
            )
            db.add(row)
        # Omitted: reject code changes and revocation of referenced storage.
        row.tenant_database_guid = tenant_database_guid
        row.resource_binding_guid = binding_guid
        row.resource_claim_generation = claim.generation
        row.resource_claim_ref = claim.claim_ref
        row.resource_claim_payload_hash = payload_hash
        if claim.operation == "revoke":
            row.soft_delete("system")
        else:
            row.is_deleted = False
            row.deleted_at = None
            row.deleted_by = None
        await db.flush()

    return ResourceClaimResponse(
        claim_ref=claim.claim_ref,
        status="acknowledged",
    )

This is commit-before-ack: flush() alone is not a commit; successful exit from async_transaction_context commits before the response is returned. The actual app effect is a tenant-local EGAVDataStorage row. Its persisted binding identity, generation, claim reference and payload hash survive process restarts. Advisory locks and row locks serialize concurrent delivery. The omitted branches acknowledge an identical replay without a second effect, reject changed payloads at the same generation, and prevent an older delivery from undoing newer state. A failed transaction must not return an acknowledgement.

Before mounting your own declared endpoint, require both internal-key authentication and a verified service identity attributed to the exact control-plane caller, including its instance identity. A valid internal key alone does not establish that caller. The existing AI dependency require_control_plane_caller in egav-ai/backend/app/api/deps.py illustrates that additional caller check; it is not automatically applied by the excerpt.

Validate tenant scope authoritatively: the organization must own the selected app instance, and the database session must belong to that instance. Neither the body org_guid nor X-App-Instance-Guid is authority by itself. The source example uses the existing internal API-key gate plus assert_org_owns_instance; do not expose this excerpt as an unauthenticated public route. Known limitation of the source example: its generic internal API-key gate does not itself enforce the exact Control Plane caller. The excerpt demonstrates persistence, not complete caller authorization. Reject a missing instance header, reject a foreign organization/instance pair, and fail closed if the ownership authority is unavailable.

Use your app's existing route/service/CRUD transaction boundaries and durable storage, not an in-memory set of claim references. Keep the receipt and local effect atomic. Validate supported components and opaque handles, reject conflicting identity/payload changes, and return the exact SDK response only after persistence. The shared request model preserves app-owned fulfillment fields; your app must separately validate those fields with a strict schema: an app-owned Pydantic model with ConfigDict(extra="forbid"), the typed envelope/app fields, and resource_claim: ResourceClaim. Merely parsing ResourceClaimRequest does not reject unknown app-owned fields. Data's storage table and GUID handle format are an example, not a requirement for other apps or something to add to Control Plane.

Offline contract check

With the Python SDK already installed in an isolated development environment, save this as check_resource_claim.py and run python check_resource_claim.py. It uses only SDK validation and conformance APIs: no HTTP request, database, provisioning, credentials or payment.

from egav_app_sdk import check_resource_claim_conformance
from egav_app_sdk.resource_claims import (
    ResourceClaimRequest,
    ResourceClaimResponse,
)
from pydantic import ValidationError

endpoint = "/v1/example/internal/resource-claims"
manifest = {
    "spec": {
        "products": [{
            "code": "reporting_database",
            "resource": {"component_type": "db"},
            "fulfillment": {"handler_endpoint": endpoint},
        }],
    },
}
empty_manifest = {"spec": {"products": []}}
# This minimal dictionary tests the conformance helper, not full manifest validity.
assert check_resource_claim_conformance(
    manifest, implemented_claim_handlers={endpoint},
) == []
assert check_resource_claim_conformance(
    manifest, implemented_claim_handlers=set(),
) == [f"resource-backed product declares unimplemented handler: {endpoint}"]
assert check_resource_claim_conformance(empty_manifest,
    implemented_claim_handlers={endpoint},
) == [f"resource-claim handler has no resource-backed product declaration: {endpoint}"]

binding = "00000000-0000-4000-8000-000000000001"
payload = {
    "org_guid": "00000000-0000-4000-8000-000000000002",
    "payment_ref": "offline-example",
    "reason": "Offline contract check",
    "resource_claim": {
        "operation": "grant",
        "generation": 1,
        "claim_ref": f"{binding}:1:grant",
        "binding_guid": binding,
        "component_type": "db",
        "resource_code": "reporting_database",
        "handle_ref": "00000000-0000-4000-8000-000000000003",
    },
}
request = ResourceClaimRequest.model_validate(payload)
assert request.idempotency_key == f"{binding}:1:grant"
# Validate an example response shape only; no resource has been claimed.
response = ResourceClaimResponse(
    claim_ref=request.idempotency_key, status="acknowledged",
)
assert response.claim_ref == request.resource_claim.claim_ref
bad_payload = {
    **payload,
    "resource_claim": {**payload["resource_claim"], "claim_ref": "wrong"},
}
try:
    ResourceClaimRequest.model_validate(bad_payload)
except ValidationError:
    pass
else:
    raise AssertionError("mismatched claim identity was accepted")
print("Offline contract controls passed; no resource was provisioned or claimed.")

The positive control supplies a matching declaration and handler path; the two negative controls remove each side in turn. For your own app, validate the full manifest first and pass handler paths discovered from its real mounted routes, not a second copy of the declaration. TypeScript builders have the equivalent checkResourceClaimConformance, parseResourceClaimRequest and parseResourceClaimResponse exports in the TypeScript SDK.

This does not prove authentication, persistence, retry delivery, or a real second app claiming an extra database. Before go-live, test your actual handler with authenticated and rejected callers, cross-tenant rejection, concurrent/identical replay, conflicting payloads, stale generations, and commit failure followed by retry. Verify the app-local effect and durable receipt together, then verify a real provisioned database reaches a second app without Control Plane source changes. That integrated proof is separate from this offline check.

Compatibility, rollout, and rollback

Resource claims require Python egav-app-sdk 0.20.0. TypeScript manifest consumers use egav-app-sdk-ts 0.41.0. The platform's own services already support claims, so a provider app needs only the SDK versions above.

Roll out a provider before the Control Plane can send claims to it:

1. Install SDK 0.20.0 in the provider service.
2. Apply the provider's receipt migration and load its claim handler.
3. Verify the provider route accepts an SDK-validated request and returns an

acknowledgement for the same claim_ref.

1. Apply the Control Plane binding migration, load the CP web processes and

worker, then publish the updated manifest.

This order keeps CP from dispatching a claim to a provider that has neither the receipt table nor the handler contract. Rollback is also fail-closed: the Data and AI services' downgrade guards refuse to drop receipt tables while any durable claim provenance remains, including revoked or soft-deleted receipts. The CP downgrade guard likewise refuses destructive binding/product cleanup while durable claim or resource-backed state remains. Retire or migrate that state through the owning service before retrying a downgrade; do not delete receipt or binding rows merely to make the migration proceed.

Defining features and quotas — best practices

The tables above are the reference; this is the judgement. A few rules keep a plan model clean as it grows.

Naming and shape.

• Treat a feature code as permanent. {service}.{area}.{capability} (e.g. egav.schemas.count) is the stable key that plan bindings, feature gates and quotas all point at — renaming or deleting a live code orphans every binding and every gate that names it. To retire one, mark it deprecated and add a new code, then migrate.
• Pick the type by the decision, not the value. boolean for an on/off entitlement; string for a fixed set of tiers or modes (spell the allowed values out in description / ui_hint); integer for anything countable or limitable. Never model on/off as an integer 0/1 — a boolean gates more clearly and cannot be metered by accident.
• Default to the lowest tier. default is what a plan gets before it overrides — the free or entry value. For an integer quota feature the default is the free-tier limit; do not set it to your top tier and hope every plan lowers it.
• One feature, one decision. Several small features beat one overloaded one — each maps to a single gate call and one column on the pricing table. Give anything shown on /pricing its own marketing_label / marketing_description so buyer copy is never your internal code.

Metering and enforcement.

• Match source to how usage accrues. cumulative for a stock that only grows (total records, stored GB) — one lifetime counter. daily for an allowance that refills (calls per day) — resets each UTC day. per_request for a per-call ceiling (max items in one batch) — checked, never aggregated.
• Keep the limit in human units. Express default + unit in what the customer reads (GB, not bytes) and use multiplier so the producer can report raw units.
• Start soft, tighten deliberately. notify (the default) observes and warns while you learn real usage; graduate to block, overage, or suspend once you know the numbers. allow is pure metering with no enforcement; overage needs an overage.price_ref; suspend needs a grace.period dunning window.
• Leave a buffer before you block. A small grace (pct or units) stops a customer being hard-stopped the instant they touch the line. Because policy and grace are platform defaults, an operator can loosen them for a generous plan without a re-publish.
• Let customers self-recover. Keep self_service.upgrade and request_increase on so a capped tenant resolves it themselves — fewer support tickets; turn on enable_overage only once you have priced it.
• Warn early, warn the right people. The default [80, 100] thresholds are a floor — add 90 for an expensive quota — and notify client_admin (and client_billing when money is involved) so the tenant acts before the wall.
• Report usage idempotently. For a cumulative quota especially, dedupe usage deltas (on an event id) so an at-least-once producer retry never double-counts.

Feature, quota, product, or config?

• Recurring entitlement or limit → a feature (add a quota when it is a metered integer).
• One-off purchase (credit pack, top-up) → a product.
• An operator knob a customer's plan should not change (a TTL, a retry count, a rotation policy) → the config block, not a feature.

What a buyer actually sees

Declaring a feature entitles it. It does not advertise it, and the two are separate decisions on purpose.

A published catalogue is an engineering surface: retention windows, dispatch rates, payload ceilings, instance classes. Most of it is meaningless to somebody deciding whether to buy, and rendering all of it produces a pricing page nobody can read. So the public page draws from an opt-in subset.

Two gates control it, and both default to off:

• show_on_pricing — whether a feature appears on the public pricing

comparison. Declare it per feature in your manifest, or let operators set it in the Control Plane under the app's feature catalogue.

• plans.is_public — whether a plan appears on the public pricing page at all.

This is deliberately not the same flag as is_active. A plan can be live, provisioning correctly, and still have no business being quoted to a visitor: a plan built for one customer, a plan mid-assembly, or a plan created by an automated test.

show_on_pricing has three states, not two

- code: support.tickets.enabled
  name: Ticketing
  description: Enable the ticket desk.
  ui_hint: Toggle ON to enable ticket workflows.
  type: boolean
  default: true
  show_on_pricing: true        # put it in front of buyers

Leaving it out is not the same as false. Most manifests should leave it out: which features sell is an editorial decision that changes far more often than your app does, and operators own it. Reach for an explicit value when the answer belongs in your source control — true when a feature ships as a selling point, false when you want it withdrawn from the page in the same commit that withdraws it from the product.

Three more plan fields drive how a published plan is presented, so none of it needs a frontend change:

Prices come from the plan's price points. Declare both a monthly and an annual point and the page offers a billing switch, showing the annual figure as its monthly equivalent alongside the amount actually billed. If the annual price is not cheaper than twelve monthly ones, no discount is advertised.

Writing copy a buyer can use

marketing_label and marketing_description are what the public page shows, falling back to name and description when they are not set. Treat them as genuinely different text rather than a copy of the engineer-facing fields — duplicating the technical wording defeats the fallback and puts sentences like "soft-enforced via the event bus" in front of a prospect.

State the outcome, in the buyer's words, in one line:

- code: cp.members.count
  name: Organization member seats          # engineer-facing
  description: Maximum number of user accounts in the org.
  marketing_label: Team members            # buyer-facing
  marketing_description: People who can sign in to your workspace, across every role.
  type: integer
  default: 10

Where prices and values are bound

Nothing in this section carries a per-plan value. The manifest fixes the vocabulary; the Control Plane binds the numbers:

• Feature values — which features are on and each integer limit — are set per plan and per org in CP, not in the manifest.
• Quota enforcement — policy, grace, overage pricing — ships a platform default here and is overridable per plan and per org/instance in CP.
• Product prices are operator-tunable: change price_cents and re-publish, or let an operator adjust in CP; the recommended toggle survives re-publish.

Re-publishing the manifest updates the definitions; it does not reset the bound values an operator has tuned. To expose a new operator-facing knob that is not a plan feature — a TTL, a retry count, a rotation policy — declare it in the config block, not as a feature.

How an operator binds them

An operator does this in the Control Plane console (Catalog & billing → Plans), or through the same admin API with an operator token. A plan is versioned: every change sends base_version, the plan's current catalog_version, and a stale one is refused with 409.

An override belongs to the organization's subscription, not to the organization, so it does not follow the organization to a new plan. Your app's feature gate reads the organization's effective features from CP, so a change shows up on the next requests; on a local stack it took under a second.

To put a customer on a plan without self-serve sign-up, the operator onboards it: POST /v1/control-plane/cp/subscriptions/onboard with org_name, org_slug, org_subdomain, admin_email, plan_code and interval. org_subdomain is lowercase letters and digits only, with no hyphens. The slug may have hyphens. The organization is provisioned into every app on the plan, which calls each app's provision endpoint (see Provisioning), and the admin is emailed an invitation.

Operator access on a local platform stack

The steps above need an operator account. On a local platform stack:

1. The first operator is seeded. Its email is SEED_EMAIL in egav-control-plane/backend/.env. Set its password with Forgot password on the local console's sign-in page (https://cp.your-domain.example:3202/login). The reset email lands in Mailpit (http://127.0.0.1:8025). The console then asks you to enrol MFA, because operators must use it.
2. Each person gets their own operator. MFA is enrolled per account, so a second developer can't use the seeded operator once someone has enrolled it: its password reset then stops at the MFA step. Sign in as an existing operator and invite them from Security & access → Operators → Invitations (or POST /v1/control-plane/cp/operator-invitations/ with email and role). admin is enough to manage plans, features, prices, overrides and onboarding. The invitee accepts from Mailpit and enrols their own MFA.
3. Scripts sign in like the console. The operator flow is the headless one on the /cp/oidc/... tier: /cp/oidc/authorize/headless, then /cp/oidc/headless/credentials, then /cp/oidc/headless/mfa with a current TOTP code (or /cp/oidc/headless/mfa/enroll and /enroll/confirm the first time), then /cp/oidc/token. The operator access token lasts 15 minutes.