From 6a3fae023fc59703b7867e20b30f261b0a85c481 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 21 Apr 2026 13:10:06 +0700 Subject: [PATCH 1/2] docs: add Stripe session status endpoint to OpenAPI specification 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. --- api-reference/openapi/accounts.json | 113 ++++++++++++++++++++++++ api-reference/stripe/session-status.mdx | 4 + docs.json | 6 ++ 3 files changed, 123 insertions(+) create mode 100644 api-reference/stripe/session-status.mdx diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json index 4ad84341..35f78e5e 100644 --- a/api-reference/openapi/accounts.json +++ b/api-reference/openapi/accounts.json @@ -415,6 +415,87 @@ } } }, + "/api/stripe/session/status": { + "get": { + "servers": [ + { + "url": "https://api.recoupable.com" + } + ], + "description": "Confirm that a Stripe checkout session has been processed and credits have been applied. Updates the session metadata with a `credit_updated` marker. Should be called once after a successful checkout redirect to trigger credit provisioning for the account.", + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "name": "sessionId", + "in": "query", + "description": "The Stripe checkout session ID to confirm (e.g. `cs_test_...`).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "accountId", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Session confirmed and credit metadata updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StripeSessionStatusResponse" + } + } + } + }, + "400": { + "description": "Bad request — missing `sessionId` or Stripe API error", + "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 +3015,38 @@ "example": "Verified" } } + }, + "StripeSessionStatusResponse": { + "type": "object", + "description": "The updated Stripe checkout session object. For the full list of available properties, see the [Stripe Checkout Session API documentation](https://docs.stripe.com/api/checkout/sessions/object).", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the Stripe checkout session.", + "example": "cs_test_a1b2c3d4e5f6g7h8i9j0" + }, + "status": { + "type": "string", + "enum": ["open", "complete", "expired"], + "description": "Current status of the checkout session.", + "example": "complete" + }, + "metadata": { + "type": "object", + "description": "Session metadata, including `credit_updated` once this endpoint has been called.", + "additionalProperties": { + "type": "string" + }, + "example": { + "accountId": "123e4567-e89b-12d3-a456-426614174000", + "credit_updated": "credit_updated" + } + } + } } } } diff --git a/api-reference/stripe/session-status.mdx b/api-reference/stripe/session-status.mdx new file mode 100644 index 00000000..1aad167d --- /dev/null +++ b/api-reference/stripe/session-status.mdx @@ -0,0 +1,4 @@ +--- +title: 'Confirm Stripe Session' +openapi: '/api-reference/openapi/accounts.json GET /api/stripe/session/status' +--- diff --git a/docs.json b/docs.json index 997442ca..3d5b8353 100644 --- a/docs.json +++ b/docs.json @@ -331,6 +331,12 @@ "api-reference/subscriptions/get" ] }, + { + "group": "Stripe", + "pages": [ + "api-reference/stripe/session-status" + ] + }, { "group": "Admins", "pages": [ From df477e50e26c8baa274794ffe1b635fde48eb7bf Mon Sep 17 00:00:00 2001 From: john Date: Tue, 21 Apr 2026 13:23:33 +0700 Subject: [PATCH 2/2] docs: update /api/stripe/session/status endpoint to use POST method Changed the HTTP method for the /api/stripe/session/status endpoint from GET to POST in the OpenAPI specification. Updated the request structure to include a request body for session confirmation parameters, defining the ConfirmStripeSessionRequest schema. Adjusted the corresponding MDX documentation to reflect this change. --- api-reference/openapi/accounts.json | 49 +++++++++++++++---------- api-reference/stripe/session-status.mdx | 2 +- 2 files changed, 30 insertions(+), 21 deletions(-) diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json index 35f78e5e..ffbe4a9b 100644 --- a/api-reference/openapi/accounts.json +++ b/api-reference/openapi/accounts.json @@ -416,7 +416,7 @@ } }, "/api/stripe/session/status": { - "get": { + "post": { "servers": [ { "url": "https://api.recoupable.com" @@ -431,27 +431,17 @@ "bearerAuth": [] } ], - "parameters": [ - { - "name": "sessionId", - "in": "query", - "description": "The Stripe checkout session ID to confirm (e.g. `cs_test_...`).", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "accountId", - "in": "query", - "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.", - "required": false, - "schema": { - "type": "string", - "format": "uuid" + "requestBody": { + "description": "Session confirmation parameters", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConfirmStripeSessionRequest" + } } } - ], + }, "responses": { "200": { "description": "Session confirmed and credit metadata updated successfully", @@ -3016,6 +3006,25 @@ } } }, + "ConfirmStripeSessionRequest": { + "type": "object", + "required": [ + "sessionId" + ], + "properties": { + "sessionId": { + "type": "string", + "description": "The Stripe checkout session ID to confirm (e.g. `cs_test_...`).", + "example": "cs_test_a1b2c3d4e5f6g7h8i9j0" + }, + "accountId": { + "type": "string", + "format": "uuid", + "description": "Used for authorization scoping when the API key has access to multiple accounts via organization membership. Must match the account already associated with the session via `metadata.accountId`. If not provided, the API key's own account is used.", + "example": "123e4567-e89b-12d3-a456-426614174000" + } + } + }, "StripeSessionStatusResponse": { "type": "object", "description": "The updated Stripe checkout session object. For the full list of available properties, see the [Stripe Checkout Session API documentation](https://docs.stripe.com/api/checkout/sessions/object).", diff --git a/api-reference/stripe/session-status.mdx b/api-reference/stripe/session-status.mdx index 1aad167d..922be985 100644 --- a/api-reference/stripe/session-status.mdx +++ b/api-reference/stripe/session-status.mdx @@ -1,4 +1,4 @@ --- title: 'Confirm Stripe Session' -openapi: '/api-reference/openapi/accounts.json GET /api/stripe/session/status' +openapi: '/api-reference/openapi/accounts.json POST /api/stripe/session/status' ---