@whooshbang/contracts 2.0.0-rc.6 → 2.0.0-rc.7

package/openapi/generated/whooshbang-v1.bundle.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.1",
   "info": {
     "title": "WhooshBang API",
-    "version": "2.0.0-rc.6",
+    "version": "2.0.0-rc.7",
     "description": "The V1 contract for human organization/project administration, project-scoped\nsubscription links, and asynchronous text messages. A Clerk session selects\none organization for administration. A project credential selects one organization,\nproject, and `test` or `live` environment for product operations; request\nbodies cannot override either authenticated scope.\n\nA person's OAuth grant selects one organization and carries scopes, but no\nproject. It names the project and environment it acts in through the URL\npath, on the environment-scoped form of each operation; the service checks\nthat path against the granting person's membership on every call. The flat\nforms remain credential-only and are unchanged.\n\nResource identifiers are opaque and are not authorization. Reads outside the\ncredential scope return the same `404` shape as absent resources. Provider\ncredentials, raw Telegram identity, and protected provider responses are\nnever part of this API.\n",
     "termsOfService": "https://flowxo.com/terms",
     "contact": {
@@ -159,93 +159,11 @@
         }
       }
     },
-    "/v1/billing/portal-sessions": {
-      "post": {
-        "operationId": "createBillingPortalSession",
-        "summary": "Open Stripe payment and subscription management",
-        "description": "Requires a current organization administrator and explicit billing write consent.\nUses only the organization's persisted Stripe customer or approved saved purchase.\nReturn destinations are server-owned. Opening the page does not itself charge a card.\n",
-        "tags": ["Organization"],
-        "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:write"],
-        "x-organization-membership": "required",
-        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
-        "responses": {
-          "201": {
-            "description": "Open Stripe payment and subscription management.",
-            "headers": {
-              "WhooshBang-Diagnostic-Id": {
-                "$ref": "#/components/headers/DiagnosticId"
-              }
-            },
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/BillingPortalSession"
-                }
-              }
-            }
-          },
-          "400": { "$ref": "#/components/responses/BadRequest" },
-          "401": { "$ref": "#/components/responses/Unauthorized" },
-          "403": { "$ref": "#/components/responses/Forbidden" },
-          "404": { "$ref": "#/components/responses/NotFound" },
-          "409": { "$ref": "#/components/responses/Conflict" },
-          "429": { "$ref": "#/components/responses/RateLimited" },
-          "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }
-        }
-      }
-    },
-    "/v1/billing/subscription-checkouts/{checkoutId}/resume": {
-      "post": {
-        "operationId": "resumeSubscriptionCheckout",
-        "summary": "Resume the saved subscription purchase",
-        "description": "Requires a current organization administrator and explicit billing write consent.\nUses only the organization's persisted Stripe customer or approved saved purchase.\nReturn destinations are server-owned. Opening the page does not itself charge a card.\n",
-        "tags": ["Organization"],
-        "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:write"],
-        "x-organization-membership": "required",
-        "parameters": [
-          {
-            "name": "checkoutId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "pattern": "^subscription_checkout_[a-f0-9]{32}$"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Resume the saved subscription purchase.",
-            "headers": {
-              "WhooshBang-Diagnostic-Id": {
-                "$ref": "#/components/headers/DiagnosticId"
-              }
-            },
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/SubscriptionCheckout"
-                }
-              }
-            }
-          },
-          "400": { "$ref": "#/components/responses/BadRequest" },
-          "401": { "$ref": "#/components/responses/Unauthorized" },
-          "403": { "$ref": "#/components/responses/Forbidden" },
-          "404": { "$ref": "#/components/responses/NotFound" },
-          "409": { "$ref": "#/components/responses/Conflict" },
-          "429": { "$ref": "#/components/responses/RateLimited" },
-          "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }
-        }
-      }
-    },
     "/v1/billing/auto-top-up": {
       "get": {
         "operationId": "getAutoTopUpSettings",
         "summary": "Read automatic top-up settings",
-        "description": "Requires an organization administrator and human billing consent. Automatic top-up is off by default.\nThe selected gross monthly cap counts pending and paid purchases initiated in each UTC calendar month.\nRefunds do not restore that cap. Disable stops future purchases; an authorized processing purchase may finish.\nThis saved card is separate from monthly subscription cards. Only verified Stripe payment authority funds credit.\n",
+        "description": "Requires an organization administrator and human billing consent. Automatic top-up is off by default.\nThe selected gross monthly cap counts pending and paid purchases initiated in each UTC calendar month.\nRefunds do not restore that cap. Disable stops future purchases; an authorized processing purchase may finish.\nPurchases use the organization's one default card. Only verified payments fund credit.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
         "x-required-scopes": ["billing:read"],
@@ -276,7 +194,7 @@
       "put": {
         "operationId": "updateAutoTopUpSettings",
         "summary": "Confirm automatic top-up settings",
-        "description": "Requires an organization administrator and human billing consent. Automatic top-up is off by default.\nThe selected gross monthly cap counts pending and paid purchases initiated in each UTC calendar month.\nRefunds do not restore that cap. Disable stops future purchases; an authorized processing purchase may finish.\nThis saved card is separate from monthly subscription cards. Only verified Stripe payment authority funds credit.\n",
+        "description": "Requires an organization administrator and human billing consent. Automatic top-up is off by default.\nThe selected gross monthly cap counts pending and paid purchases initiated in each UTC calendar month.\nRefunds do not restore that cap. Disable stops future purchases; an authorized processing purchase may finish.\nPurchases use the organization's one default card. Only verified payments fund credit.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
         "x-required-scopes": ["billing:write"],
@@ -315,19 +233,18 @@
         }
       }
     },
