docs(subscriptions): POST /api/subscriptions/card-on-file ($0 setup-mode session)

api-reference/openapi/accounts.json

@@ -790,6 +790,81 @@
         }
       }
     },
+    "/api/subscriptions/card-on-file": {
+      "post": {
+        "description": "Create a $0 card-on-file checkout session for the authenticated account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription, so an account that later runs out of credits can be auto-recharged instead of dead-ending. Returns a hosted checkout URL that the client should redirect to.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "description": "Card-on-file session parameters",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateCardOnFileSessionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Card-on-file session created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreateSubscriptionSessionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - missing or invalid parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionSessionErrorResponse"
+                },
+                "example": {
+                  "error": "successUrl must be a valid URL"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - invalid or missing authentication",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionSessionErrorResponse"
+                },
+                "example": {
+                  "error": "Exactly one of x-api-key or Authorization must be provided"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionSessionErrorResponse"
+                },
+                "example": {
+                  "error": "Internal server error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/accounts/{id}/subscription": {
       "get": {
         "description": "Retrieve the subscription for an account, directly or via an organization.",
@@ -4221,6 +4296,20 @@
           }
         }
       },
+      "CreateCardOnFileSessionRequest": {
+        "type": "object",
+        "required": [
+          "successUrl"
+        ],
+        "properties": {
+          "successUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "The URL Stripe redirects to after the card is saved.",
+            "example": "https://chat.recoupable.dev?card=saved"
+          }
+        }
+      },
       "CreateSubscriptionSessionResponse": {
         "type": "object",
         "required": [
@@ -4236,7 +4325,7 @@
           "url": {
             "type": "string",
             "format": "uri",
-            "description": "The hosted checkout URL. Redirect to this URL to complete the payment.",
+            "description": "The hosted checkout URL. Redirect to this URL to complete Checkout.",
             "example": "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0"
           }
         }

api-reference/subscriptions/card-on-file-create.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Create Card On File Session'
+openapi: '/api-reference/openapi/accounts.json POST /api/subscriptions/card-on-file'
+---

docs.json

@@ -334,6 +334,7 @@
             "group": "Billing",
             "pages": [
               "api-reference/subscriptions/sessions-create",
+              "api-reference/subscriptions/card-on-file-create",
               "api-reference/subscriptions/portal-create",
               "api-reference/accounts/subscription-get",
               "api-reference/credits/sessions-create",