feat(billing): show invoice descriptions and cap in-app list at 5

[waleedlatif1]

Summary

• The in-app Invoices widget now shows each invoice's line-item description ("Usage overage", "Sim Max", "Sim Pro") — the same metadata Stripe's hosted portal shows, but previously never fetched into our own UI. Extracted from the invoice's top-level description, falling back to the primary line item's description.
• Capped the in-app list at 5 most-recent invoices (was 10). "View all" (which opens the Stripe billing portal for the full history) already appears whenever there are more.

Changes

• app/api/billing/invoices/route.ts — expand: ['data.lines'] on the Stripe list call, map a description field, MAX_INVOICES 10 → 5.
• lib/api/contracts/subscription.ts — add description: string | null to the invoice contract.
• billing.tsx — render the description in each row; add it to the row view-model.
• route.test.ts — updated the two MAX_INVOICES-bound assertions and added coverage for description extraction/precedence.

Type of Change

• New feature / improvement

Testing

• vitest on the invoices route (5/5 passing, incl. new description test)
• Typecheck clean on changed files; biome clean; check:api-validation passes

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jul 17, 2026 9:38pm

[cursor]

PR Summary

Low Risk
Display and read-path billing changes with contract/tests updated; no auth, payment capture, or limit-mutation logic touched.

Overview
Billing settings invoice rows now show what each charge was for (plan name, usage overage, etc.) and only the five most recent finalized invoices in-app, with View all still driven by hasMore.

The invoices API lowers MAX_INVOICES from 10 to 5, expands Stripe line items on list, and returns a nullable description (invoice-level text first, else the first line item with a description). STRIPE_PAGE_SIZE is decoupled at 20 so the smaller UI cap does not shrink draft-pagination and accidentally hide finalized invoices behind long draft tails.

The subscription API contract and billing settings UI pass through and render the new description in each row.

^{Reviewed by Cursor Bugbot for commit 6e958c7. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds invoice descriptions to the in-app billing history and reduces the visible list size. The main changes are:

• Fetch and map Stripe invoice and line-item descriptions.
• Add the nullable description to the shared API contract.
• Display descriptions in invoice rows.
• Show five recent invoices while preserving pagination and View all behavior.
• Update route tests for the new limit and description precedence.

Confidence Score: 5/5

This looks safe to merge.

• The updated pagination path preserves overflow and Stripe continuation signals.
• Description mapping consistently returns a string or null as required by the shared contract.
• The latest test changes exercise the corrected pagination flow.
• No blocking issues were found in the changed code.

Important Files Changed

Filename	Overview
apps/sim/app/api/billing/invoices/route.ts	Adds description extraction, lowers the display cap, and keeps the Stripe scan size independent from that cap.
apps/sim/app/api/billing/invoices/route.test.ts	Updates list-limit expectations and adds coverage for description fallback and precedence.
apps/sim/app/workspace/[workspaceId]/settings/components/billing/billing.tsx	Adds the invoice description to the row model and renders it in the billing list.
apps/sim/lib/api/contracts/subscription.ts	Adds a required nullable description field to the shared invoice response schema.

_{Reviews (3): Last reviewed commit: "fix(billing): decouple Stripe scan page ..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 6e958c7. Configure here.}