-    "/v1/billing/auto-top-up/setups": {
-      "post": {
-        "operationId": "createAutoTopUpSetup",
-        "summary": "Save a card for automatic top-up",
-        "description": "Requires an organization administrator and human billing consent. Automatic top-up is off by default.\nThe selected gross monthly cap counts pending and paid purchases initiated in each UTC calendar month.\nRefunds do not restore that cap. Disable stops future purchases; an authorized processing purchase may finish.\nThis saved card is separate from monthly subscription cards. Only verified Stripe payment authority funds credit.\n",
+    "/v1/billing/entitlements": {
+      "get": {
+        "operationId": "getBillingEntitlements",
+        "summary": "Read paid account entitlements",
+        "description": "Requires current organization membership. Financial purchases and preference writes require an administrator.\nPrices and paid entitlements come from server-approved offers and verified captured payments.\nAttribution expiry restores the platform mark while retaining sender identity, consent,\nunsubscribe and answer controls. payment_issue reports a recurring charge the card did not pay.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:write"],
+        "x-required-scopes": ["billing:read"],
         "x-organization-membership": "required",
-        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
         "responses": {
-          "201": {
-            "description": "Save a card for automatic top-up.",
+          "200": {
+            "description": "Read paid account entitlements.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -335,7 +252,7 @@
             },
             "content": {
               "application/json": {
-                "schema": { "$ref": "#/components/schemas/AutoTopUpSetup" }
+                "schema": { "$ref": "#/components/schemas/BillingEntitlements" }
               }
             }
           },
@@ -349,29 +266,27 @@
         }
       }
     },
-    "/v1/billing/auto-top-up/setups/{setupId}/reconcile": {
+    "/v1/billing/subscription-changes": {
       "post": {
-        "operationId": "reconcileAutoTopUpSetup",
-        "summary": "Refresh an owned automatic top-up card setup",
-        "description": "Requires an organization administrator and human billing consent. Automatic top-up is off by default.\nThe selected gross monthly cap counts pending and paid purchases initiated in each UTC calendar month.\nRefunds do not restore that cap. Disable stops future purchases; an authorized processing purchase may finish.\nThis saved card is separate from monthly subscription cards. Only verified Stripe payment authority funds credit.\n",
+        "operationId": "createSubscriptionChange",
+        "summary": "Quote an approved recurring change",
+        "description": "Requires an administrator in the current organization. A quote does not charge. Without a current plan or add-on the change starts one. Confirmation matches the saved exact cash amount and charges the default card. Uncertain outcomes recover the same owned change.",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
         "x-required-scopes": ["billing:write"],
         "x-organization-membership": "required",
-        "parameters": [
-          {
-            "name": "setupId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "pattern": "^auto_top_up_setup_[a-f0-9]{32}$"
+        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/SubscriptionSelection" }
             }
           }
-        ],
+        },
         "responses": {
-          "200": {
-            "description": "Refresh an owned automatic top-up card setup.",
+          "201": {
+            "description": "Quote an approved recurring change.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -379,9 +294,7 @@
             },
             "content": {
               "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ReconcileAutoTopUpSetupResult"
-                }
+                "schema": { "$ref": "#/components/schemas/SubscriptionChange" }
               }
             }
           },
@@ -395,62 +308,29 @@
         }
       }
     },
-    "/v1/billing/auto-top-up/setups/{setupId}/resume": {
-      "post": {
-        "operationId": "resumeAutoTopUpSetup",
-        "summary": "Resume an owned automatic top-up card setup",
-        "description": "Requires an organization administrator and human billing consent. Automatic top-up is off by default.\nThe selected gross monthly cap counts pending and paid purchases initiated in each UTC calendar month.\nRefunds do not restore that cap. Disable stops future purchases; an authorized processing purchase may finish.\nThis saved card is separate from monthly subscription cards. Only verified Stripe payment authority funds credit.\n",
+    "/v1/billing/subscription-changes/{changeId}": {
+      "get": {
+        "operationId": "getSubscriptionChange",
+        "summary": "Recover an owned recurring change",
+        "description": "Requires an administrator in the current organization. A quote does not charge. Without a current plan or add-on the change starts one. Confirmation matches the saved exact cash amount and charges the default card. Uncertain outcomes recover the same owned change.",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:write"],
+        "x-required-scopes": ["billing:read"],
         "x-organization-membership": "required",
         "parameters": [
           {
-            "name": "setupId",
+            "name": "changeId",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string",
-              "pattern": "^auto_top_up_setup_[a-f0-9]{32}$"
+              "pattern": "^subscription_change_[a-f0-9]{32}$"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Resume an owned automatic top-up card setup.",
-            "headers": {
-              "WhooshBang-Diagnostic-Id": {
-                "$ref": "#/components/headers/DiagnosticId"
-              }
-            },
-            "content": {
-              "application/json": {
-                "schema": { "$ref": "#/components/schemas/AutoTopUpSetup" }
-              }
-            }
-          },
-          "400": { "$ref": "#/components/responses/BadRequest" },
-          "401": { "$ref": "#/components/responses/Unauthorized" },
-          "403": { "$ref": "#/components/responses/Forbidden" },
-          "404": { "$ref": "#/components/responses/NotFound" },
-          "409": { "$ref": "#/components/responses/Conflict" },
-          "429": { "$ref": "#/components/responses/RateLimited" },
-          "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }
-        }
-      }
-    },
-    "/v1/billing/entitlements": {
-      "get": {
-        "operationId": "getBillingEntitlements",
-        "summary": "Read paid account entitlements",
-        "description": "Requires current organization membership. Financial purchases and preference writes require an administrator.\nPrices and paid entitlements come from server-approved offers and verified captured Stripe payments.\nSubscription Checkout does not itself grant paid access. Attribution expiry restores the platform mark\nwhile retaining sender identity, consent, unsubscribe and answer controls.\n",
-        "tags": ["Organization"],
-        "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:read"],
-        "x-organization-membership": "required",
-        "responses": {
-          "200": {
-            "description": "Read paid account entitlements.",
+            "description": "Recover an owned recurring change.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -458,7 +338,7 @@
             },
             "content": {
               "application/json": {
-                "schema": { "$ref": "#/components/schemas/BillingEntitlements" }
+                "schema": { "$ref": "#/components/schemas/SubscriptionChange" }
               }
             }
           },
@@ -472,29 +352,39 @@
         }
       }
     },
-    "/v1/billing/subscription-changes": {
+    "/v1/billing/subscription-changes/{changeId}/confirm": {
       "post": {
-        "operationId": "createSubscriptionChange",
-        "summary": "Quote an approved recurring change",
-        "description": "Requires an administrator in the current organization. A quote does not charge. Confirmation matches the saved exact cash amount. Uncertain outcomes recover the same owned change.",
+        "operationId": "confirmSubscriptionChange",
+        "summary": "Confirm the quoted card charge or scheduled reduction",
+        "description": "Requires an administrator in the current organization. A quote does not charge. Without a current plan or add-on the change starts one. Confirmation matches the saved exact cash amount and charges the default card. Uncertain outcomes recover the same owned change.",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
         "x-required-scopes": ["billing:write"],
         "x-organization-membership": "required",
-        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+        "parameters": [
+          {
+            "name": "changeId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "pattern": "^subscription_change_[a-f0-9]{32}$"
+            }
+          }
+        ],
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateSubscriptionCheckoutRequest"
+                "$ref": "#/components/schemas/ConfirmSubscriptionChangeRequest"
               }
             }
           }
         },
         "responses": {
-          "201": {
-            "description": "Quote an approved recurring change.",
+          "200": {
+            "description": "Confirm the quoted card charge or scheduled reduction.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -516,14 +406,14 @@
         }
       }
     },
