Skip to main content
ScaleMath
← Leaderboard
93
ScaleMath score
0 critical1 significant5 minor
Rerun audit
1
SignificantStripe CLI Reference — Install (docs.stripe.com/cli/install)

CLI 'Install' page contains only navigation, no install instructions

ProblemThe page at /cli/install renders as a bare navigation index (Introduction, Install, Upgrade, Login, …) with no actual installation commands or page content, while the development-environment quickstart delegates further install options to the GitHub readme.
ConsequenceA developer or AI agent landing on this URL finds no install command at all. The quickstart says 'For more installation options for Windows, macOS, Linux, and Docker, check the Stripe CLI readme on GitHub', so the docs site itself fails to answer the basic question of how to install the CLI, forcing a detour to GitHub or causing an agent to invent an install command.
Current
cli Getting started Introduction Install Upgrade Login List authorized contexts Switch context ... (page contains only the navigation tree, no install instructions or commands)
Recommended
Render the actual Install page content on /cli/install, including 'Install the Stripe CLI with npm: npm install --global @stripe/cli' plus macOS (Homebrew), Windows, Linux, and Docker options, with a link to further installation options on GitHub.
The fixEnsure the docs generator emits the page body (not just the left-nav) for /cli/install, and verify all CLI reference pages render their content, not only navigation.
Was this finding useful?
2
MinorTest card numbers (cURL example), Accept in-person payments (PaymentIntent examples), Sell subscriptions as a SaaS startup (Checkout Session examples), Set up your development environment (create_price.rb), The Payment Intents API (cURL examples)

Hardcoded example secret API key repeated across copy-paste code samples

ProblemThe same literal test secret key appears hardcoded in every cURL/SDK example: -u "sk_test_Gx4mWEgHtCMr4DYMUIqfIrsz:". The testing page itself instructs 'Store live API keys in a secrets vault or environment variables. Don't store keys in source code' and the Ruby sample even comments 'Don't embed any keys in production code' — while embedding a key in the code block.
ConsequenceDevelopers and AI agents copy examples verbatim and leave the hardcoded key in source code, normalizing the anti-pattern the docs warn against; agents scaffolding from these samples will reproduce the embedded-key style.
Current
curl https://api.stripe.com/v1/payment_intents \ -u "sk_test_Gx4mWEgHtCMr4DYMUIqfIrsz:" \ -d amount=500 \ -d currency=gbp
Recommended
curl https://api.stripe.com/v1/payment_intents \ -u "$STRIPE_SECRET_KEY:" \ -d amount=500 \ -d currency=gbp
The fixReplace the literal sk_test_... string in all examples with an environment-variable placeholder (e.g. $STRIPE_SECRET_KEY) and note that the CLI/SDKs pick up keys automatically after stripe login.
Was this finding useful?
3
MinorSell subscriptions as a SaaS startup — 'Set the billing cycle' section

Confusing/self-contradictory billing cycle anchor explanation

ProblemThe text says the anchor 'determines the first full invoice date, when customers are billed the full subscription amount', then immediately gives an example where the customer 'is first initially billed on May 15, then always on the 1st of the month' — i.e. the first charge is a partial/prorated charge on the signup date, not the full amount on the anchor date, without clarifying the proration.
ConsequenceFirst-week engineers and agents implementing billing-cycle anchoring will mispredict when and how much the customer is first charged, leading to unexpected-charge support tickets or incorrect invoicing logic in their own systems.
Current
The billing cycle anchor determines the first full invoice date, when customers are billed the full subscription amount. For example, a monthly subscription created on May 15 with an anchor on June 1 is first initially billed on May 15, then always on the 1st of the month.
Recommended
The billing cycle anchor determines the date customers are billed the full subscription amount going forward. For example, a monthly subscription created on May 15 with an anchor on June 1 is first billed on May 15 (a prorated charge for May 15–31), then billed the full amount on June 1 and on the 1st of every month after.
The fixRewrite the sentence to explicitly state the initial charge is prorated and that the full amount begins at the anchor date.
Was this finding useful?
4
MinorThe Payment Intents API — 'Dynamic statement descriptor' section

