docs: add Stripe session retrieval endpoint to OpenAPI specification

[ahmednahima0-beep]

Introduced a new endpoint for retrieving a Stripe checkout session by its client reference ID. The OpenAPI specification now includes detailed descriptions of the endpoint, required parameters, and response schemas for successful and error cases. Additionally, updated the documentation to include a new group for Stripe in the navigation structure.

---

Summary by cubic

Added a GET /api/stripe/sessions endpoint to fetch a Stripe Checkout Session by client reference ID. This supports verifying payment status after checkout redirects and is documented under a new Stripe group.

• New Features
  • OpenAPI: GET /api/stripe/sessions with query params referenceId (required, UUID) and accountId (optional; clarified for org-member accounts); secured by apiKeyAuth and bearerAuth.
  • Responses: 200 returns GetStripeSessionResponse; 400/401/403/404 return AccountErrorResponse.
  • Docs: New page api-reference/stripe/session-get; removed the old sessions list doc; added a "Stripe" group in docs.json.

^{Written for commit 8e3562a. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added a new API endpoint to retrieve Stripe checkout session information, including session ID, status, and checkout URL.

• Documentation

  • Added comprehensive documentation for the new Stripe sessions endpoint with details on parameters and response formats.
  • Updated navigation to surface the new documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new API endpoint documentation for retrieving Stripe checkout sessions via GET /api/stripe/sessions. Includes OpenAPI schema definitions with request/response contracts, corresponding documentation page, and navigation entry to surface the endpoint reference.

Changes

Cohort / File(s)	Summary
API Endpoint Definition api-reference/openapi/accounts.json	Added new GET /api/stripe/sessions endpoint with query parameters (referenceId required UUID, accountId optional UUID). Defined success response schema GetStripeSessionResponse containing Stripe session fields, and error schema GetStripeSessionErrorResponse for HTTP 400/401/404 responses.
Documentation & Navigation api-reference/stripe/sessions-list.mdx, docs.json	Created new documentation page with frontmatter metadata for the "List Stripe Sessions" endpoint. Added "Stripe" group under "Accounts" tab in navigation to expose the endpoint reference.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Stripe sessions now hop into docs with delight,
Schemas and responses all perfectly right!
Navigation guide grows with a new reference home,
Through API fields, stripe-bound endpoints now roam. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately captures the main change: adding a new Stripe session retrieval endpoint documentation to the OpenAPI specification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

api-reference/openapi/accounts.json (1)

3071-3083: Align GetStripeSessionErrorResponse schema with other error response patterns.

GetStripeSessionErrorResponse defines { error: string } while all sibling error schemas (AccountErrorResponse, SubscriptionErrorResponse, OrganizationsErrorResponse) include a status: "error" field. Since SubscriptionErrorResponse already uses the error field (alongside status), consider adding a status field to GetStripeSessionErrorResponse for consistency across the OpenAPI spec, or document why this endpoint diverges from the established error response pattern.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi/accounts.json` around lines 3071 - 3083,
GetStripeSessionErrorResponse currently only defines { error: string } and
should be made consistent with other error schemas; update the
GetStripeSessionErrorResponse schema to include a "status" property with fixed
value "error" (e.g., "type": "string", "enum": ["error"]) and add "status" to
the required array so the schema becomes { status: "error", error: string } to
match AccountErrorResponse/SubscriptionErrorResponse/OrganizationsErrorResponse
patterns.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@api-reference/openapi/accounts.json`:
- Around line 445-454: The parameter accountId on the /api/stripe/sessions
operation claims an "Admin-only override" but the operation lacks a 403 response
and its error schema (GetStripeSessionErrorResponse {error: string}) is
inconsistent with the rest of the spec; either add a 403 response or change the
parameter text to the organization-membership wording, and standardize the error
schema to AccountErrorResponse. Concretely: in the /api/stripe/sessions
operation update the accountId parameter (replace "Admin-only override" with
"Only applicable when the authenticated account has access to multiple accounts
via organization membership" if you prefer the org wording) or add a 403
response object with description "Forbidden - account override not permitted"
and use AccountErrorResponse as the response schema; also replace
GetStripeSessionErrorResponse with AccountErrorResponse (or map its shape to
match AccountErrorResponse) so the endpoint uses the same {status, message}
error format.

In `@api-reference/stripe/sessions-list.mdx`:
- Around line 1-4: The page title and filename misdescribe the endpoint: change
the title in api-reference/stripe/sessions-list.mdx from "List Stripe Sessions"
to "Get Stripe Session" (or "Retrieve Stripe Session"), rename the file/slug
(sessions-list → session-get or session-retrieve) and update any docs.json nav
entry that references the old slug/title so the page reflects that GET
/api/stripe/sessions returns a single GetStripeSessionResponse by referenceId
rather than a list.

---

Nitpick comments:
In `@api-reference/openapi/accounts.json`:
- Around line 3071-3083: GetStripeSessionErrorResponse currently only defines {
error: string } and should be made consistent with other error schemas; update
the GetStripeSessionErrorResponse schema to include a "status" property with
fixed value "error" (e.g., "type": "string", "enum": ["error"]) and add "status"
to the required array so the schema becomes { status: "error", error: string }
to match
AccountErrorResponse/SubscriptionErrorResponse/OrganizationsErrorResponse
patterns.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f6228e24-f5f4-400e-b432-7f3daeb23cde

📥 Commits

Reviewing files that changed from the base of the PR and between ea3c08a and 600b9fc.

📒 Files selected for processing (3)

• api-reference/openapi/accounts.json
• api-reference/stripe/sessions-list.mdx
• docs.json

[cubic-dev-ai]

2 issues found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/stripe/sessions-list.mdx">

<violation number="1" location="api-reference/stripe/sessions-list.mdx:2">
P3: The title implies a collection endpoint, but this route retrieves a single Stripe session by `referenceId`. Rename the page title to reflect single-resource retrieval.</violation>
</file>

<file name="api-reference/openapi/accounts.json">

<violation number="1" location="api-reference/openapi/accounts.json:448">
P2: The `accountId` description declares an admin-only override, but this operation does not document a `403` forbidden response for unauthorized override attempts. Add `403` or adjust the description to match the actual authorization behavior.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}