-    "/v1/billing/subscription-changes/{changeId}": {
-      "get": {
-        "operationId": "getSubscriptionChange",
-        "summary": "Recover an owned recurring change",
-        "description": "Requires an administrator in the current organization. A quote does not charge. Confirmation matches the saved exact cash amount. Uncertain outcomes recover the same owned change.",
+    "/v1/billing/subscription-changes/{changeId}/cancel": {
+      "post": {
+        "operationId": "cancelSubscriptionChange",
+        "summary": "Discard a quote or undo a scheduled change",
+        "description": "Requires an administrator in the current organization. Discards a reserved quote before anything is charged, or undoes a change scheduled for the end of the paid month before it takes effect; the plan and add-ons then stay exactly as they are. A change already being charged cannot be discarded. Repeating the request reports the same expired change.",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:read"],
+        "x-required-scopes": ["billing:write"],
         "x-organization-membership": "required",
         "parameters": [
           {
@@ -538,7 +428,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Recover an owned recurring change.",
+            "description": "The discarded quote or undone scheduled change, now expired.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -560,39 +450,26 @@
         }
       }
     },
-    "/v1/billing/subscription-changes/{changeId}/confirm": {
-      "post": {
-        "operationId": "confirmSubscriptionChange",
-        "summary": "Confirm the quoted card charge or scheduled reduction",
-        "description": "Requires an administrator in the current organization. A quote does not charge. Confirmation matches the saved exact cash amount. Uncertain outcomes recover the same owned change.",
+    "/v1/projects/{projectId}/attribution": {
+      "get": {
+        "operationId": "getProjectAttribution",
+        "summary": "Read project attribution preference and entitlement",
+        "description": "Requires current organization membership. Financial purchases and preference writes require an administrator.\nPrices and paid entitlements come from server-approved offers and verified captured payments.\nAttribution expiry restores the platform mark while retaining sender identity, consent,\nunsubscribe and answer controls. payment_issue reports a recurring charge the card did not pay.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:write"],
+        "x-required-scopes": ["projects:read"],
         "x-organization-membership": "required",
         "parameters": [
           {
-            "name": "changeId",
+            "name": "projectId",
             "in": "path",
             "required": true,
-            "schema": {
-              "type": "string",
-              "pattern": "^subscription_change_[a-f0-9]{32}$"
-            }
+            "schema": { "type": "string" }
           }
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/ConfirmSubscriptionChangeRequest"
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
-            "description": "Confirm the quoted card charge or scheduled reduction.",
+            "description": "Read project attribution preference and entitlement.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -600,7 +477,7 @@
             },
             "content": {
               "application/json": {
-                "schema": { "$ref": "#/components/schemas/SubscriptionChange" }
+                "schema": { "$ref": "#/components/schemas/ProjectAttribution" }
               }
             }
           },
@@ -612,31 +489,36 @@
           "429": { "$ref": "#/components/responses/RateLimited" },
           "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }
         }
-      }
-    },
-    "/v1/billing/subscription-changes/{changeId}/cancel": {
-      "post": {
-        "operationId": "cancelSubscriptionChange",
-        "summary": "Discard an undispatched recurring quote",
-        "description": "Requires an administrator in the current organization. A quote does not charge. Confirmation matches the saved exact cash amount. Uncertain outcomes recover the same owned change.",
+      },
+      "put": {
+        "operationId": "updateProjectAttribution",
+        "summary": "Update project attribution preference",
+        "description": "Requires current organization membership. Financial purchases and preference writes require an administrator.\nPrices and paid entitlements come from server-approved offers and verified captured payments.\nAttribution expiry restores the platform mark while retaining sender identity, consent,\nunsubscribe and answer controls. payment_issue reports a recurring charge the card did not pay.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:write"],
+        "x-required-scopes": ["projects:write"],
         "x-organization-membership": "required",
         "parameters": [
           {
-            "name": "changeId",
+            "name": "projectId",
             "in": "path",
             "required": true,
-            "schema": {
-              "type": "string",
-              "pattern": "^subscription_change_[a-f0-9]{32}$"
-            }
+            "schema": { "type": "string" }
           }
         ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateProjectAttributionRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
-            "description": "Discard an undispatched recurring quote.",
+            "description": "Update project attribution preference.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -644,7 +526,7 @@
             },
             "content": {
               "application/json": {
-                "schema": { "$ref": "#/components/schemas/SubscriptionChange" }
+                "schema": { "$ref": "#/components/schemas/ProjectAttribution" }
               }
             }
           },
@@ -658,29 +540,19 @@
         }
       }
     },
-    "/v1/billing/subscription-checkouts": {
+    "/v1/billing/card-setups": {
       "post": {
-        "operationId": "createSubscriptionCheckout",
-        "summary": "Start an approved monthly subscription",
-        "description": "Requires current organization membership. Financial purchases and preference writes require an administrator.\nPrices and paid entitlements come from server-approved offers and verified captured Stripe payments.\nSubscription Checkout does not itself grant paid access. Attribution expiry restores the platform mark\nwhile retaining sender identity, consent, unsubscribe and answer controls.\n",
+        "operationId": "createCardSetup",
+        "summary": "Open a card form session",
+        "description": "Requires a current organization administrator. A person enters the card in the\nembeddable payment form; card numbers never pass through WhooshBang. A complete\nsetup makes the card the organization's one default card for credit, automatic\ntop-up, plans and add-ons. Opening a setup does not charge anything.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
         "x-required-scopes": ["billing:write"],
         "x-organization-membership": "required",
         "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/CreateSubscriptionCheckoutRequest"
-              }
-            }
-          }
-        },
         "responses": {
           "201": {
-            "description": "Start an approved monthly subscription.",
+            "description": "Open a card form session.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -688,9 +560,7 @@
             },
             "content": {
               "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/SubscriptionCheckout"
-                }
+                "schema": { "$ref": "#/components/schemas/CardSetup" }
               }
             }
           },
@@ -704,29 +574,29 @@
         }
       }
     },
