pricing: clarify credits, per-resource rate, and worked example

[workprentice]

Addresses #20696 (does not fully close it — see scope note below).

Problem

Multiple people talking to prospects report that pulumi.com/pricing doesn't let a reader answer "I have N resources — what will I pay per month?" The issue lists five gaps; this PR closes four of them with content-only changes to content/pricing/_index.md.

What changed

1. "Additional usage billed on demand" is now a link. Both the Team and Enterprise plan-card notes link that phrase to the Pricing FAQ category (/pricing/#faq-pricing), where the on-demand rate is explained in detail.
2. The per-resource rate is now in the plan cards themselves. Team: "additional usage billed at $0.1825 per resource/month". Enterprise: "...at $0.365 per resource/month". These numbers were already published lower on the page (comparison table and FAQ); this just surfaces them where readers are actually looking.
3. "What are Pulumi Credits?" now describes the shared-pool model. A credit is $1 USD, and every product (IaC, ESC, Insights, Deployments, Neo) meters usage in its own unit against the same pool.
4. New FAQ item works a resource count through to a monthly figure, plus a second example showing how non-IaC usage draws from the same credit pool.

What I deliberately did not change

• The interactive pricing calculator (the issue's fifth bullet) is out of scope for this PR. Bringing it back is a front-end and product-scoping effort, not a docs content fix, and deserves its own PR with product sign-off on the estimator's behavior.
• I did not touch the plan-card layout or the comparison table's information architecture — only the copy inside existing fields.
• I did not use anything from the internal Slack thread or the "internal credit deck" the issue mentions. Every number and claim in this diff was already published on the live page (the on-demand rates and the 500/2,000 resource figures); I only surfaced and cross-linked them.

A modeling judgment call worth a second look

The Team plan's $40 base cannot fund 500 resources through the credit pool at the published on-demand rate (500 × $0.1825/resource/month = $91.25, not $40). So the page's two framings — "$40 buys a pool of Pulumi Credits" and "the Team plan includes up to 500 resources" — don't reconcile arithmetically as a pure pay-from-the-pool model.

I resolved this by treating 500 (Team) and 2,000 (Enterprise) as an included resource allotment on top of the base fee, separate from how the credit pool funds overage. This matches the issue's own proposed wording ("$40/mo includes 500 resources, then $0.1825 per additional resource/mo") and the page's existing FAQ claim ("The Team edition includes up to 500 IaC resources to get started with").

Could a reviewer confirm this is the intended model? If 500/2,000 are instead meant as a hard plan cap rather than an included allotment before overage billing kicks in, the wording in the plan-card notes and the new worked-example FAQ item would need to change. I did not want to guess at billing mechanics beyond what the page already asserts.

Validation

• YAML front matter re-parses cleanly after the edit (verified with yaml.safe_load).
• node scripts/lint/lint-markdown.js: 0 errors.
• yarn prettier --check content/pricing/_index.md: passes.
• Vale (Pulumi style): 0 findings on the changed file.
• Recomputed every dollar figure by hand: $0.00025/hr × 730 hr = $0.1825/resource/month (Team); $0.0005/hr × 730 hr = $0.365/resource/month (Enterprise); worked example $40 + (700 × $0.1825) = $167.75/month.
• Confirmed note and unit fields in the pricing plan-card partial are passed through markdownify, so the new links render correctly.
• Confirmed the #faq-pricing anchor exists (layouts/page/pricing.html renders id="faq-{{ .id }}" with id: pricing on the Pricing FAQ category).

Collision check

Two other open PRs touch content/pricing/_index.md: #20528 (Insights → Discovery/Governance rename, touches the comparison table's Insights section header) and #19757 (self-hosted Pulumi Cloud copy, touches the Product FAQ category). Neither overlaps the regions this PR touches (plan-card tiers notes and the Pricing FAQ category), so no merge-order dependency.

---

🧠 This PR was created by workprentice.

[github-actions]

Pre-merge Review — Last updated 2026-08-05T14:21:11Z

Tip

Summary: This PR clarifies the /pricing/ page: it replaces the two vague "additional usage billed on demand" tier notes with the concrete per-resource rates (now linked to the FAQ), splits the "What are Pulumi Credits?" answer so the per-product metering units are stated explicitly, and adds a new worked-example FAQ showing a $167.75 monthly bill for a Team plan managing 1,200 resources. On a pricing page the wrongness that hurts a reader is a rate or a total they can't reconcile — so the pass concentrated on the arithmetic, on whether the numbers match the published rates, and on whether the two new links actually resolve. Every rate and total checks out against the live pricing page and the page's own FAQ (15 of 18 extracted claims verified, 0 contradicted; the remaining 3 are first-party policy statements, not checkable claims), and the new /pricing/#faq-pricing links are valid — the faq-pricing anchor is emitted by layouts/page/pricing.html:229 from the id: pricing FAQ group, and the tier note field is passed through markdownify, so the inline markdown link renders. One thing is worth a second look before merge: the worked example's premise that the $40 base fee includes 500 resources doesn't reconcile with the credits model the same PR strengthens two answers above.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	HIGH

Investigation log

• Cross-sibling reads: not run (not in a templated section)
• External claim verification: 15 of 18 claims verified (0 unverifiable, 0 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 11 Pass 1, 0 Pass 2, 7 Pass 3 (verified 7, contradicted 0, unverifiable 0).
• Cited-claim spot-checks: not run (no cited claims)
• Frontmatter sweep: ran on body
• Temporal-trigger sweep: ran (recency words present in diff; spot-check in-review)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: not run (no fenced code blocks in content files)
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
0	1	0	0

🔍 Verification trail

18 claims extracted · 15 verified · 0 unverifiable · 0 contradicted

• L42-45 in content/pricing/_index.md "The Pulumi Team plan costs $40/month base and includes 40 Pulumi Credits." → ✅ verified (evidence: (escalated from pass3) Pricing table lists Team plan: "price: $40", "price_label: /month base", "unit: "Includes 40 Credits"" — matching the claim exactly.; source: repo:content/pricing/_index.md L40-44)
• L45 in content/pricing/_index.md "The Team plan includes up to 500 resources; additional usage beyond that is billed at $0.1825 per resource/month." → ✅ verified (evidence: Pulumi's pricing page states: "IaC resources are billed hourly at the rate of $0.00025 for Team ($0.1825 per resource per month)..." and "The Team edition includes up to 500 IaC resources to get started with."; source: https://www.pulumi.com/pricing/)
• L63-66 in content/pricing/_index.md "The Pulumi Enterprise (starting) plan costs $400/month base and includes 400 Pulumi Credits." → ✅ verified (evidence: (escalated from pass3) content/pricing/_index.md lines 60-66 list the Enterprise tier with price: $400, price_label: /month base, and unit: \"**Includes 400 Credits**\", matching the claim exactly.; source: repo:content/pricing/_index.md)
• L66 in content/pricing/_index.md "The Pulumi Enterprise plan tier includes up to 2,000 resources, with additional usage billed at $0.365 per resource/month." → ✅ verified (evidence: Pulumi's pricing page states: "The Enterprise plan includes up to 2,000 resources" and separately "IaC resources are billed hourly at the rate of ... starting at $0.0005 for Enterprise ($0.365 per resource per month)."; source: https://www.pulumi.com/pricing/)
• L689 in content/pricing/_index.md "If a customer subsequently consumes all up-front purchased usage, they will be billed in arrears for usage beyond that amount." → ✅ verified (evidence: The pricing FAQ states: "If you subsequently consume all up-front purchased usage, you will be billed in arrears as you go beyond that amount of usage." This is an exact restatement of the claim.; source: content/pricing/_index.md:689)
• L689 in content/pricing/_index.md "Customers who prefer to pay annually can contact sales to receive a discount for a committed amount of usage paid up-front." → ➖ not-a-claim (evidence: Line 689 is the pricing page's own FAQ text describing Pulumi's own billing/sales policy: "If you prefer to pay annually, you can contact sales to receive a discount for a committed amount of usage paid up-front." This is a faithful restat…; source: repo:content/pricing/_index.md#L689)
• L692 in content/pricing/_index.md "Customers can pre-purchase Pulumi Credits as needed to cover expected usage, either through a monthly up-front fee or an annual agreement." → ✅ verified (evidence: Pulumi's pricing page states verbatim: "One Pulumi Credit costs $1 USD, and you can pre-purchase Pulumi Credits as needed to cover expected usage either through a monthly up-front fee or annual agreement."; source: https://www.pulumi.com/pricing/)
• L694 in content/pricing/_index.md "Regardless of which mix of Pulumi products an organization uses, all usage draws from the same pool of Pulumi Credits at the rates listed on the pricing page o…" → ➖ not-a-claim (evidence: The claim text is a paraphrase of the exact line under review (L694): "Whatever mix of products your organization uses, all of that usage draws from the same pool of Pulumi Credits at the rates above or as listed on your order form." This…; source: repo:content/pricing/_index.md#L694)
• L694 in content/pricing/_index.md "Every Pulumi product meters usage in its own unit: IaC resources are metered by the hour, ESC usage is metered by secrets and secrets API calls, workflow usage…" → ✅ verified (evidence: Line 694 of the same file states: "Every Pulumi product meters usage in its own unit: IaC resources by the hour, ESC secrets and secrets API calls, workflow minutes, and Neo tokens." This is corroborated elsewhere in the doc: IaC resources…; source: content/pricing/_index.md:694)
• L697 in content/pricing/_index.md "IaC resources are billed hourly starting at $0.0005 per resource-hour for the Enterprise plan, equivalent to $0.365 per resource per month." → ✅ verified (evidence: Pulumi's official pricing page states: "IaC resources are billed hourly at the rate of $0.00025 for Team ($0.1825 per resource per month) and starting at $0.0005 for Enterprise ($0.365 per resource per month)."; source: https://www.pulumi.com/pricing/)
• L699 in content/pricing/_index.md "Enterprise plans receive volume discounts such that the more resources consumed, the lower the incremental rate." → ✅ verified (evidence: The pricing FAQ states verbatim: "Enterprise plans receive volume discounts, so that the more resources you consume, the lower the incremental rate." This directly matches the claim's assertion.; source: repo:content/pricing/_index.md (line 699))
• L699 in content/pricing/_index.md "Prepaid plans offer more considerable discounts than self-serve pay-as-you-go plans." → ✅ verified (evidence: The official Pulumi pricing page states verbatim: "This is true of self-serve pay-as-you-go plans, although prepaid plans offer more considerable discounts."; source: https://www.pulumi.com/pricing/)
• L701 in content/pricing/_index.md "A partial resource hour used is billed as a full hour." → ➖ not-a-claim (evidence: The line "For billing purposes, a partial resource hour used is billed as a full hour" is the pricing page's own stated billing policy — a first-party pricing/business-rule description, not a technical claim checkable against product sourc…; source: repo:content/pricing/_index.md L701)
• L701 in content/pricing/_index.md "Billing counts any resource that's declared in a Pulumi program." → ✅ verified (evidence: The pricing FAQ states: "For billing purposes, a partial resource hour used is billed as a full hour and we count any resource that's declared in a Pulumi program. This includes provider resources ... component resources ... and stacks..."…; source: content/pricing/_index.md:701; content/docs/iac/concepts/resources/_index.md)
• L701 in content/pricing/_index.md "Billable resources include component resources, which are groupings of resources such as an Amazon EKS cluster." → ✅ verified (evidence: Source text at line 701 states billable resources include "component resources which are groupings of resources (e.g., an Amazon EKS cluster)", matching the claim exactly.; source: repo:content/pricing/_index.md:701)
• L702-704 in content/pricing/_index.md "For a Team plan managing 1,200 IaC resources for a full month, the monthly bill would be the $40 base fee plus 700 additional resources at $0.1825 per resource…" → ✅ verified (evidence: Pulumi's pricing page confirms Team plan is billed at "$0.1825 per resource per month" and "The Team edition includes up to 500 IaC resources to get started with." With 1,200 resources, 700 are additional beyond the included 500: 700 × $0.…; source: https://www.pulumi.com/pricing/)
• L706 in content/pricing/_index.md "The same shared-pool billing model applies across all Pulumi products, including Pulumi ESC for secrets management, workflow minutes for Deployments, and Neo f…" → ✅ verified (evidence: The pricing page's own FAQ (L694) states: "Every Pulumi product meters usage in its own unit: IaC resources by the hour, ESC secrets and secrets API calls, workflow minutes, and Neo tokens. Whatever mix of products your organization uses,…; source: repo:content/pricing/_index.md)
• L702-704 in content/pricing/_index.md "the $40 monthly base fee includes up to 500 resources" → 🤷 unverifiable (evidence: the page's own FAQ describes the base fee as buying a credit pool — "The up-front fee will create a pool of Pulumi Credits" (L687) — and the Team tier card states "Includes 40 Credits" (L44) at "$1 USD" per credit (L692), drawn down for IaC at $0.1825/resource/month (L697). 40 credits at that rate covers ~219 resource-months, not 500. Which of the two models governs isn't stated anywhere on the page, so the premise can't be confirmed from published material.; source: content/pricing/_index.md:687, :692, :697; https://www.pulumi.com/pricing/)
• L708-709 in content/pricing/_index.md "The Team edition includes up to 500 IaC resources to get started with." → ✅ verified (evidence: The official Pulumi pricing page states verbatim: "The Team edition includes up to 500 IaC resources to get started with. You could manage 500 EKS clusters or EC2 instances for a month using this amount."; source: https://www.pulumi.com/pricing/)

🚨 Outstanding in this PR

No outstanding findings in this PR.

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

• [L702-704] content/pricing/_index.md — "a Team plan (which includes up to 500 resources for the $40 monthly base fee)". The $167.75 total is arithmetically correct given a 500-resource inclusion, and it matches the published $0.1825 per resource per month rate. But the parenthetical premise doesn't reconcile with the credits model this same PR sharpens two answers above. Per the page: the base fee "will create a pool of Pulumi Credits" (L687), Team "Includes 40 Credits" (L44), one credit is $1 (L692), and IaC draws from that pool at $0.1825/resource/month (L697). 40 credits therefore covers about 219 resource-months — not 500. Enterprise has the same gap, and wider: 400 credits at $0.365 covers ~1,096 resource-months against a stated "Up to 2,000 resources included" (L66).

  This tension pre-dates the PR (the tier notes and the "What can I do with 500 IaC resources per month?" answer already asserted the 500 figure), but the PR makes it computable for the first time: the old note said only "additional usage billed on demand," and now the exact rate sits on the card, one multiplication away from the contradiction. Since the stated goal here is to clarify credits, it'd be worth confirming with the pricing owners which model actually governs, and then either:

  • saying the 500/2,000 allowances are a separate resource allowance granted on top of the credit pool, if that's what they are; or
  • restating the example purely in credits, so a reader who does the math lands where the page does.

  A one-clause fix for the example itself, if the resource allowance is real and separate:

            As an example, a Team plan (whose $40 monthly base fee includes an allowance of up to 500 resources) managing 1,200 IaC resources for the full month would pay the $40 base plus 700 additional resources at $0.1825 per resource per month: $40 + (700 × $0.1825) = $167.75 for the month.
  

  That's a wording change only — the total is unaffected either way. Flagging it as low-confidence rather than blocking, because the numbers as published are self-consistent with the rate table and only the reason for the 500 is unclear.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-08-05T14:21:11Z — Rates, the $167.75 worked example, and both new #faq-pricing links all check out; flagged one low-confidence item — the "$40 base fee includes 500 resources" premise doesn't reconcile with the page's own 40-credit pool math. (ddf859f)

---

• Refresh this review — comment @claude #update-review. Say what you fixed, or which finding you dispute and why; both work in the same mention.
• Ask for anything else — comment @claude with no hashtag (questions, one-off fixes). Leaves this review untouched.

Important

Please don't hide, resolve, or delete this comment! It breaks things!

📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches.

[pulumi-bot]

Your site preview for commit ddf859f is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-20719-ddf859f4.s3-website.us-west-2.amazonaws.com

Changed pages:

• /pricing/

[jeffmerrick]

Would like humans to take care of this one.