Docs Guardian sweep — 2026-08-17 (slice 4: invoicing, one-off invoices, emails)

[sarkissianraffi]

Docs Guardian sweep — 2026-08-17 (slice 4: invoicing, one-off invoices, emails)

Automated documentation sweep. A human must review and merge — this agent never merges.

Weekly cadence this run, so the rotation slice was picked as ISO week % 10 (week 34 → slice 4) rather than the skill's twice-weekly formula.

Fixed in this PR

Type	Count	Notes
Inaccuracies	12	each listed below with evidence
Typos	12	incl. 8 __YOU_*_ID__ → __YOUR_*_ID__ placeholders
Broken links	0	none confirmed dead
Broken images	0	none confirmed broken
Tone / verbosity	31	across 13 pages
Missing examples added	1	invoice metadata API example
Wrong payloads	7	invalid JSON in example bodies

27 files changed, well under the 40-file cap.

---

Inaccuracy fixes (evidence required)

Wrong HTTP verb — PUT /customers does not exist

• guide/invoicing/invoicing-settings/net-payment-term.mdx, guide/invoicing/invoicing-settings/taxes.mdx: PUT → POST on /api/v1/customers — evidence: lago-api config/routes.rb:46 declares resources :customers, param: :external_id, only: %i[create index show destroy] (no update route); the published spec lists only post and get on /customers. 28 other doc pages already use POST.

Wrong customer identifier field

• guide/invoicing/invoicing-settings/taxes.mdx: "code": "acme_inc" → "external_id": "acme_inc" — evidence: CustomerCreateInput requires external_id and has no code property.

Wrong wrapper key and missing nesting on billing-entity payloads

• guide/invoicing/invoicing-settings/grace-period.mdx: "organization" → "billing_entity", and invoice_grace_period moved under billing_configuration — evidence: billing_entities_controller.rb:70/103 uses params.require(:billing_entity).permit(..., billing_configuration: [:invoice_footer, :invoice_grace_period, ...]).
• guide/invoicing/invoicing-settings/overview.mdx: invoice_footer and document_locale moved under billing_configuration (same evidence). The page's own prose already said document_locale lives in billing_configuration, so the example contradicted the text.

Wrong field name

• guide/invoicing/fees.mdx: regroup_paid_fee → regroup_paid_fees — evidence: 14 occurrences of the plural in the published spec, 0 of the singular; rate_card.rb:34 defines enum :regroup_paid_fees. Every other doc page uses the plural.

Terminology drift: organization vs billing entity

• guide/invoicing/invoicing-settings/empty-invoices.mdx: customers inherit finalize_zero_amount_invoice from the billing entity, not the organization; code-block title "Update the organization's settings" → "billing entity's" (the call targets /billing_entities/{code}).
• guide/invoicing/invoicing-settings/grace-period.mdx: "the organization's grace period" → "the billing entity's", matching the section heading and the endpoint used.

Copy-paste error

• guide/invoicing/invoicing-settings/overview.mdx: the Translate invoices tab said "You can update the customer footer of invoices by changing the document_locale" — rewritten to describe the document language. The custom footer tab also called a universal footer a "customer footer", contradicting the paragraph above it.

Add-on deletion scope

• guide/one-off-invoices/create-add-ons.mdx: "removes the add-on from all plans and subscriptions where it is used" → removes the add-on and the fixed charges that use it from plans; already-issued invoices are unchanged — evidence: AddOns::DestroyService calls add_on.discard! and add_on.fixed_charges.update_all(deleted_at:); subscriptions are not touched.

Contradictory sentence

• guide/invoicing/fees.mdx: "embedded within an invoice or credit note object, making it retrievable on its own" → "…, but it can also be retrieved on its own" — evidence: /fees/{lago_id} exists in the spec.

Missing documented constraint

