From 0cf0df802270450323fa039a680c64e99bafdff1 Mon Sep 17 00:00:00 2001
From: john <ahmednahima0@gmail.com>
Date: Tue, 21 Apr 2026 12:47:08 +0700
Subject: [PATCH] docs: add Stripe billing portal session endpoint to OpenAPI
 specification

- Introduced a new POST endpoint at /api/stripe/portal for creating a Stripe billing portal session.
- Added detailed request and response schemas for CreateStripePortalRequest and CreateStripePortalResponse.
- Updated docs.json to include the new Stripe portal documentation in the navigation structure.
---
 api-reference/openapi/accounts.json    | 118 +++++++++++++++++++++++++
 api-reference/stripe/portal-create.mdx |   4 +
 docs.json                              |   6 ++
 3 files changed, 128 insertions(+)
 create mode 100644 api-reference/stripe/portal-create.mdx

diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json
index 4ad84341..ad9bff99 100644
--- a/api-reference/openapi/accounts.json
+++ b/api-reference/openapi/accounts.json
@@ -415,6 +415,77 @@
         }
       }
     },
+    "/api/stripe/portal": {
+      "post": {
+        "servers": [
+          {
+            "url": "https://api.recoupable.com"
+          }
+        ],
+        "description": "Create a Stripe billing portal session for the authenticated account. The account must have an active Stripe subscription. Returns a Stripe-hosted portal URL that the client should redirect the user to, allowing them to manage their subscription, update payment methods, or cancel.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "description": "Billing portal session parameters",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStripePortalRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Billing portal session created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreateStripePortalResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request — missing or invalid parameters, or no active subscription found for the account",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized — invalid or missing authentication",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - account override not permitted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/workspaces": {
       "post": {
         "description": "Create a new workspace account. Workspaces can optionally be linked to an organization.",
@@ -2934,6 +3005,53 @@
             "example": "Verified"
           }
         }
+      },
+      "CreateStripePortalRequest": {
+        "type": "object",
+        "required": [
+          "returnUrl"
+        ],
+        "properties": {
+          "returnUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "The URL to redirect the user to after they leave the billing portal.",
+            "example": "https://chat.recoupable.com/settings"
+          },
+          "accountId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Filter to a specific account. Only applicable when the authenticated account has access to multiple accounts via organization membership; if not provided, the API key's own account is used.",
+            "example": "123e4567-e89b-12d3-a456-426614174000"
+          }
+        }
+      },
+      "CreateStripePortalResponse": {
+        "type": "object",
+        "description": "A Stripe billing portal session. For the full list of available properties, see the [Stripe Billing Portal Session API documentation](https://docs.stripe.com/api/customer_portal/sessions/object).",
+        "required": [
+          "id",
+          "url"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for the Stripe billing portal session.",
+            "example": "bps_test_a1b2c3d4e5f6g7h8i9j0"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The Stripe-hosted billing portal URL. Redirect the user to this URL to manage their subscription.",
+            "example": "https://billing.stripe.com/session/bps_test_a1b2c3d4e5f6g7h8i9j0"
+          },
+          "return_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The URL the user will be redirected to after leaving the billing portal.",
+            "example": "https://chat.recoupable.com/settings"
+          }
+        }
       }
     }
   }
diff --git a/api-reference/stripe/portal-create.mdx b/api-reference/stripe/portal-create.mdx
new file mode 100644
index 00000000..8faa28a7
--- /dev/null
+++ b/api-reference/stripe/portal-create.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Create Billing Portal Session'
+openapi: '/api-reference/openapi/accounts.json POST /api/stripe/portal'
+---
diff --git a/docs.json b/docs.json
index 997442ca..81587520 100644
--- a/docs.json
+++ b/docs.json
@@ -331,6 +331,12 @@
               "api-reference/subscriptions/get"
             ]
           },
+          {
+            "group": "Stripe",
+            "pages": [
+              "api-reference/stripe/portal-create"
+            ]
+          },
           {
             "group": "Admins",
             "pages": [