One-line state: A capable Merchant-of-Record platform with broad docs, but the API reference, SDK pages, and AI-onboarding surfaces openly contradict each other on package names, status codes, env-selection, ID formats, and feature counts — and the contradictions land hardest on the AI agents Creem explicitly courts.
1. The AI-facing index installs a package that exists nowhere else (critical)
Problem: The agent-facing index says "Install SDK: npm install @creem/sdk". The package @creem/sdk appears nowhere else in the docs. The real packages are creem (core), creem_io (wrapper), and @creem_io/nextjs (Next.js adapter).
Consequence: This is the one file Creem tells AI assistants to read first. An agent that follows it runs npm install @creem/sdk, gets an install error or a typosquat, and the whole automated integration dies on step 3. Humans cross-check; agents fail silently.
The fix: Change the llms.txt install line to npm install creem (matching the core SDK page) and list the real package set explicitly.
2. Docs lead with an SDK the official repo marks deprecated (significant)
Problem: The creem_io GitHub README opens with: "This package (creem_io) is deprecated. Please use the official creem package instead." Yet the docs use creem_io as a primary example — import { createCreem } from 'creem_io' is the headline snippet on the One-Time Payment page, and it has its own current "TypeScript Wrapper" SDK page.
Consequence: Developers and agents build new integrations against a deprecated package with no migration banner in the docs. The package still functions, so nothing breaks today — the harm is future breakage and missing migration guidance, with the deprecation discoverable only by visiting GitHub.
The fix: Add a deprecation banner to the wrapper SDK page and rewrite the One-Time Payment example on the creem core package, or explicitly state the wrapper's support status and timeline.
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
Problem: The API Introduction's Response Codes table says 401 = "Missing API key" and 403 = "Invalid API key or insufficient permissions." The Error Handling page documents no 401 at all, and states under "Authentication Errors (403 Forbidden)": "Returned when the API key is missing, invalid, or doesn't have permission."
Consequence: Developers writing auth-error handling can't know whether to branch on 401 or 403 for a missing key. Anyone who codes against the Introduction (if (status === 401)) silently mishandles the actual 403 the Error page describes.
The fix: Pick one status for a missing key, fix it on both pages, and make the Error Handling page's status table match the Introduction's full set.
4. PayPal is advertised as a checkout method but absent from the authoritative list (significant)
Problem: The Getting Started FAQ says "What payment methods do you support? Cards (Visa, Mastercard, Amex), PayPal, Apple Pay, Google Pay..." The authoritative "Currently Supported Payment Methods" list (Credit Cards, Apple Pay, Bancontact, Cartes Bancaires, EPS, Google Pay, IDEAL, Link, MobilePay) does not include PayPal.
Consequence: Merchants pick Creem expecting to offer PayPal at checkout, market it to their own customers, and then find it isn't available — a contradiction that surfaces only in production.
The fix: Remove PayPal from the FAQ supported-methods answer (or move it to a clearly-labeled roadmap line, as WeChat Pay/Alipay are) so both pages agree.
5. Base URL /v1 segment is present on some pages, absent on others (significant)
Problem: The API Introduction gives base URLs with the path segment: https://api.creem.io/v1 and https://test-api.creem.io/v1. The Error Handling page's Environments table and the llms.txt index give them without: https://api.creem.io. The endpoint map (llms-full.txt) shows real paths as /v1/....
Consequence: A developer or agent who builds the base URL from the Error/llms pages and appends documented endpoint paths produces either a doubled or a missing /v1, returning 404s that look like wrong endpoints rather than a base-URL bug.
The fix: Standardize on one canonical base URL (with /v1) across the Introduction, Error Handling, and llms.txt, and state once whether endpoint paths already include the segment.
6. The dedicated Error page documents 3 of the 7 status codes — with a wrong category and a missing field (significant)
Problem: The Introduction lists seven response codes (200/400/401/403/404/429/500); the Error Handling page documents only three (400/403/404), omitting 401, 429, and 500. Worse, the "Resource Not Found (404)" example body shows "error": "Bad Request" (should be "Not Found"), and the 403 example omits the message field that the documented Error Response Format marks as a string[] of "human-readable error messages."
Consequence: Developers can't build rate-limit backoff (429) or server-error retries (500) from the page that's supposed to be the error contract, and anyone parsing the error string to categorize failures will mis-bucket a 404 as a 400.
The fix: Document all status codes the API can return on the Error Handling page, fix the 404 example's error value to "Not Found," and include message in the 403 example (or mark it optional in the format spec).
7. Three different environment-selection mechanisms across SDKs and the homepage (significant)
Problem: The core creem SDK selects environment with serverIdx (0 = production, 1 = test). The deprecated creem_io wrapper uses testMode: true. The CLI auto-detects from the key prefix. And the homepage quickstart sets serverIdx: 1 (test) while the core SDK page sets serverIdx: 0 (production) — so the very first snippet a new user copies silently targets a different environment than the SDK reference.
Consequence: A developer who learns one SDK's pattern carries the wrong mental model to the other and ships code pointed at the wrong environment — e.g., copying the homepage's serverIdx: 1 into production thinking it's the default.
The fix: Document the env-selection mechanism per SDK in one comparison table, and make the homepage and core SDK examples agree on which serverIdx value is the production default.
8. Checkout ID prefix is chck_ on one page and ch_ on another (significant)
Problem: The core SDK page uses creem.checkouts.retrieve('chck_1234567890'), while the One-Time Payment response shows "id": "ch_1QyIQDw9cbFWdA1ry5Qc6I" and checkout URLs like checkout.creem.io/ch_.... Two different prefixes for the same object.
Consequence: Developers who write ID validation/regex (/^chck_/ vs /^ch_/) or pattern-match in routing get it wrong for half the platform's own examples. Agents extracting the ID format from one page will reject IDs from the other.
The fix: State the canonical checkout ID prefix once and correct every example to match.
9. AI pages undercount endpoints, webhooks, and SDKs versus the actual reference (significant)
Problem: Both AI pages claim SKILL.md covers "all 24 API endpoints... 10 webhook events." The API reference (llms-full.txt) contains 54 endpoint pages — of which ~12 are duplicate aliases (see issue 10), leaving ~42 unique endpoints, still far above the claimed 24. The webhooks guide enumerates 12 event types (it explicitly lists subscription.trialing and subscription.paused beyond the claimed 10). The llms.txt index lists SDKs as just "TypeScript, Next.js adapter," while the same AI pages claim "4 SDKs."
Consequence: Creem markets SKILL.md as a "complete knowledge base" for AI assistants, but it advertises coverage of barely half the real surface area (24 of ~42 unique endpoints). An agent told there are 10 webhook events won't build handlers for the other 2 (including subscription.paused).
The fix: Recompute and align the endpoint/webhook/SDK counts everywhere, ideally generating them from the OpenAPI spec (after de-duplicating the reference) so they can't drift again.
10. The endpoint reference is inflated by duplicate pages for the same path (significant)
Problem: Of the 54 endpoint pages, eleven customer-credits operations are documented twice under parallel slug families resolving to the identical HTTP method + path — e.g. create-credits-account and create-customer-credits-account both map to POST /v1/customer-credits/accounts, and get-credits-account-balance / get-customer-credits-account-balance both map to GET /v1/customer-credits/accounts/{id}/balance. Separately, get-metrics-summary and get-stats-summary both resolve to GET /v1/stats/summary with near-identical descriptions.
Consequence: It's ambiguous which page is canonical; an agent indexing the reference sees two "different" endpoints for one operation, inflating its endpoint map and risking duplicate client methods. It also makes the 24-vs-54 confusion in issue 9 worse.
The fix: Collapse each duplicate pair to a single canonical page (301 the alias slug) so each path appears exactly once.
11. Mintlify starter-template boilerplate shipped in production docs (significant)
Problem: The entire /essentials/* section is unmodified Mintlify starter content: blockquote examples reading "Dorothy followed her through many of the beautiful rooms in her castle," references to the legacy mint.json config (Mintlify now uses docs.json), and dead internal links like [link to text](/writing-content/text). All of it is exposed in llms-full.txt.
Consequence: Because it's in llms-full.txt, agents ingest fairy-tale placeholder prose and broken /writing-content/* links as if they were Creem documentation, and a developer who reads the navigation page is told to edit a mint.json that no longer exists.
The fix: Delete the /essentials/* template pages (or replace with real content) and exclude them from llms-full.txt.
12. Redirect signature is documented but never verifiable (significant)
Problem: The success-URL parameters table includes signature — "All previous parameters signed by Creem using your API-key, verifiable by you." No verification snippet, algorithm, or canonical-string construction is given. Only webhook signatures (HMAC-SHA256 over the raw body, creem-signature header) are documented.
Consequence: A developer who trusts checkout_id/customer_id from the redirect without verifying the signature is exposed to forged success redirects (a user can fabricate ?checkout_id=...&product_id=... to claim entitlements). The docs flag the signature as "verifiable by you" but give no way to verify it.
The fix: Document exactly how the redirect signature is computed (which params, what order, what key, what algorithm) with a copy-pasteable verification example, and clarify whether it uses the API key or webhook secret.
13. Moderation API: "required May 1st 2026 / currently free" vs "required now, no date" (significant)
Problem: The FAQ says "Integration is required starting May 1st, 2026. The API is currently free to use." The Moderation feature page says it is "required for all merchants running AI image or video generation products" with accounts "out of compliance... may be suspended without notice" — no date, no mention of being free. (Today is 2026-06-17, so the FAQ's future-tense cutover has already passed and reads as stale.)
Consequence: A merchant reading the FAQ believes they have a grace period and no cost; the feature page says non-compliance risks suspension now. The two pages give opposite answers to "must I integrate this today, and will it cost me?"
The fix: Reconcile the timeline and pricing on both pages; if the May 1 2026 deadline has passed, state that integration is now mandatory and confirm the current pricing in one place.
14. CLI says "never share your API key with any agent" while the headline flow tells agents to take it (significant)
Problem: The CLI page warns: "Never share your API key with any service, tool, or agent other than the Creem CLI or API. Keys are stored locally at ~/.creem/config.json." Meanwhile the FAQ's sanctioned AI flow says to "Point any AI coding assistant at creem.io/SKILL.md. It will install the CLI, configure auth, and help you integrate," and adds that an AI agent can manage your store. Keys are stored in plaintext.
Consequence: Two official pages give opposite security guidance. A developer can't tell whether handing their API key to an AI assistant (which Creem actively encourages) violates Creem's own stated rule, and the plaintext storage location amplifies the stakes.
The fix: Reconcile the security posture — either scope the CLI warning to exclude the sanctioned AI flow, or describe a safer onboarding path (e.g., short-lived/test-only keys for agents) and clarify how ~/.creem/config.json should be protected.
15. Webhook signature helper is not runnable standalone TypeScript and only generates, never verifies (significant)
Problem: The verification example is a bare method body — generateSignature(payload: string, secret: string): string { ... } — with no enclosing function/class declaration, so it isn't valid standalone TypeScript. It also only computes a signature; it never verifies one against the incoming creem-signature header, and shows no timing-safe comparison step.
Consequence: A developer or agent who copies the snippet gets a syntax error, and even after fixing it has a function that generates a signature but never validates an inbound webhook — leaving the actual security check (constant-time compare against creem-signature) as an unguided exercise.
The fix: Ship one canonical, runnable verification function (function verifyCreemSignature(payload, header, secret): boolean) that recomputes the HMAC and does a timing-safe compare against the creem-signature header.
16. Moderation flag and deny are functionally identical (minor)
Problem: The decision table defines deny as "Do not forward to your model" and flag as "not explicitly denied, but... closely monitored by Creem" with the recommended action "We recommend blocking it as well." So the guidance for both is effectively "block."
Consequence: Developers can't implement meaningfully different handling for flag vs deny, which defeats the point of a three-value decision enum and may lead to over-blocking legitimate prompts.
The fix: Specify a concrete, distinct action for flag (e.g., generate-but-log, soft-warn, or escalate) or document why merchants should treat it identically to deny.
17. SKILL.md size disagrees across the two AI pages (minor)
Problem: The same SKILL.md artifact is described as "a 31KB markdown document" on the For-Humans page and "~32KB" on the For-Agents page.
Consequence: Minor on its own, but the size mismatch undercuts the "complete, precise knowledge base" framing these pages use for AI consumers — if the docs can't agree on the file's size, an agent has no reason to trust the coverage claims attached to it (see issue 9).
The fix: Use one figure for SKILL.md, generated from the actual file, on both pages.
18. One webhook event breaks the past-tense naming convention (minor)
Problem: Every documented webhook event is named in the past tense — checkout.completed, subscription.active, subscription.paid, subscription.canceled, subscription.expired, refund.created, dispute.created — except subscription.update, which uses the present-tense/imperative form. The inconsistency is consistent across both the API Introduction and the Webhooks guide, so it's a naming convention smell rather than a contradiction.
Consequence: An agent (or developer) generating handler names from the pattern — e.g. mapping events to onSubscriptionUpdated — will guess subscription.updated and silently never receive the event, since the real string is subscription.update.
The fix: Rename the event to subscription.updated to match the convention, or call out the exception explicitly in the event table so it isn't auto-inferred wrong.
What they do well
The webhook event reference (/code/webhooks) is complete and internally consistent: 12 named events, a clear creem-signature HMAC-SHA256 scheme, and an explicit note that no static outbound IPs are provided.
The Merchant-of-Record operational docs are unusually concrete — payout dates (1st/15th), $50 minimum, supported payout rails, and billing-cycle support are stated as hard facts useful for planning.
Test/production isolation is clearly stated (separate base hosts, non-interchangeable keys), which prevents a common class of cross-environment mistakes.
Top 3 recommendations
Make machine numbers machine-generated. Endpoint count, webhook event count, SDK list, base URLs, and SKILL.md size should be derived from the OpenAPI spec and the actual files — most contradictions here (24 vs ~42, 10 vs 12, @creem/sdk, /v1) are drift between hand-written claims and reality.
Pick one canonical answer per fact and propagate it. Missing-key status code (401 vs 403), checkout ID prefix (ch_ vs chck_), env-selection mechanism, and PayPal support each have two live answers — choose one and fix every page.
Clean the AI surface first. It's the front door Creem advertises to agents: fix llms.txt's package name, drop the Mintlify starter boilerplate from llms-full.txt, retire/deprecate creem_io in examples, and ship one runnable signature-verification snippet.