• guide/invoicing/invoice-metadata.mdx: added "Keys must be unique within an invoice" — evidence: Metadata::InvoiceMetadata validates key with uniqueness: {scope: :invoice_id}. (The existing limits of 5 pairs / 20-char keys / 140-char values were verified correct against COUNT_PER_INVOICE = 5 and the length validations.)

Wrong payloads — invalid JSON in example bodies

All found by parsing every --data-raw body in the repo. These would fail if a reader copy-pasted them:

• guide/dunning/manual-dunning.mdx: doubled opening brace '{ {
• guide/wallet-and-prepaid-credits/wallet-top-up-and-void.mdx: missing colon in "value" "manual-void"; missing commas after "method": "fixed" (×2) and after "threshold_credits"
• guide/plans/charges/invoiceable-vs-noninvoiceable.mdx: missing comma after "regroup_paid_fees"
• guide/subscriptions/edit-subscription.mdx: trailing comma after "group_properties": []
• guide/invoicing/previews.mdx: trailing comma after "plan_code": "new_plan"

Also fixed structurally broken examples in slice 4: unbalanced braces and a missing comma in credit-notes/credit-note-metadata.mdx, and a missing comma plus a trailing comma in invoicing-settings/grace-period.mdx.

Typos and mechanical fixes

__YOU_INVOICE_ID__ → __YOUR_INVOICE_ID__ (7) and __YOU_CREDIT_NOTE_ID__ → __YOUR_CREDIT_NOTE_ID__ (1); **LAGO_INVOICE_ID** → __LAGO_INVOICE_ID__; "Overriden" → "Overridden" (×2); "recomend" → "recommend"; "everytime" → "every time"; "(add ons)" → "(add-ons)"; "an Cross Industry Invoice" → "a"; "european" → "European"; "premium licence" → "license"; "below.:" → "below:"; unbalanced **"Invoice custom section**; four-backtick fences closing three-backtick blocks (×2); `net_payment_term argument` backtick placement (also removed two stray non-breaking spaces); "Filter invoice by" → "Filter invoices by"; "all customers invoices" → "all customer invoices".

Tone and verbosity

Applied the tone guide and the recorded convention against em-dashes (this diff introduces zero em-dashes and removes five existing ones). Highlights: removed marketing fluff and an exclamation mark from taxes.mdx; removed "sit back and relax" / "we take care of it" from emails.mdx and switched first person to Lago; present tense instead of "will" across download-invoices.mdx, previews.mdx, void.mdx, create-one-off-invoices.mdx; removed "kindly note", "Please note that", "As mentioned above/previously", "Here are a few things to keep in mind"; title-case headings to sentence case; deleted a duplicated "Use an add-on" section that repeated the page intro verbatim; replaced the dangling "Please follow this page to know more about these actions." in grace-period.mdx with a real link to the draft-invoices page; and aligned the void.mdx API tab with the placeholder convention used elsewhere on the same page.

Missing examples added

• guide/invoicing/invoice-metadata.mdx documented editing metadata via the API but contained no code at all. Added a PUT /invoices/{lago_id} example validated against InvoiceUpdateInput, showing both updating an existing pair (with id) and creating a new one (without id).

---

Needs human confirmation (not changed)