-    "/v1/billing/subscription-checkouts/{checkoutId}/reconcile": {
+    "/v1/billing/card-setups/{setupId}/reconcile": {
       "post": {
-        "operationId": "reconcileSubscriptionCheckout",
-        "summary": "Refresh an owned subscription purchase",
-        "description": "Requires current organization membership. Financial purchases and preference writes require an administrator.\nPrices and paid entitlements come from server-approved offers and verified captured Stripe payments.\nSubscription Checkout does not itself grant paid access. Attribution expiry restores the platform mark\nwhile retaining sender identity, consent, unsubscribe and answer controls.\n",
+        "operationId": "reconcileCardSetup",
+        "summary": "Save a confirmed card as the default",
+        "description": "Requires a current organization administrator. A person enters the card in the\nembeddable payment form; card numbers never pass through WhooshBang. A complete\nsetup makes the card the organization's one default card for credit, automatic\ntop-up, plans and add-ons. Opening a setup does not charge anything.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
         "x-required-scopes": ["billing:write"],
         "x-organization-membership": "required",
         "parameters": [
           {
-            "name": "checkoutId",
+            "name": "setupId",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string",
-              "pattern": "^subscription_checkout_[a-f0-9]{32}$"
+              "pattern": "^card_setup_[a-f0-9]{32}$"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Refresh an owned subscription purchase.",
+            "description": "Save a confirmed card as the default.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -734,9 +604,7 @@
             },
             "content": {
               "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ReconcileSubscriptionCheckoutResult"
-                }
+                "schema": { "$ref": "#/components/schemas/CardSetup" }
               }
             }
           },
@@ -750,26 +618,29 @@
         }
       }
     },
-    "/v1/projects/{projectId}/attribution": {
-      "get": {
-        "operationId": "getProjectAttribution",
-        "summary": "Read project attribution preference and entitlement",
-        "description": "Requires current organization membership. Financial purchases and preference writes require an administrator.\nPrices and paid entitlements come from server-approved offers and verified captured Stripe payments.\nSubscription Checkout does not itself grant paid access. Attribution expiry restores the platform mark\nwhile retaining sender identity, consent, unsubscribe and answer controls.\n",
+    "/v1/billing/credit-purchases": {
+      "post": {
+        "operationId": "createCreditPurchase",
+        "summary": "Buy a credit pack with the default card",
+        "description": "Requires a current organization administrator. Charges the default card for one\ncredit pack; the pack amount is the explicit approval. Without a default card the\nrequest is refused with billing_card_required. Retrying with the same\nIdempotency-Key returns the same purchase and never charges twice. Credit is\ngranted only after the payment is verified.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["projects:read"],
+        "x-required-scopes": ["billing:write"],
         "x-organization-membership": "required",
-        "parameters": [
-          {
-            "name": "projectId",
-            "in": "path",
-            "required": true,
-            "schema": { "type": "string" }
+        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateCreditPurchaseRequest"
+              }
+            }
           }
-        ],
+        },
         "responses": {
-          "200": {
-            "description": "Read project attribution preference and entitlement.",
+          "201": {
+            "description": "Buy a credit pack with the default card.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -777,7 +648,7 @@
             },
             "content": {
               "application/json": {
-                "schema": { "$ref": "#/components/schemas/ProjectAttribution" }
+                "schema": { "$ref": "#/components/schemas/CreditPurchase" }
               }
             }
           },
@@ -789,36 +660,31 @@
           "429": { "$ref": "#/components/responses/RateLimited" },
           "502": { "$ref": "#/components/responses/ProviderOutcomeUnknown" }
         }
-      },
-      "put": {
-        "operationId": "updateProjectAttribution",
-        "summary": "Update project attribution preference",
-        "description": "Requires current organization membership. Financial purchases and preference writes require an administrator.\nPrices and paid entitlements come from server-approved offers and verified captured Stripe payments.\nSubscription Checkout does not itself grant paid access. Attribution expiry restores the platform mark\nwhile retaining sender identity, consent, unsubscribe and answer controls.\n",
+      }
+    },
+    "/v1/billing/credit-purchases/{purchaseId}/reconcile": {
+      "post": {
+        "operationId": "reconcileCreditPurchase",
+        "summary": "Refresh a credit purchase",
+        "description": "Requires a current organization administrator. Charges the default card for one\ncredit pack; the pack amount is the explicit approval. Without a default card the\nrequest is refused with billing_card_required. Retrying with the same\nIdempotency-Key returns the same purchase and never charges twice. Credit is\ngranted only after the payment is verified.\nReconcile after the customer confirms the charge in the payment form.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["projects:write"],
+        "x-required-scopes": ["billing:write"],
         "x-organization-membership": "required",
         "parameters": [
           {
-            "name": "projectId",
+            "name": "purchaseId",
             "in": "path",
             "required": true,
-            "schema": { "type": "string" }
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/UpdateProjectAttributionRequest"
-              }
+            "schema": {
+              "type": "string",
+              "pattern": "^credit_purchase_[a-f0-9]{32}$"
             }
           }
-        },
+        ],
         "responses": {
           "200": {
-            "description": "Update project attribution preference.",
+            "description": "Refresh a credit purchase.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -826,7 +692,7 @@
             },
             "content": {
               "application/json": {
-                "schema": { "$ref": "#/components/schemas/ProjectAttribution" }
+                "schema": { "$ref": "#/components/schemas/CreditPurchase" }
               }
             }
           },
@@ -840,18 +706,23 @@
         }
       }
     },
-    "/v1/billing": {
+    "/v1/billing/invoices": {
       "get": {
-        "operationId": "getBillingAccount",
-        "summary": "Read account delivery credit",
-        "description": "Requires a current organization administrator. Bundle bonus funds core sends only.\nShared email uses purchased or starter credit at $1 per 1,000.\nCheckout returns a hosted Stripe URL and does not charge the card itself.\nVerified current Stripe payment authority is required before credit is granted.\n",
+        "operationId": "listBillingInvoices",
+        "summary": "List invoices and receipts",
+        "description": "Requires a current organization administrator. Returns the most recent\ncredit purchases, automatic top-ups, recurring invoices and the welcome credit,\nnewest first, each with its downloadable invoice or receipt where one exists.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
         "x-required-scopes": ["billing:read"],
         "x-organization-membership": "required",
+        "parameters": [
+          { "$ref": "#/components/parameters/ListAfterCursor" },
+          { "$ref": "#/components/parameters/ListPageLimit" },
+          { "$ref": "#/components/parameters/PageNumber" }
+        ],
         "responses": {
           "200": {
-            "description": "Read account delivery credit.",
+            "description": "List invoices and receipts.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -859,7 +730,9 @@
             },
             "content": {
               "application/json": {
-                "schema": { "$ref": "#/components/schemas/BillingAccount" }
+                "schema": {
+                  "$ref": "#/components/schemas/BillingInvoiceCollection"
+                }
               }
             }
           },
@@ -873,29 +746,28 @@
         }
       }
     },
