docs(openapi): add subscription portal creation endpoint

api-reference/openapi/accounts.json

@@ -480,6 +480,62 @@
         }
       }
     },
+    "/api/subscriptions/portal": {
+      "post": {
+        "description": "Create a subscription management session for the authenticated account. Returns a hosted URL where the customer can update payment method, view invoices, or cancel. The client should redirect the user to that URL.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "description": "Portal session parameters",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateSubscriptionPortalRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Portal session created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreateSubscriptionPortalResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - missing or invalid parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionPortalErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - invalid or missing authentication",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionPortalErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/workspaces": {
       "post": {
         "description": "Create a new workspace account. Workspaces can optionally be linked to an organization.",
@@ -2974,6 +3030,54 @@
             "example": "successUrl is required"
           }
         }
+      },
+      "SubscriptionPortalErrorResponse": {
+        "type": "object",
+        "required": [
+          "error"
+        ],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Human-readable error message.",
+            "example": "returnUrl is required"
+          }
+        }
+      },
+      "CreateSubscriptionPortalRequest": {
+        "type": "object",
+        "required": [
+          "returnUrl"
+        ],
+        "description": "Request body for creating a billing portal session. The account is determined from authentication (API key or session), not from this payload.",
+        "properties": {
+          "returnUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "The URL to redirect to when the customer leaves the portal.",
+            "example": "https://chat.recoupable.com/settings/billing"
+          }
+        }
+      },
+      "CreateSubscriptionPortalResponse": {
+        "type": "object",
+        "required": [
+          "id",
+          "url"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The portal session ID.",
+            "example": "portal_sess_a1b2c3d4"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The hosted portal URL. Redirect to this URL so the customer can manage their subscription.",
+            "example": "https://billing.example.com/manage/portal_sess_a1b2c3d4"
+          }
+        }
       }
     }
   }

api-reference/subscriptions/portal-create.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Create Subscription Portal'
+openapi: '/api-reference/openapi/accounts.json POST /api/subscriptions/portal'
+---

docs.json

@@ -312,6 +312,7 @@
             "group": "Subscriptions",
             "pages": [
               "api-reference/subscriptions/sessions-create",
+              "api-reference/subscriptions/portal-create",
               "api-reference/accounts/subscription-get"
             ]
           },