From e0488667dd8d5d04260d198a23db2291a5bf7f28 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Fri, 1 May 2026 19:33:23 +0530 Subject: [PATCH 1/2] docs(docs): migrate POST /api/stripe/portal/create Documents the new POST /api/subscriptions/portal-sessions endpoint that pairs with the existing POST /api/subscriptions/sessions for chat's stripe-outbound migration (group 4). --- api-reference/openapi/accounts.json | 100 ++++++++++++++++++ .../subscriptions/portal-sessions-create.mdx | 4 + docs.json | 3 +- 3 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 api-reference/subscriptions/portal-sessions-create.mdx diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json index 6765228..f8dc7ca 100644 --- a/api-reference/openapi/accounts.json +++ b/api-reference/openapi/accounts.json @@ -410,6 +410,72 @@ } } }, + "/api/subscriptions/portal-sessions": { + "post": { + "description": "Create a Stripe billing portal session for the authenticated account's existing Stripe customer. Returns a hosted portal URL that the client should redirect to so the customer can manage their subscription, payment methods, and invoices.", + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ], + "requestBody": { + "description": "Portal session parameters", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreatePortalSessionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Portal session created successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreatePortalSessionResponse" + } + } + } + }, + "400": { + "description": "Bad request - missing or invalid parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubscriptionSessionErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized - invalid or missing authentication", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubscriptionSessionErrorResponse" + } + } + } + }, + "404": { + "description": "No Stripe customer linked to this account", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubscriptionSessionErrorResponse" + } + } + } + } + } + } + }, "/api/workspaces": { "post": { "description": "Create a new workspace account. Workspaces can optionally be linked to an organization.", @@ -2848,6 +2914,40 @@ "example": "successUrl is required" } } + }, + "CreatePortalSessionRequest": { + "type": "object", + "required": [ + "returnUrl" + ], + "properties": { + "returnUrl": { + "type": "string", + "format": "uri", + "description": "The URL to redirect the customer to after they exit the billing portal.", + "example": "https://chat.recoupable.com" + } + } + }, + "CreatePortalSessionResponse": { + "type": "object", + "required": [ + "id", + "url" + ], + "properties": { + "id": { + "type": "string", + "description": "The billing portal session ID.", + "example": "bps_test_a1b2c3d4e5f6g7h8i9j0" + }, + "url": { + "type": "string", + "format": "uri", + "description": "The hosted billing portal URL. Redirect the customer here to manage their subscription.", + "example": "https://billing.stripe.com/p/session/test_a1b2c3d4e5f6g7h8i9j0" + } + } } } } diff --git a/api-reference/subscriptions/portal-sessions-create.mdx b/api-reference/subscriptions/portal-sessions-create.mdx new file mode 100644 index 0000000..27b5958 --- /dev/null +++ b/api-reference/subscriptions/portal-sessions-create.mdx @@ -0,0 +1,4 @@ +--- +title: 'Create Billing Portal Session' +openapi: '/api-reference/openapi/accounts.json POST /api/subscriptions/portal-sessions' +--- diff --git a/docs.json b/docs.json index 0ea3137..c503020 100644 --- a/docs.json +++ b/docs.json @@ -319,7 +319,8 @@ { "group": "Subscriptions", "pages": [ - "api-reference/subscriptions/sessions-create" + "api-reference/subscriptions/sessions-create", + "api-reference/subscriptions/portal-sessions-create" ] }, { From bab7126acee32e26876257ec008dcb7aaabb0eb4 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Fri, 1 May 2026 19:45:08 +0530 Subject: [PATCH 2/2] refactor(docs): rename to /api/stripe/{checkout,portal}-sessions Per CHAT_API_MIGRATION_FINDINGS REST cleanup section, update paths and nav group to align with the dedicated API: /api/subscriptions/sessions -> /api/stripe/checkout-sessions /api/subscriptions/portal-sessions -> /api/stripe/portal-sessions Subscriptions nav group -> Stripe --- api-reference/openapi/accounts.json | 4 ++-- api-reference/stripe/checkout-sessions-create.mdx | 4 ++++ api-reference/stripe/portal-sessions-create.mdx | 4 ++++ api-reference/subscriptions/portal-sessions-create.mdx | 4 ---- api-reference/subscriptions/sessions-create.mdx | 4 ---- docs.json | 6 +++--- 6 files changed, 13 insertions(+), 13 deletions(-) create mode 100644 api-reference/stripe/checkout-sessions-create.mdx create mode 100644 api-reference/stripe/portal-sessions-create.mdx delete mode 100644 api-reference/subscriptions/portal-sessions-create.mdx delete mode 100644 api-reference/subscriptions/sessions-create.mdx diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json index f8dc7ca..e00dfcf 100644 --- a/api-reference/openapi/accounts.json +++ b/api-reference/openapi/accounts.json @@ -354,7 +354,7 @@ } } }, - "/api/subscriptions/sessions": { + "/api/stripe/checkout-sessions": { "post": { "description": "Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. The session is pre-configured with a 30-day trial period.", "security": [ @@ -410,7 +410,7 @@ } } }, - "/api/subscriptions/portal-sessions": { + "/api/stripe/portal-sessions": { "post": { "description": "Create a Stripe billing portal session for the authenticated account's existing Stripe customer. Returns a hosted portal URL that the client should redirect to so the customer can manage their subscription, payment methods, and invoices.", "security": [ diff --git a/api-reference/stripe/checkout-sessions-create.mdx b/api-reference/stripe/checkout-sessions-create.mdx new file mode 100644 index 0000000..fe62eb8 --- /dev/null +++ b/api-reference/stripe/checkout-sessions-create.mdx @@ -0,0 +1,4 @@ +--- +title: 'Create Checkout Session' +openapi: '/api-reference/openapi/accounts.json POST /api/stripe/checkout-sessions' +--- diff --git a/api-reference/stripe/portal-sessions-create.mdx b/api-reference/stripe/portal-sessions-create.mdx new file mode 100644 index 0000000..5c2ff5f --- /dev/null +++ b/api-reference/stripe/portal-sessions-create.mdx @@ -0,0 +1,4 @@ +--- +title: 'Create Billing Portal Session' +openapi: '/api-reference/openapi/accounts.json POST /api/stripe/portal-sessions' +--- diff --git a/api-reference/subscriptions/portal-sessions-create.mdx b/api-reference/subscriptions/portal-sessions-create.mdx deleted file mode 100644 index 27b5958..0000000 --- a/api-reference/subscriptions/portal-sessions-create.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Create Billing Portal Session' -openapi: '/api-reference/openapi/accounts.json POST /api/subscriptions/portal-sessions' ---- diff --git a/api-reference/subscriptions/sessions-create.mdx b/api-reference/subscriptions/sessions-create.mdx deleted file mode 100644 index 2713979..0000000 --- a/api-reference/subscriptions/sessions-create.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Create Subscription Session' -openapi: '/api-reference/openapi/accounts.json POST /api/subscriptions/sessions' ---- diff --git a/docs.json b/docs.json index c503020..6e9955f 100644 --- a/docs.json +++ b/docs.json @@ -317,10 +317,10 @@ ] }, { - "group": "Subscriptions", + "group": "Stripe", "pages": [ - "api-reference/subscriptions/sessions-create", - "api-reference/subscriptions/portal-sessions-create" + "api-reference/stripe/checkout-sessions-create", + "api-reference/stripe/portal-sessions-create" ] }, {