-    "/v1/billing/wallet-checkouts": {
-      "post": {
-        "operationId": "createWalletCheckout",
-        "summary": "Start a prepaid wallet purchase",
-        "description": "Requires a current organization administrator. Bundle bonus funds core sends only.\nShared email uses purchased or starter credit at $1 per 1,000.\nCheckout returns a hosted Stripe URL and does not charge the card itself.\nVerified current Stripe payment authority is required before credit is granted.\n",
+    "/v1/billing/receipt-email": {
+      "put": {
+        "operationId": "updateBillingReceiptEmail",
+        "summary": "Choose where receipts are emailed",
+        "description": "Requires a current organization administrator. Receipts and invoices for\nevery charge go to this address. Null stops them.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
         "x-required-scopes": ["billing:write"],
         "x-organization-membership": "required",
-        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateWalletCheckoutRequest"
+                "$ref": "#/components/schemas/UpdateBillingReceiptEmailRequest"
               }
             }
           }
         },
         "responses": {
-          "201": {
-            "description": "Start a prepaid wallet purchase.",
+          "200": {
+            "description": "Choose where receipts are emailed.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -903,7 +775,7 @@
             },
             "content": {
               "application/json": {
-                "schema": { "$ref": "#/components/schemas/WalletCheckout" }
+                "schema": { "$ref": "#/components/schemas/BillingAccount" }
               }
             }
           },
@@ -917,26 +789,18 @@
         }
       }
     },
-    "/v1/billing/wallet-checkouts/{checkoutId}/reconcile": {
-      "post": {
-        "operationId": "reconcileWalletCheckout",
-        "summary": "Refresh an owned prepaid purchase",
-        "description": "Requires a current organization administrator. Bundle bonus funds core sends only.\nShared email uses purchased or starter credit at $1 per 1,000.\nCheckout returns a hosted Stripe URL and does not charge the card itself.\nVerified current Stripe payment authority is required before credit is granted.\n",
+    "/v1/billing": {
+      "get": {
+        "operationId": "getBillingAccount",
+        "summary": "Read account delivery credit",
+        "description": "Requires a current organization administrator. Bundle bonus funds core sends only.\nShared email uses purchased or starter credit at $1 per 1,000.\nCredit is granted only after a verified payment. card is the one default card;\nreceipt_email is where receipts go.\n",
         "tags": ["Organization"],
         "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
-        "x-required-scopes": ["billing:write"],
+        "x-required-scopes": ["billing:read"],
         "x-organization-membership": "required",
-        "parameters": [
-          {
-            "name": "checkoutId",
-            "in": "path",
-            "required": true,
-            "schema": { "type": "string", "pattern": "^checkout_[a-f0-9]{32}$" }
-          }
-        ],
         "responses": {
           "200": {
-            "description": "Refresh an owned prepaid purchase.",
+            "description": "Read account delivery credit.",
             "headers": {
               "WhooshBang-Diagnostic-Id": {
                 "$ref": "#/components/headers/DiagnosticId"
@@ -944,9 +808,7 @@
             },
             "content": {
               "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ReconcileWalletCheckoutResult"
-                }
+                "schema": { "$ref": "#/components/schemas/BillingAccount" }
               }
             }
           },
@@ -12169,14 +12031,6 @@
         "additionalProperties": false,
         "description": "Replace the requested active project selection with owned, active projects within current paid capacity. An empty selection releases all slots."
       },
-      "BillingPortalSession": {
-        "type": "object",
-        "required": ["portal_url"],
-        "properties": {
-          "portal_url": { "type": "string", "format": "uri", "maxLength": 4096 }
-        },
-        "additionalProperties": false
-      },
       "BillingEntitlements": {
         "type": "object",
         "required": [
@@ -12188,11 +12042,10 @@
           "live_notifications_remaining",
           "shared_emails_remaining",
           "allowance_period_end",
-          "recurring_checkout_available",
           "offers",
-          "pending_subscription_checkout_id",
-          "subscription_management_available",
-          "has_subscription"
+          "has_subscription",
+          "recurring_available",
+          "payment_issue"
         ],
         "properties": {
           "content_retention_days": {
@@ -12229,7 +12082,10 @@
               { "type": "null" }
             ]
           },
-          "recurring_checkout_available": { "type": "boolean" },
+          "recurring_available": {
+            "type": "boolean",
+            "description": "Whether plans and add-ons can be bought now. False when the deployment has no recurring catalog or cannot take payments."
+          },
           "offers": {
             "type": "array",
             "items": {
@@ -12272,46 +12128,58 @@
               "additionalProperties": false
             }
           },
-          "pending_subscription_checkout_id": {
-            "type": ["string", "null"],
-            "pattern": "^subscription_checkout_[a-f0-9]{32}$",
-            "minLength": 54,
-            "maxLength": 54
-          },
-          "subscription_management_available": { "type": "boolean" },
           "has_subscription": { "type": "boolean" },
           "pending_subscription_change_id": {
             "type": ["string", "null"],
             "pattern": "^subscription_change_[a-f0-9]{32}$",
             "minLength": 52,
             "maxLength": 52
+          },
+          "payment_issue": {
+            "anyOf": [
+              { "type": "null" },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["amount_usd", "next_attempt_at"],
+                "properties": {
+                  "amount_usd": {
+                    "type": "string",
+                    "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                    "maxLength": 40
+                  },
+                  "next_attempt_at": {
+                    "anyOf": [
+                      { "type": "string", "format": "date-time" },
+                      { "type": "null" }
+                    ]
+                  }
+                }
+              }
+            ],
+            "description": "A recurring charge the default card did not pay. Paid access continues until the paid boundary; another attempt follows at next_attempt_at, or none when null. Update the card to settle it."
           }
         },
         "additionalProperties": false
       },
-      "CreateSubscriptionCheckoutRequest": {
+      "SubscriptionSelection": {
         "type": "object",
         "required": ["plan", "hide_attribution", "additional_projects"],
         "properties": {
           "plan": { "type": "string", "enum": ["payg", "team", "agency"] },
-          "hide_attribution": { "type": "boolean" },
+          "hide_attribution": {
+            "type": "boolean",
+            "description": "Remove WhooshBang branding from recipient emails, messages and subscription pages."
+          },
           "additional_projects": {
             "type": "integer",
             "minimum": 0,
-            "maximum": 10000
+            "maximum": 10000,
+            "description": "Extra projects beyond the plan's included projects, each billed monthly."
           }
         },
         "additionalProperties": false,
-        "description": "Account subscription selection for initial Checkout or a quoted change. Additional project quantities have a technical Checkout bound. The server selects approved prices and allowances. Attribution is included on Team and Agency; PAYG may purchase the account-wide add-on.",
-        "anyOf": [
-          { "properties": { "plan": { "enum": ["team", "agency"] } } },
-          { "properties": { "hide_attribution": { "const": true } } },
-          {
-            "properties": {
-              "additional_projects": { "minimum": 1, "type": "integer" }
-            }
-          }
-        ]
+        "description": "An account's recurring selection: a plan, branding removal and extra projects. The server selects approved prices and allowances. Branding removal is included on Team and Agency; Pay as you go may add it. Choosing Pay as you go with nothing else ends every recurring charge at the paid boundary."
       },
       "SubscriptionChange": {
         "type": "object",
@@ -12325,7 +12193,9 @@
           "unused_time_credit_usd",
           "effective_at",
           "expires_at",
-          "payment_url"
+          "client_secret",
+          "failure",
+          "publishable_key"
         ],
         "properties": {
           "id": {
@@ -12334,7 +12204,10 @@
             "minLength": 52,
             "maxLength": 52
           },
-          "kind": { "type": "string", "enum": ["upgrade", "boundary"] },
+          "kind": {
+            "type": "string",
+            "enum": ["start", "upgrade", "boundary"]
+          },
           "status": {
             "type": "string",
             "enum": [
@@ -12346,9 +12219,7 @@
               "expired"
             ]
           },
-          "selection": {
-            "$ref": "#/components/schemas/CreateSubscriptionCheckoutRequest"
-          },
+          "selection": { "$ref": "#/components/schemas/SubscriptionSelection" },
           "monthly_price_usd": {
             "type": "string",
             "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
@@ -12381,61 +12252,47 @@
             ]
           },
           "expires_at": { "type": "string", "format": "date-time" },
-          "payment_url": {
+          "client_secret": {
             "anyOf": [
-              { "type": "string", "format": "uri", "maxLength": 4096 },
+              { "type": "string", "minLength": 1, "maxLength": 512 },
               { "type": "null" }
-            ]
-          }
-        },
-        "additionalProperties": false,
-        "description": "An owned immutable recurring selection. A reserved quote has not charged a card. Confirm its exact immediate cash charge; paid upgrades reset the cycle and carry unused paid time, while reductions start at the existing paid boundary. Processing or pending outcomes must be recovered without starting another change."
-      },
-      "ConfirmSubscriptionChangeRequest": {
-        "type": "object",
-        "required": ["approved_charge_now_usd"],
-        "properties": {
-          "approved_charge_now_usd": {
-            "type": "string",
-            "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
-            "maxLength": 40,
-            "description": "The exact charge_now_usd from the saved quote; cents only, for explicit card-charge approval."
-          }
-        },
-        "additionalProperties": false
-      },
-      "SubscriptionCheckout": {
-        "type": "object",
-        "required": ["id", "status", "checkout_url"],
-        "properties": {
-          "id": {
-            "type": "string",
-            "pattern": "^subscription_checkout_[a-f0-9]{32}$",
-            "minLength": 54,
-            "maxLength": 54
+            ],
+            "description": "Present only while the card issuer asks the customer to confirm this charge in the payment form."
           },
-          "status": {
-            "type": "string",
-            "enum": ["open", "complete", "expired"]
+          "publishable_key": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^pk_(test|live)_[A-Za-z0-9]{1,250}$"
+              },
+              { "type": "null" }
+            ],
+            "description": "The public key the payment form uses with client_secret. Present only with client_secret."
           },