• guide/emails.mdx: the prerequisites say to turn scenarios on in Settings > [Your billing entity] > Email scenarios, but the steps below say Settings > Emails tab. One of the two UI labels is stale; I could not verify the current label from the repo or the API. The three scenarios themselves are correct (EMAIL_SETTINGS = ["invoice.finalized", "credit_note.created", "payment_receipt.created"]).
• guide/invoicing/invoicing-settings/taxes.mdx: the Tax hierarchy section uses "Billing entity taxes" for subscription invoices but "Organization taxes" for one-off invoices. This looks like pre-billing-entity drift, but changing tax precedence semantics needs someone who knows whether the two genuinely differ.
• guide/one-off-invoices/create-add-ons.mdx creates an add-on with code setup, while create-one-off-invoices.mdx consumes setup_fee. The examples do not chain. Harmless individually; worth aligning if you want the pages read in sequence.
• changelog/product.mdx:751 is the only image reference in the repo using a relative ./images/… path (96 siblings use /changelog/images/…). It renders correctly on the live site, so it is not broken and I left the changelog untouched per the changelog-only-fix-breakage rule. Flagging as a consistency nit.
• 10 pages are not reachable from docs.json navigation (orphans), including guide/payments/stripe-integration, integrations/payments/custom-payment-integration, templates/payg/aws, templates/payg/klaviyo, templates/per-transaction/column, templates/per-transaction/swan, and four snippets/templates/*. Snippets are expected to be unreferenced; the others may be intentional or may be lost pages. Not deleted, per policy.

Suspected spec issues (for the OpenAPI guardian)

• BillingEntityUpdateInput is missing its request wrapper. The schema exposes name, default_currency, … at the top level, but billing_entities_controller.rb does params.require(:billing_entity). The docs (and this PR) use the "billing_entity": {...} wrapper, which matches the code. The spec appears wrong.
• units typed as string-only on one-off invoice fees. InvoiceOneOffCreateInput.fees[].units is ["string","null"] with a numeric pattern, but the docs pass integers ("units": 1) and Rails coerces both. Worth confirming whether the spec should also allow integers.

Deferred to next run

• 132 legacy [](#anchor "Direct link to heading") artifacts across 31 files. These are redundant under Mintlify's auto-generated anchors, but removing them would touch far more files than this sweep should, and at least one anchor (grace-period.mdx's #define-a-grace-period-at-organization-level) no longer matches its heading. Worth a dedicated mechanical PR.
• External link verification returned zero confirmed-dead URLs out of 285 unique. 18 returned 403/405/timeout (LinkedIn, npm, Intuit, Salesforce, Medium, Docker Hub) and are treated as unverifiable, not broken. http://pdf:3000 is a docker-compose service name in the self-hosted guide and is correct as written.

Process feedback for the retro

• The payload check as specified only extracted --data / -d curl bodies. Nearly every Lago doc example uses --data-raw, so the first pass reported 60 JSON blocks and missed 7 genuinely broken payloads across the repo. The check should match --data-raw explicitly, and should skip bodies containing $(...) command substitution (two api-reference/events/* examples use $(date +%s) and are valid as written).
• The internal-link check needs to strip query strings before resolving a path: /api-reference/customers/get-all?playground=open was reported as broken when the page exists.

---

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
lago	🟢 Ready	View Preview	Aug 17, 2026, 7:44 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
lago-docs	🟢 Ready	View Preview	Aug 17, 2026, 7:44 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[sarkissianraffi]

📝 Slack announcement (posted here — Slack was unreachable this run)

No Slack tooling is available in this run's environment (no Slack MCP tools, no webhook), so per the skill's failure handling the #documentation announcement is recorded here instead. A human should copy this into #documentation.

📝 Docs Guardian — sweep of 2026-08-17 (slice 4: invoicing, one-off invoices, emails)
PR ready for human review: #642
Fixed: 12 inaccuracies · 12 typos · 0 broken links · 0 broken images · 31 tone/verbosity edits · 1 example added · 7 payload fixes
⚠️ Needs a human decision: stale UI label in emails.mdx (Email scenarios vs Emails tab); "Organization" vs "Billing entity" in the one-off tax hierarchy; 10 pages orphaned from docs.json nav; 2 suspected spec issues handed to the OpenAPI guardian.
⏳ Still awaiting review: none (no other open guardian PRs).
I never merge — please review and merge when ready.

Run notes for the record:

• No open guardian PRs existed at the start of this run, so there was no outstanding human feedback to address. The most recent merged guardian PR (Docs Guardian sweep — 2026-08-11 (slice 6: coupons, analytics, alerts, webhooks, AI agents) #636) had one review comment, "Changes LGTM" from a verified write-access maintainer, with no actionable request and no durable rule to record.
• LEARNINGS.md was loaded from the private skills repo and applied — notably the no-em-dash rule (this diff introduces zero em-dashes and removes five) and the rule to leave removed /api-reference/analytics/* links alone.
• No LEARNINGS.md PR was opened: nothing in this run was backed by an identifiable new human comment, and entries may not be added by inference.

[phfrc]

1. guide/emails.mdx — UI label mismatch

Checked lago-front: the settings route is BILLING_ENTITY_EMAIL_SCENARIOS_ROUTE, and the tab label used in BillingEntityMain.tsx:44 / BillingEntityEmailScenariosConfig.tsx is translation key text_1742367202528mfhsv0f4fxq = "Email scenarios". So the prerequisites line ("Settings > [Your billing entity] > Email scenarios") is correct, and the steps section ("Open the Emails tab") is the stale one.

Fix: change step 2 from "Open the Emails tab" to "Open the Email scenarios tab" (or "section", matching current UI copy).

[phfrc]

2. guide/invoicing/invoicing-settings/taxes.mdx — tax hierarchy for one-off invoices

Checked Fees::ApplyTaxesService#applicable_taxes in lago-api — the billing-entity-level fallback (Tax.joins(:billing_entities_taxes).where(billing_entity_id: customer.billing_entity_id)) applies uniformly to every fee type, subscription or one-off. There's no separate organization-level tax fallback in code. So "Organization taxes" in the one-off-invoices hierarchy section is the same terminology drift already fixed in the subscription-invoices section above it, not a genuine semantic difference.

Fix: change "Organization taxes apply to all fees" → "Billing entity taxes apply to all fees" and "override organization taxes" → "override billing entity taxes" in the one-off invoices hierarchy list, matching the subscription section's wording.

[phfrc]

changelog/product.mdx:751 relative image path

Re-verified: 1 relative ./images/... path vs. 96 absolute /changelog/images/... paths in the same file; Mintlify resolves relative paths against the file's own directory, so it renders fine. Leave it — this is a durable decision, not something to keep re-flagging as a consistency nit in future sweeps.

[claude]

Per Michael Ponrajah's review point that Mintlify fence annotations should be preserved, I restored the two {28} line highlights this sweep dropped from guide/invoicing/invoicing-settings/grace-period.mdx (both Add a grace period on the... blocks). The corrected organization to billing entity titles are kept; only the annotation was added back. I checked every fence info string changed in this PR against main and these two were the only annotations lost.

---

Generated by Claude Code

[phfrc]

✅

[michaelponrajah]

guide/emails.mdx, line 12 🔴 must fix

This rewrite changed the meaning, and now contradicts the rest of the page:

1. It asserts something opt-in as automatic. Line 40 says "By default, all scenarios are switched off", and the Prerequisites list above requires turning them on. The old wording ("you can automatically email them") was correct.
2. Wrong trigger. Per the scenario list on line 35, invoices are emailed when they are finalized, not created — draft invoices are never emailed.
3. Incomplete. Payment receipts are scenario 2 of 3 and dropped out.

Lago can automatically email invoices, payment receipts and credit notes to your customers. All email scenarios are off by default — turn on the ones you need.

[michaelponrajah]

guide/invoicing/invoicing-settings/overview.mdx, line 28

Nice fix on the missing closing quote in step 3 — the label in step 2 is also wrong. lago-front calls this section "Invoice custom sections" (base.json → text_1749024634192ov41w9fp6r2), not "Invoice section".

2. Open the **"Invoice custom sections"** tab;

[claude]

Applied your guide/emails.mdx intro rewrite in 4a0ad85, with one deviation from the literal suggestion: the em-dash became "so" ("off by default, so turn on the ones you need") to keep the recorded no-em-dash convention for docs prose. Say the word if you'd rather have your exact punctuation.

---

Generated by Claude Code