docs(monetization): comprehensive correction pass

[vazexqi]

Summary

Follow-up to PR #1003. Brings the rest of the monetization docs into alignment with the actual implementation in core (monetization-inbound policy), gateway-service (/v3/metering/... API), and openmeter (TypeSpec API spec).

Each commit is independently reviewable.

1. Correct error code, CloudEvent subject, and policy errors (50c78b5d)

• index.mdx — replace 429 Too Many Requests with 403 Forbidden in two places. The policy returns 403 for every error condition, including quota exhaustion. Verified at core/packages/runtime/src/policies/monetization-inbound/policy.ts (every error path uses HttpProblems.forbidden).
• meters.mdx — change CloudEvent example subject from the OpenMeter generic "customer-id" placeholder to the actual subscription ULID. The policy emits subject == subscription (both equal to the subscription ID) at policy.ts:454-465. Adds a note explaining the convention.
• monetization-policy.md — add three error rows that the policy actually returns ("No key present", "Authorization Failed", "Subscription payment status is not available.").
• private-plans.md — clarify the plan ID used in /publish and /plan-invites is a 26-char ULID, not the human-friendly key.

2. Subscription-lifecycle API examples match OpenMeter (43046df3)

The programmatic create/change/cancel examples in subscription-lifecycle.md used field shapes that don't exist in OpenMeter's API. Replaced with the actual schemas from openmeter/api/spec/src/productcatalog/subscription.tsp:

• Create: body is { plan: { key, version }, customerId | customerKey, timing }. There is no top-level planKey or stripeCustomerId.
• Change: endpoint is POST .../change, not PATCH on the subscription. Body is { timing, plan: { key, version } }. Response returns both current and next subscriptions.
• Cancel: body { timing } controls behavior. Show timing: "next_billing_cycle" to match the prose; omitting the body cancels immediately.
• Drop the /restore example. OpenMeter marked the endpoint deprecated as of 2025-10-06 (already past).

3. Document bucket-level monetization configuration (a12bd94c)

The MonetizationConfiguration API was entirely undocumented despite being the source of truth for upgrade/downgrade direction (planOrder) and the bucket-level payment grace period (maxPaymentOverdueDays). Adds a new section to api-access.mdx covering GET, PUT, and DELETE on /v3/metering/{bucketId}/monetization-configuration. Updates monetization-policy.md's grace-period section to show the correct precedence chain (customer metadata → plan metadata → bucket config → built-in default).

4. Document Stripe setup and billing-readiness APIs (fd121c0f)

Five real Stripe-setup endpoints were not documented:

• POST /v3/metering/{bucketId}/setup/stripe (install + default profile)
• GET /v3/metering/{bucketId}/setup/stripe
• POST /v3/metering/{bucketId}/setup/stripe/{stripeAppId}/billing-profile
• GET /v3/metering/{bucketId}/billing-readiness
• PUT /v3/metering/{bucketId}/apps/{appId} (with key-prefix validation)

Adds a "Stripe setup and billing readiness" section to api-access.mdx, plus a :::tip in stripe-integration.md directing scripted/CI users at the new section.

Test plan

• Prettier passes (run via lefthook on every commit)
• Reviewer to spot-check rendered preview deploy
• Reviewer confirms intra-page anchor links resolve (#bucket-monetization-configuration, #stripe-setup-and-billing-readiness, #subscription-and-payment-validation)
• Optional: run any of the new curl examples against a dev bucket to confirm response shapes match the doc claims

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 7, 2026 3:39pm