-          "checkout_url": {
+          "failure": {
             "anyOf": [
-              { "type": "string", "format": "uri", "maxLength": 4096 },
+              {
+                "type": "string",
+                "enum": ["card_declined", "authentication_failed"]
+              },
               { "type": "null" }
-            ]
+            ],
+            "description": "Why the last charge attempt failed. Update the card, then confirm again."
           }
         },
-        "additionalProperties": false
+        "additionalProperties": false,
+        "description": "An owned recurring selection. A reserved quote has not charged anything. start buys the first plan or add-on; upgrade charges now, resets the cycle and credits unused paid time; boundary reductions start at the existing paid boundary. Confirm the exact immediate charge; the default card pays it. Processing or pending changes are recovered, never repeated."
       },
-      "ReconcileSubscriptionCheckoutResult": {
+      "ConfirmSubscriptionChangeRequest": {
         "type": "object",
-        "required": ["outcome", "entitlements"],
+        "required": ["approved_charge_now_usd"],
         "properties": {
-          "outcome": {
+          "approved_charge_now_usd": {
             "type": "string",
-            "enum": ["applied", "unpaid", "ignored"]
-          },
-          "entitlements": { "$ref": "#/components/schemas/BillingEntitlements" }
+            "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+            "maxLength": 40,
+            "description": "The exact charge_now_usd from the saved quote; cents only, for explicit card-charge approval."
+          }
         },
         "additionalProperties": false
       },
@@ -12498,8 +12355,8 @@
           "available",
           "monthly_reserved_cents",
           "state",
-          "saved_card",
-          "pending_setup_id"
+          "card",
+          "last_purchase"
         ],
         "properties": {
           "enabled": { "type": "boolean" },
@@ -12534,61 +12391,46 @@
               "monthly_cap_reached"
             ]
           },
-          "saved_card": {
+          "card": {
+            "anyOf": [
+              { "type": "null" },
+              { "$ref": "#/components/schemas/BillingCard" }
+            ]
+          },
+          "last_purchase": {
             "anyOf": [
               { "type": "null" },
               {
                 "type": "object",
                 "additionalProperties": false,
-                "required": ["brand", "last_four"],
+                "required": [
+                  "id",
+                  "purchase_cents",
+                  "credit_usd",
+                  "completed_at"
+                ],
                 "properties": {
-                  "brand": {
+                  "id": {
                     "type": "string",
-                    "minLength": 1,
-                    "maxLength": 32
+                    "pattern": "^auto_top_up_[a-f0-9]{32}$"
+                  },
+                  "purchase_cents": {
+                    "type": "integer",
+                    "enum": [500, 1000, 2500, 5000, 10000]
+                  },
+                  "credit_usd": {
+                    "type": "string",
+                    "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                    "maxLength": 40
                   },
-                  "last_four": { "type": "string", "pattern": "^[0-9]{4}$" }
+                  "completed_at": { "type": "string", "format": "date-time" }
                 }
               }
-            ]
-          },
-          "pending_setup_id": {
-            "type": ["string", "null"],
-            "pattern": "^auto_top_up_setup_[a-f0-9]{32}$"
-          }
-        }
-      },
-      "AutoTopUpSetup": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["id", "status", "checkout_url"],
-        "properties": {
-          "id": {
-            "type": "string",
-            "pattern": "^auto_top_up_setup_[a-f0-9]{32}$"
-          },
-          "status": {
-            "type": "string",
-            "enum": ["open", "complete", "expired"]
-          },
-          "checkout_url": {
-            "type": ["string", "null"],
-            "format": "uri",
-            "maxLength": 4096
+            ],
+            "description": "The most recent paid automatic purchase, if any."
           }