Statement descriptor text contradicts its own example

ProblemThe section is titled 'Dynamic statement descriptor' and says 'use the statement_descriptor parameter', but the accompanying example actually passes statement_descriptor_suffix, and only a following Note clarifies the split (statement_descriptor for non-card, suffix for card).
ConsequenceA developer or agent skimming prose-then-code will pass statement_descriptor for a card payment instead of statement_descriptor_suffix, getting unexpected API errors or statement output.
Current
To provide a different description on a per-payment basis, use the statement_descriptor parameter. ... -d "statement_descriptor_suffix=Custom descriptor"
Recommended
To provide a different description on a per-payment basis for card charges, use the statement_descriptor_suffix parameter (use statement_descriptor for non-card charges). ... -d "statement_descriptor_suffix=Custom descriptor"
The fixAlign the prose with the code sample: name statement_descriptor_suffix first, and keep the existing Note as reinforcement.
Was this finding useful?
5
MinorSet up your development environment — Ruby quickstart

Stale SDK version claim: Ruby 2.3+ support

ProblemThe page states 'The latest version of the Stripe Ruby server-side SDK is v19.6.0. It supports Ruby versions 2.3+.' Ruby 2.3 has been end-of-life for years, and pinning the doc to a specific patch version (v19.6.0) invites staleness.
ConsequenceNew developers may scaffold projects on an EOL Ruby runtime believing it is supported, creating security and compatibility debt; agents may generate Gemfiles targeting Ruby 2.3.
Current
The latest version of the Stripe Ruby server-side SDK is v19.6.0. It supports Ruby versions 2.3+.
Recommended
The Stripe Ruby server-side SDK requires a maintained Ruby version; check RubyGems for the current minimum supported Ruby version and the latest SDK release rather than relying on this page.
The fixUpdate the minimum supported Ruby version to the SDK's actual requirement and either remove the hardcoded version number or note it reflects the writing date.
Was this finding useful?
6
MinorAccept simple payments for a startup — 'Next steps'; Accept in-person payments — physical test card table

Copyediting defects in use-case guides

ProblemTwo wording errors: 'Management fulfillment for your orders and view metrics' (should be 'Manage fulfillment') in the startup guide, and 'Payment is declined with an generic_decline code' (should be 'a generic_decline') in the Terminal physical test card table.
ConsequenceSmall polish issues, but they erode trust in step-by-step guidance and can confuse non-native-English readers or machine consumers that parse step text literally.
Current
Management fulfillment for your orders and view metrics. ... 05 Payment is declined with an generic_decline code.
Recommended
Manage fulfillment for your orders and view metrics. ... 05 Payment is declined with a generic_decline code.
The fixApply the two copyedits in the respective guides.
Was this finding useful?

What they do well

  • ✓Use-case-driven onboarding (get-started/use-cases) maps business models to end-to-end guides, which is exactly how new developers and agents self-select entry points.
  • ✓The testing page is exceptionally comprehensive: brand/country card tables, decline codes, Radar and dispute simulation, and location-simulation email tricks for Checkout.
  • ✓AI/agent support is first-class and concrete: an agent plugin, MCP server, agent skills, and a copy-ready setup prompt (docs.stripe.com/agents).
  • ✓Preview status (Public preview / Private preview) is labeled inline next to features like Event destinations, Batch jobs, and stablecoin products, so agents don't build on unreleased APIs unknowingly.

Top recommendations

  1. 1.Ensure every docs URL renders full page content rather than a navigation-only shell (as seen on /cli/install), since agents fetch URLs directly and cannot fall back to a visual nav.
  2. 2.Purge the hardcoded sk_test_... key from all code samples in favor of environment-variable placeholders to stop normalizing embedded keys in copied code.
  3. 3.Add a linting pass for prose/code contradictions and stale versions in quickstarts (statement_descriptor vs suffix, billing-cycle-anchor wording, Ruby version claims).
Pages we read (25)
Was this report useful?

Want us to fix these?

You build the product. ScaleMath handles the docs (and QA).

This is an automated audit of public documentation. It may contain mistakes, so use it as a starting point, not the final word.