docs: add Stripe session status endpoint to OpenAPI specification

[ahmednahima0-beep]

Introduced a new endpoint /api/stripe/session/status to confirm the processing of a Stripe checkout session. The documentation includes detailed descriptions of request parameters, response schemas, and error handling for various scenarios. Additionally, updated the navigation in docs.json to include the new Stripe group and its corresponding page.

---

Summary by cubic

Add /api/stripe/session/status to the OpenAPI spec and docs. Clients can confirm a Stripe Checkout session and trigger credit provisioning after redirect.

• New Features
  • Documented POST /api/stripe/session/status in api-reference/openapi/accounts.json with apiKeyAuth/bearerAuth, JSON body ConfirmStripeSessionRequest (sessionId required, accountId optional), and 200/400/401/403 responses.
  • Added ConfirmStripeSessionRequest and StripeSessionStatusResponse schemas (id, status = open|complete|expired, metadata with credit_updated).
  • Created api-reference/stripe/session-status.mdx and added a new "Stripe" group in docs.json.

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

Summary by CodeRabbit

• New Features

  • New API endpoint added to confirm and retrieve Stripe checkout session status following payment redirect, with optional metadata support for session tracking

• Documentation

  • New documentation page created for the Stripe session confirmation endpoint, detailing request parameters, authentication requirements, and possible error responses

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a new Stripe checkout session status confirmation API endpoint to the OpenAPI specification, along with corresponding documentation page and navigation group. The endpoint accepts a session ID and returns confirmation status with optional metadata.

Changes

Cohort / File(s)	Summary
Stripe Session Status Endpoint api-reference/openapi/accounts.json, api-reference/stripe/session-status.mdx, docs.json	Introduced GET /api/stripe/session/status endpoint with sessionId (required) and accountId (optional UUID) query parameters, returning StripeSessionStatusResponse schema containing session ID, status enum (open|complete|expired), and optional metadata. Added documentation page and navigation group entry under Accounts tab.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A Stripe session hops on by,
Status checked to the sky,
Complete or open, expired too,
This endpoint's shiny and new! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a new Stripe session status endpoint to the OpenAPI specification with supporting documentation.
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: 1

🧹 Nitpick comments (1)

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

418-498: Documented GET performs a state mutation — consider documenting idempotency/replay semantics, or flagging the API to use POST.

The description states this endpoint "Updates the session metadata with a credit_updated marker" and "Should be called once after a successful checkout redirect to trigger credit provisioning." Using GET for a non-idempotent, credit-provisioning side effect deviates from REST conventions and makes the endpoint vulnerable to accidental re-invocation (browser prefetch, retries, link previews, crawlers hitting a shared URL).

This is a docs PR so the HTTP method reflects the existing backend, but it's worth either:

• raising with the API team to move this to POST (or PATCH), or
• explicitly documenting in the description that the endpoint is safe to call repeatedly (idempotent on the server side — subsequent calls are a no-op once credit_updated is set).

The second option at minimum prevents readers of the docs from worrying about double-crediting.

🤖 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 418 - 498, The documented
GET for "/api/stripe/session/status" performs a state mutation (updates session
metadata with a `credit_updated` marker); either change the operation to a
non-GET verb (e.g., replace "get" with "post" or "patch" in the
"/api/stripe/session/status" operation) and update servers/parameters/responses
accordingly, or explicitly update the operation description to state the
endpoint is idempotent and safe to call repeatedly (explain that subsequent
calls are no-ops once `credit_updated` is set) and add guidance about
replay/consumer expectations so readers know it won’t double-credit; reference
the operation under "/api/stripe/session/status" and the response schema
StripeSessionStatusResponse when updating docs.

🤖 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 444-453: Update the "accountId" query parameter description to
explicitly state its relation to the session's embedded account
(metadata.accountId): clarify that "accountId" is used only for
authorization/scoping by organization-scoped API keys and must match the
session's metadata.accountId when provided (it does not override the session's
embedded account), e.g., append one sentence to the existing description
referencing the response field metadata.accountId and saying the parameter must
match that value if supplied.

---

Nitpick comments:
In `@api-reference/openapi/accounts.json`:
- Around line 418-498: The documented GET for "/api/stripe/session/status"
performs a state mutation (updates session metadata with a `credit_updated`
marker); either change the operation to a non-GET verb (e.g., replace "get" with
"post" or "patch" in the "/api/stripe/session/status" operation) and update
servers/parameters/responses accordingly, or explicitly update the operation
description to state the endpoint is idempotent and safe to call repeatedly
(explain that subsequent calls are no-ops once `credit_updated` is set) and add
guidance about replay/consumer expectations so readers know it won’t
double-credit; reference the operation under "/api/stripe/session/status" and
the response schema StripeSessionStatusResponse when updating docs.

🪄 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: 06f20fd8-41f4-4770-b668-35674e01114e

📥 Commits

Reviewing files that changed from the base of the PR and between ea3c08a and 6a3fae0.

📒 Files selected for processing (3)

• api-reference/openapi/accounts.json
• api-reference/stripe/session-status.mdx
• docs.json

[cubic-dev-ai]

1 issue 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/openapi/accounts.json">

<violation number="1" location="api-reference/openapi/accounts.json:419">
P2: State-changing Stripe session confirmation/credit provisioning is modeled as GET, violating HTTP safe-method semantics and risking unintended execution via caches/prefetch/SDK assumptions.</violation>
</file>

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