-        }
-      },
-      "ReconcileAutoTopUpSetupResult": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["outcome", "settings"],
-        "properties": {
-          "outcome": {
-            "type": "string",
-            "enum": ["applied", "unpaid", "ignored"]
-          },
-          "settings": { "$ref": "#/components/schemas/AutoTopUpSettings" }
-        }
+        },
+        "description": "Automatic top-up is off by default. When on, the default card buys the selected pack whenever credit falls below the trigger. The monthly cap counts pending and paid purchases started in each UTC calendar month; refunds do not restore it. Turning it off stops future purchases; one already processing may finish. needs_card means there is no default card yet."
       },
       "BillingAccount": {
         "type": "object",
@@ -12602,8 +12444,10 @@
           "available_email_credit_usd",
           "core_price_per_1000_usd",
           "shared_email_price_per_1000_usd",
-          "checkout_available",
-          "packs"
+          "purchases_available",
+          "packs",
+          "card",
+          "receipt_email"
         ],
         "properties": {
           "currency": { "const": "USD" },
@@ -12634,7 +12478,10 @@
           },
           "core_price_per_1000_usd": { "const": "3.000000" },
           "shared_email_price_per_1000_usd": { "const": "1.000000" },
-          "checkout_available": { "type": "boolean" },
+          "purchases_available": {
+            "type": "boolean",
+            "description": "Whether this deployment can take card payments now. When false, credit, plans and add-ons cannot be bought."
+          },
           "packs": {
             "type": "array",
             "items": {
@@ -12653,11 +12500,76 @@
                 }
               }
             }
+          },
+          "card": {
+            "anyOf": [
+              { "type": "null" },
+              { "$ref": "#/components/schemas/BillingCard" }
+            ]
+          },
+          "receipt_email": {
+            "anyOf": [
+              { "type": "null" },
+              { "$ref": "#/components/schemas/EmailAddress" }
+            ],
+            "description": "Where receipts and invoices are emailed. Null sends none."
+          }
+        },
+        "description": "Shared account message credit. Bonus funds core sends only; shared email draws purchased or starter credit. Amounts are exact USD decimal strings. Negative purchased or bonus balances retain refund debt and are not spendable."
+      },
+      "BillingCard": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["brand", "last_four", "exp_month", "exp_year"],
+        "properties": {
+          "brand": { "type": "string", "minLength": 1, "maxLength": 32 },
+          "last_four": { "type": "string", "pattern": "^[0-9]{4}$" },
+          "exp_month": { "type": "integer", "minimum": 1, "maximum": 12 },
+          "exp_year": { "type": "integer", "minimum": 2000, "maximum": 9999 }
+        },
+        "description": "The organization's one default card. It pays for credit, automatic top-up, plans and add-ons. Only the brand, last four digits and expiry are ever returned."
+      },
+      "CardSetup": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "status",
+          "client_secret",
+          "publishable_key",
+          "card"
+        ],
+        "properties": {
+          "id": { "type": "string", "pattern": "^card_setup_[a-f0-9]{32}$" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "complete", "expired"]
+          },
+          "client_secret": {
+            "anyOf": [
+              { "type": "string", "minLength": 1, "maxLength": 512 },
+              { "type": "null" }
+            ]
+          },
+          "publishable_key": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^pk_(test|live)_[A-Za-z0-9]{1,250}$"
+              },
+              { "type": "null" }
+            ]
+          },
+          "card": {
+            "anyOf": [
+              { "type": "null" },
+              { "$ref": "#/components/schemas/BillingCard" }
+            ]
           }
         },
-        "description": "Shared account wallet. Bonus funds core sends only; shared email draws purchased or starter credit. Amounts are exact USD decimal strings. Negative purchased or bonus balances retain refund debt and are not spendable."
+        "description": "A card form session. A person enters the card in the embeddable payment form mounted with client_secret and publishable_key, then reconciles. A complete setup makes that card the one default card. client_secret is present only while open."
       },
-      "CreateWalletCheckoutRequest": {
+      "CreateCreditPurchaseRequest": {
         "type": "object",
         "additionalProperties": false,
         "required": ["purchase_cents"],
@@ -12666,36 +12578,202 @@
             "type": "integer",
             "enum": [500, 1000, 2500, 5000, 10000]
           }
-        }
+        },
+        "description": "Buy one credit pack now with the default card. The amount is the explicit approval of the charge."
       },
-      "WalletCheckout": {
+      "CreditPurchase": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "status", "checkout_url"],
+        "required": [
+          "id",
+          "purchase_cents",
+          "credit_usd",
+          "status",
+          "failure",
+          "client_secret",
+          "card",
+          "publishable_key"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^checkout_[a-f0-9]{32}$" },
+          "id": {
+            "type": "string",
+            "pattern": "^credit_purchase_[a-f0-9]{32}$"
+          },
+          "purchase_cents": {
+            "type": "integer",
+            "enum": [500, 1000, 2500, 5000, 10000]
+          },
+          "credit_usd": {
+            "type": "string",
+            "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+            "maxLength": 40
+          },
           "status": {
             "type": "string",
-            "enum": ["open", "complete", "expired"]
+            "enum": ["processing", "requires_action", "paid", "failed"]
           },
-          "checkout_url": {
-            "type": ["string", "null"],
-            "format": "uri",
-            "maxLength": 4096
-          }
-        }
+          "failure": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": ["card_declined", "authentication_failed"]
+              },
+              { "type": "null" }
+            ]
+          },
+          "client_secret": {
+            "anyOf": [
+              { "type": "string", "minLength": 1, "maxLength": 512 },
+              { "type": "null" }
+            ]
+          },
+          "publishable_key": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^pk_(test|live)_[A-Za-z0-9]{1,250}$"
+              },
+              { "type": "null" }
+            ],
+            "description": "The public key the payment form uses with client_secret. Present only with client_secret."
+          },
+          "card": { "$ref": "#/components/schemas/BillingCard" }
+        },
+        "description": "A credit pack charged to the default card. paid means the credit is in the balance. requires_action means the card issuer asks the customer to confirm in the payment form using client_secret; reconcile afterwards. A failed purchase charged nothing; start a new one after updating the card."
       },
-      "ReconcileWalletCheckoutResult": {
+      "BillingInvoice": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["outcome", "account"],
+        "required": [
+          "id",
+          "kind",
+          "created_at",
+          "amount_usd",
+          "status",
+          "purchase_cents",
+          "items",
+          "period_start",
+          "period_end",
+          "document_url",
+          "document_kind"
+        ],
         "properties": {
-          "outcome": {
+          "id": { "type": "string", "minLength": 1, "maxLength": 255 },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "credit",
+              "automatic_top_up",
+              "recurring",
+              "welcome_credit"
+            ]
+          },
+          "created_at": { "type": "string", "format": "date-time" },
+          "amount_usd": {
             "type": "string",
-            "enum": ["applied", "unpaid", "ignored"]
+            "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+            "maxLength": 40
           },
-          "account": { "$ref": "#/components/schemas/BillingAccount" }
-        }
+          "status": {
+            "type": "string",
+            "enum": [
+              "paid",
+              "open",
+              "void",
+              "uncollectible",
+              "refunded",
+              "free"
+            ]
+          },
+          "purchase_cents": {
+            "anyOf": [
+              { "type": "integer", "enum": [500, 1000, 2500, 5000, 10000] },
+              { "type": "null" }
+            ]
+          },
+          "items": {
+            "type": "array",
+            "maxItems": 3,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "quantity"],
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "enum": ["team", "agency", "attribution", "project"]
+                },
+                "quantity": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 10025
+                }
+              }
+            }
+          },
+          "period_start": {
+            "anyOf": [
+              { "type": "string", "format": "date-time" },
+              { "type": "null" }
+            ]
+          },
+          "period_end": {
+            "anyOf": [
+              { "type": "string", "format": "date-time" },
+              { "type": "null" }
+            ]
+          },
+          "document_url": {
+            "anyOf": [
+              { "type": "string", "format": "uri", "maxLength": 4096 },
+              { "type": "null" }
+            ]
+          },
+          "document_kind": {
+            "anyOf": [
+              { "type": "string", "enum": ["invoice", "receipt"] },
+              { "type": "null" }
+            ]
+          }
+        },
+        "description": "One charge or credit grant. Credit purchases carry purchase_cents; recurring invoices carry their items and paid period. document_url downloads the invoice PDF or opens the receipt."
+      },
+      "BillingInvoiceCollection": {
+        "type": "object",
+        "description": "A page of invoices and receipts, newest first.",
+        "required": ["items"],
+        "properties": {
+          "items": {
+            "type": "array",
+            "maxItems": 100,
+            "items": { "$ref": "#/components/schemas/BillingInvoice" }
+          },
+          "next_cursor": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^[A-Za-z0-9_-]+$"
+          },
+          "page": { "$ref": "#/components/schemas/ListPageNumber" },
+          "page_size": { "$ref": "#/components/schemas/ListPageSize" },
+          "total": { "$ref": "#/components/schemas/ListTotal" }
+        },
+        "additionalProperties": false
+      },
+      "UpdateBillingReceiptEmailRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["email"],
+        "properties": {
+          "email": {
+            "anyOf": [
+              { "type": "null" },
+              { "$ref": "#/components/schemas/EmailAddress" }
+            ],
+            "description": "The receipt address, or null."
+          }
+        },
+        "description": "Where receipts and invoices are emailed. Null stops them."
       },
       "OrganizationProjection": {
         "type": "object",
@@ -17220,6 +17298,18 @@
         "enum": ["telegram", "slack", "email"],
         "description": "A provider-neutral delivery channel. Adding a member makes it representable; it does not claim that every deployment has registered an executable adapter."
       },
+      "ListTotal": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "How many records the list holds in total, not only on this page. Counted while the page was read, so a write landing between the count and the page can leave it a record or two out of step with `items`. That is noise on an inspection surface; it never changes which records a page addresses."
+      },
+      "EmailAddress": {
+        "type": "string",
+        "minLength": 3,
+        "maxLength": 254,
+        "pattern": "^(?=[^@]{1,64}@)(?!\\.)(?![^@]*\\.@)(?![^@]*\\.\\.)[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
+        "description": "Exactly one mailbox: an unquoted ASCII dot-atom local part plus a canonical lower-case IDNA domain. The comparison key preserves local-part bytes and case and lower-cases only the domain; dot, plus-tag, alias and provider equivalence are never inferred."
+      },
       "OrganizationRole": {
         "type": "string",
         "enum": ["admin", "member"],
@@ -17309,11 +17399,6 @@
           }
         ]
       },
-      "ListTotal": {
-        "type": "integer",
-        "minimum": 0,
-        "description": "How many records the list holds in total, not only on this page. Counted while the page was read, so a write landing between the count and the page can leave it a record or two out of step with `items`. That is noise on an inspection surface; it never changes which records a page addresses."
-      },
       "EmailDomainName": {
         "type": "string",
         "minLength": 4,
@@ -17591,13 +17676,6 @@
         "pattern": "^wb_pc1\\.pcred_[A-Za-z0-9_-]{21}[AQgw]\\.[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$",
         "description": "The exact one-time runtime bearer syntax. The final segment is canonical unpadded base64url for exactly 32 random secret bytes."
       },
-      "EmailAddress": {
-        "type": "string",
-        "minLength": 3,
-        "maxLength": 254,
-        "pattern": "^(?=[^@]{1,64}@)(?!\\.)(?![^@]*\\.@)(?![^@]*\\.\\.)[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
-        "description": "Exactly one mailbox: an unquoted ASCII dot-atom local part plus a canonical lower-case IDNA domain. The comparison key preserves local-part bytes and case and lower-cases only the domain; dot, plus-tag, alias and provider equivalence are never inferred."
-      },
       "ConnectionIdentity": {
         "type": "object",
         "description": "The identity a subscriber will see, named the way its provider names it. Carries the provider so a reader knows what kind of handle it is holding, rather than inferring it from the field's name. One shape for every provider: what differs between them is the handle's own format, which is stated here as a rule rather than as a separate type per provider.",
@@ -19092,7 +19170,7 @@
       "provider-capabilities-v1.schema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "$id": "https://whooshbang.flowxo.com/schemas/provider-capabilities-v1.schema.json",
-        "x-contract-version": "2.0.0-rc.6",
+        "x-contract-version": "2.0.0-rc.7",
         "title": "ProviderCapabilitiesV1",
         "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.",
         "type": "object",
@@ -19812,5 +19890,5 @@
       }
     }
   },
-  "x-contract-version": "2.0.0-rc.6"
+  "x-contract-version": "2.0.0-rc.7"
 }